CSS @layer order

.changeset/fix-css-layer-order.md

@@ -0,0 +1,5 @@
+---
+'layerchart': patch
+---
+
+fix(styles): Declare CSS cascade layer order so `components` reliably wins over `base` in production builds. Non-Tailwind consumers can `@import 'layerchart/core.css'` (included by framework presets).

.changeset/fix-tooltip-layer-typo.md

@@ -0,0 +1,5 @@
+---
+'layerchart': patch
+---
+
+fix(styles): Normalize mistyped `@layer component` → `@layer components` in Tooltip and Layer components.

docs/src/content/guides/styles.md

@@ -346,6 +346,30 @@ Many components support data-driven colors via the `c` (color) prop on `Chart`,
 
 :::
 
+## CSS layers
+
+LayerChart scopes its default styles into [CSS cascade layers](https://developer.mozilla.org/en-US/docs/Web/CSS/@layer) (`base` and `components`) so your own styles can reliably override them. Cascade-layer precedence is determined by the order in which each layer name is _first declared_ — not by where the rules appear — and later layers win. LayerChart relies on `base` being declared before `components` so that component defaults win over base defaults.
+
+If you use Tailwind, `@import 'tailwindcss'` emits the canonical `@layer theme, base, components, utilities;` order for you, so there's nothing to do. Likewise, the [framework presets](#third-party-framework-colors) (`layerchart/shadcn-svelte.css`, `layerchart/skeleton-4.css`, etc.) already include it.
+
+:::note
+**If you're not using Tailwind or a framework preset, declare the layer order explicitly.** Without it, the order falls to whatever sequence your bundler happens to emit the component styles in — which can differ between dev and production. A common symptom is `base` rules incorrectly taking precedence over `components` rules _only in a production build_.
+
+Import LayerChart's core stylesheet once, before using LayerChart:
+
+```css title="app.css"
+@import 'layerchart/core.css';
+```
+
+Or declare the order yourself:
+
+```css title="app.css"
+@layer theme, base, components, utilities;
+```
+
+An empty `@layer` statement just registers the priority order; the actual rules slot into it regardless of load order.
+:::
+
 ## Padding
 
 Chart padding controls the space between the chart edges and the data area. Use the `padding` prop on `Chart` to set `top`, `bottom`, `left`, and `right` values individually, or pass a single number to apply uniform padding on all sides.

packages/layerchart/src/lib/components/layers/Layer.svelte

@@ -77,7 +77,7 @@
 {/if}
 
 <style>
-  @layer component {
+  @layer components {
     :global(:where(.lc-debug-frame)) {
       --fill-color: color-mix(in oklab, var(--color-danger) 10%, transparent);
     }

packages/layerchart/src/lib/components/tooltip/Tooltip.svelte

@@ -492,7 +492,7 @@
 {/if}
 
 <style>
-  @layer component {
+  @layer components {
     :where(.lc-tooltip-root) {
       position: absolute;
       z-index: 50;

packages/layerchart/src/lib/components/tooltip/TooltipContext.svelte

@@ -818,7 +818,7 @@
 </div>
 
 <style>
-  @layer component {
+  @layer components {
     :where(.lc-tooltip-context-container) {
       position: absolute;
     }

packages/layerchart/src/lib/components/tooltip/TooltipHeader.svelte

@@ -108,7 +108,7 @@
 </div>
 
 <style>
-  @layer component {
+  @layer components {
     :where(.lc-tooltip-header) {
       font-weight: 600;
       white-space: nowrap;

packages/layerchart/src/lib/components/tooltip/TooltipItem.svelte

@@ -168,7 +168,7 @@
 </div>
 
 <style>
-  @layer component {
+  @layer components {
     :where(.lc-tooltip-item-root) {
       display: contents;
     }

packages/layerchart/src/lib/components/tooltip/TooltipList.svelte

@@ -23,7 +23,7 @@
 </div>
 
 <style>
-  @layer component {
+  @layer components {
     :where(.lc-tooltip-list) {
       display: grid;
       grid-template-columns: 1fr auto;

packages/layerchart/src/lib/components/tooltip/TooltipSeparator.svelte

@@ -22,7 +22,7 @@
 </div>
 
 <style>
-  @layer component {
+  @layer components {
     :where(.lc-tooltip-separator) {
       height: 1px;
       border-radius: 4px;

packages/layerchart/src/lib/styles/core.css

@@ -0,0 +1,17 @@
+/*
+  LayerChart core styles.
+
+  Declares the cascade layer order LayerChart's component styles rely on.
+  Precedence is determined by the order in which each layer name is *first*
+  declared (later layers win), so this must be established up front — otherwise
+  the order falls to whatever sequence the bundler emits component styles in,
+  which can differ between dev and production builds (e.g. `base` incorrectly
+  overriding `components` only in production).
+
+  When using Tailwind this is redundant (Tailwind emits the same order via
+  `@import 'tailwindcss'`) but harmless — re-declaring an existing order is a
+  no-op. Non-Tailwind consumers should import this file (`layerchart/core.css`)
+  before using LayerChart. The framework presets (shadcn-svelte, skeleton,
+  daisyui) import it for you.
+*/
+@layer theme, base, components, utilities;

packages/layerchart/src/lib/styles/daisyui-5.css

@@ -1,3 +1,5 @@
+@import './core.css';
+
 .lc-root-container {
   --color-surface-100: var(--color-base-100);
   --color-surface-200: var(--color-base-200);

packages/layerchart/src/lib/styles/shadcn-svelte.css

@@ -1,3 +1,5 @@
+@import './core.css';
+
 /*
   When NOT using shadcn-svelte Chart component.
   Not typically needed even when using built-in Chart, as defaults typically are sufficient

packages/layerchart/src/lib/styles/skeleton-3.css

@@ -1,3 +1,5 @@
+@import './core.css';
+
 .lc-root-container {
   --color-primary: var(--color-primary-500);
 

packages/layerchart/src/lib/styles/skeleton-4.css

@@ -1,3 +1,5 @@
+@import './core.css';
+
 .lc-root-container {
   --color-primary: var(--color-primary-500);