From fefc444d9a7ede1d5bc28716b914cc39904f3f65 Mon Sep 17 00:00:00 2001
From: Sean Lynch <techniq35@gmail.com>
Date: Thu, 2 Jul 2026 10:45:13 -0400
Subject: [PATCH 1/3] 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-css-layer-order.md               |  5 +++++
 packages/layerchart/src/lib/styles/core.css     | 17 +++++++++++++++++
 .../layerchart/src/lib/styles/daisyui-5.css     |  2 ++
 .../layerchart/src/lib/styles/shadcn-svelte.css |  2 ++
 .../layerchart/src/lib/styles/skeleton-3.css    |  2 ++
 .../layerchart/src/lib/styles/skeleton-4.css    |  2 ++
 6 files changed, 30 insertions(+)
 create mode 100644 .changeset/fix-css-layer-order.md
 create mode 100644 packages/layerchart/src/lib/styles/core.css

diff --git a/.changeset/fix-css-layer-order.md b/.changeset/fix-css-layer-order.md
new file mode 100644
index 000000000..a122e79a0
--- /dev/null
+++ b/.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).
diff --git a/packages/layerchart/src/lib/styles/core.css b/packages/layerchart/src/lib/styles/core.css
new file mode 100644
index 000000000..1b4a54a6f
--- /dev/null
+++ b/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;
diff --git a/packages/layerchart/src/lib/styles/daisyui-5.css b/packages/layerchart/src/lib/styles/daisyui-5.css
index fc917f070..f49efbd3d 100644
--- a/packages/layerchart/src/lib/styles/daisyui-5.css
+++ b/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);
diff --git a/packages/layerchart/src/lib/styles/shadcn-svelte.css b/packages/layerchart/src/lib/styles/shadcn-svelte.css
index 1f9f94a80..58d9cb431 100644
--- a/packages/layerchart/src/lib/styles/shadcn-svelte.css
+++ b/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
diff --git a/packages/layerchart/src/lib/styles/skeleton-3.css b/packages/layerchart/src/lib/styles/skeleton-3.css
index 4b2fadac4..404c3242a 100644
--- a/packages/layerchart/src/lib/styles/skeleton-3.css
+++ b/packages/layerchart/src/lib/styles/skeleton-3.css
@@ -1,3 +1,5 @@
+@import './core.css';
+
 .lc-root-container {
   --color-primary: var(--color-primary-500);
 
diff --git a/packages/layerchart/src/lib/styles/skeleton-4.css b/packages/layerchart/src/lib/styles/skeleton-4.css
index 4b2fadac4..404c3242a 100644
--- a/packages/layerchart/src/lib/styles/skeleton-4.css
+++ b/packages/layerchart/src/lib/styles/skeleton-4.css
@@ -1,3 +1,5 @@
+@import './core.css';
+
 .lc-root-container {
   --color-primary: var(--color-primary-500);
 

From b0f98272c894686ede969da1e17b8149fe8ccfe8 Mon Sep 17 00:00:00 2001
From: Sean Lynch <techniq35@gmail.com>
Date: Thu, 2 Jul 2026 10:45:23 -0400
Subject: [PATCH 2/3] =?UTF-8?q?fix(styles):=20Normalize=20mistyped=20`@lay?=
 =?UTF-8?q?er=20component`=20=E2=86=92=20`@layer=20components`=20in=20Tool?=
 =?UTF-8?q?tip=20and=20Layer=20components.?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .changeset/fix-tooltip-layer-typo.md                         | 5 +++++
 packages/layerchart/src/lib/components/layers/Layer.svelte   | 2 +-
 .../layerchart/src/lib/components/tooltip/Tooltip.svelte     | 2 +-
 .../src/lib/components/tooltip/TooltipContext.svelte         | 2 +-
 .../src/lib/components/tooltip/TooltipHeader.svelte          | 2 +-
 .../layerchart/src/lib/components/tooltip/TooltipItem.svelte | 2 +-
 .../layerchart/src/lib/components/tooltip/TooltipList.svelte | 2 +-
 .../src/lib/components/tooltip/TooltipSeparator.svelte       | 2 +-
 8 files changed, 12 insertions(+), 7 deletions(-)
 create mode 100644 .changeset/fix-tooltip-layer-typo.md

diff --git a/.changeset/fix-tooltip-layer-typo.md b/.changeset/fix-tooltip-layer-typo.md
new file mode 100644
index 000000000..c5c7591d5
--- /dev/null
+++ b/.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.
diff --git a/packages/layerchart/src/lib/components/layers/Layer.svelte b/packages/layerchart/src/lib/components/layers/Layer.svelte
index 15b8e5742..d05e23f3f 100644
--- a/packages/layerchart/src/lib/components/layers/Layer.svelte
+++ b/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);
     }
diff --git a/packages/layerchart/src/lib/components/tooltip/Tooltip.svelte b/packages/layerchart/src/lib/components/tooltip/Tooltip.svelte
index 1a94a13ba..7985a659d 100644
--- a/packages/layerchart/src/lib/components/tooltip/Tooltip.svelte
+++ b/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;
diff --git a/packages/layerchart/src/lib/components/tooltip/TooltipContext.svelte b/packages/layerchart/src/lib/components/tooltip/TooltipContext.svelte
index d2e6bfba3..6f7ac1cd8 100644
--- a/packages/layerchart/src/lib/components/tooltip/TooltipContext.svelte
+++ b/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;
     }
diff --git a/packages/layerchart/src/lib/components/tooltip/TooltipHeader.svelte b/packages/layerchart/src/lib/components/tooltip/TooltipHeader.svelte
index 9ab2f9aab..350c76679 100644
--- a/packages/layerchart/src/lib/components/tooltip/TooltipHeader.svelte
+++ b/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;
diff --git a/packages/layerchart/src/lib/components/tooltip/TooltipItem.svelte b/packages/layerchart/src/lib/components/tooltip/TooltipItem.svelte
index 184e7ccb1..b3d99d2fd 100644
--- a/packages/layerchart/src/lib/components/tooltip/TooltipItem.svelte
+++ b/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;
     }
diff --git a/packages/layerchart/src/lib/components/tooltip/TooltipList.svelte b/packages/layerchart/src/lib/components/tooltip/TooltipList.svelte
index c0fdf818d..42b18925f 100644
--- a/packages/layerchart/src/lib/components/tooltip/TooltipList.svelte
+++ b/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;
diff --git a/packages/layerchart/src/lib/components/tooltip/TooltipSeparator.svelte b/packages/layerchart/src/lib/components/tooltip/TooltipSeparator.svelte
index ce78ebb65..3d9c44754 100644
--- a/packages/layerchart/src/lib/components/tooltip/TooltipSeparator.svelte
+++ b/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;

From bdf636fa7af1256c02219ec61c58bcb63a1b9e03 Mon Sep 17 00:00:00 2001
From: Sean Lynch <techniq35@gmail.com>
Date: Thu, 2 Jul 2026 10:45:42 -0400
Subject: [PATCH 3/3] update styling docs regarding css layers

---
 docs/src/content/guides/styles.md | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/docs/src/content/guides/styles.md b/docs/src/content/guides/styles.md
index d4c7bf5b3..747cd64b0 100644
--- a/docs/src/content/guides/styles.md
+++ b/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.