srcdev-nuxt-components 9.1.55 → 9.1.56

package/.claude/skills/theming-override-default.md

@@ -2,255 +2,184 @@
 
 ## Overview
 
-The layer ships a default blue theme. This skill covers how to replace it with your own colour palette in a consuming Nuxt app — including adding a new colour scale and remapping all semantic tokens for light and dark modes.
+The layer ships a default blue theme. The recommended way to replace it is to generate your own
+named colour files — this gives you clean step variables (`--gold-09`, `--gold-04`) to reference
+in your theme overrides rather than raw oklch values. Setting `--theme-hue` and `--theme-chroma`
+drives the parametric ramp; the generated files give you named aliases for every step.
+
+For the full architecture see `theming-colour-ramps.md`.
 
 ## Prerequisites
 
-- Consuming app has `srcdev-nuxt-components` installed as a Nuxt layer
-- The consuming app has its own CSS entry point (e.g. `app/assets/styles/main.css`) registered in `nuxt.config.ts` via `css: [...]`
+- `srcdev-nuxt-components` installed as a Nuxt layer
+- A CSS entry point registered in `nuxt.config.ts` (e.g. `app/assets/styles/main.css`)
 
 ## Steps
 
-### 1. Create the colour scale file
+### 1. Create `ramps.config.mjs` in your project root
 
-Create `app/assets/styles/setup/02.colours/_gold.css` (or your colour name).
+Define the palettes you want. You can add brand-new ones, reuse a built-in name to replace
+the layer's values, or both. Consumer CSS loads after the layer, so your generated files win
+the cascade automatically — no `!important` needed:
 
-Colours use the `oklch` colour space. The scale runs from `00` (lightest) to `10` (darkest) — `00` is optional and only needed if you require a near-white tint.
+```js
+// ramps.config.mjs
+export const ramps = {
+  // New palette — adds --gold-00..10 and --palette-gold-* vars
+  gold: { hue: 85, chroma: 0.20 },
 
-```css
-:where(html) {
-  --gold-00: oklch(98% 0.01 85);
-  --gold-01: oklch(94% 0.04 85);
-  --gold-02: oklch(88% 0.09 85);
-  --gold-03: oklch(80% 0.14 85);
-  --gold-04: oklch(72% 0.18 85);
-  --gold-05: oklch(64% 0.20 85);
-  --gold-06: oklch(56% 0.19 85);
-  --gold-07: oklch(48% 0.17 85);
-  --gold-08: oklch(40% 0.15 85);
-  --gold-09: oklch(32% 0.12 85);
-  --gold-10: oklch(25% 0.09 85);
-}
+  // Override a built-in — your generated _blue.css replaces the layer's --blue-00..10
+  // blue: { hue: 240, chroma: 0.18 },
+
+  // Override the error/invalid palette — all red error states use your values
+  // red: { hue: 15, chroma: 0.26 },
+
+  // Optional — add hue drift (colour rotates linearly across the 11 steps):
+  // copper: { hue: 45, chroma: 0.21, drift: -15 },
+};
 ```
 
-Adjust the hue angle (third value) to taste — `85` is a warm gold. Use an oklch colour picker to preview the scale.
+Choose your hue and peak chroma using [oklch.com](https://oklch.com). The `chroma` value controls
+saturation at the peak step (06); typical range is 0.12–0.25.
 
-### 2. Create the colours index
+Hue quick reference:
 
-Create `app/assets/styles/setup/02.colours/index.css` and import your scale:
+| Range   | Colour         |
+|---------|----------------|
+| 0–30    | Red / pink     |
+| 30–70   | Orange / amber |
+| 70–100  | Yellow / gold  |
+| 100–160 | Green          |
+| 220–270 | Blue           |
+| 270–310 | Violet         |
 
-```css
-@import "./_gold";
+### 2. Add the generator to `package.json`
+
+The script lives in the layer's `node_modules` — no copying required. Prepend it to `dev`,
+`build`, and `generate` so generated CSS never drifts out of sync with `ramps.config.mjs`:
+
+```json
+"scripts": {
+  "generate:ramps": "node node_modules/srcdev-nuxt-components/scripts/generate-consumer-ramps.mjs",
+  "dev":      "npm run generate:ramps && nuxt dev",
+  "build":    "npm run generate:ramps && nuxt build",
+  "generate": "npm run generate:ramps && nuxt generate"
+}
 ```
 
-### 3. Create the light theme override
+Also add it to `postinstall` so it runs automatically after every `npm install`:
 
-Create `app/assets/styles/setup/03.theming/default/_light.css`.
+```json
+"postinstall": "nuxt prepare && npm run generate:ramps && npm run setup:claude"
+```
 
-This file uses `:where(html)` and maps semantic tokens to your colour scale. Copy the full token list from the layer and replace `--blue-*` references with `--gold-*`:
+> **Do not manually edit generated files.** They carry a `/* GENERATED */` comment at the top
+> and are overwritten every time the generator runs. All changes belong in `ramps.config.mjs`.
 
-```css
-:where(html) {
-  /* Color scale */
-  --colour-theme-1: var(--gold-01);
-  --colour-theme-2: var(--gold-02);
-  --colour-theme-3: var(--gold-03);
-  --colour-theme-4: var(--gold-04);
-  --colour-theme-5: var(--gold-05);
-  --colour-theme-6: var(--gold-06);
-  --colour-theme-7: var(--gold-07);
-  --colour-theme-8: var(--gold-08);
-  --colour-theme-9: var(--gold-09);
-  --colour-theme-10: var(--gold-10);
-
-  /* Body */
-  --page-bg: var(--slate-00);
-  --colour-text-default: var(--slate-09);
-  --colour-text-accent: var(--gold-09);
-  --colour-text-eyebrow: var(--gold-09);
-
-  /* Links */
-  --colour-link-default: var(--gold-10);
-  --colour-link-hover: var(--gold-09);
-
-  /* Form inputs */
-  --theme-input-surface: var(--slate-00);
-  --theme-input-surface-hover: var(--slate-01);
-  --theme-input-border: var(--gold-06);
-  --theme-input-border-hover: var(--gold-05);
-  --theme-input-border-focus: var(--gold-04);
-  --theme-input-outline: transparent;
-  --theme-input-outline-focus: var(--gold-04);
-  --theme-input-visible-outline: var(--gold-10);
-  --theme-focus-visible-shadow: 0 0 0 2px var(--gold-02);
-  --theme-input-placeholder: var(--slate-05);
-  --theme-input-text-color-normal: var(--slate-09);
-
-  /* Checkbox / radio */
-  --theme-checkbox-symbol-color: var(--gold-08);
-  --theme-checkbox-symbol-surface: var(--theme-input-surface);
-  --theme-checkbox-decorator-color: var(--gold-09);
-
-  /* Toggle */
-  --theme-toggle-symbol-color-default: var(--gold-00);
-  --theme-toggle-symbol-color-checked: var(--gold-08);
-
-  /* Buttons — primary */
-  --theme-button-primary-surface: var(--gold-09);
-  --theme-button-primary-surface-hover: var(--gold-08);
-  --theme-button-primary-surface-active: var(--gold-07);
-  --theme-button-primary-border: var(--gold-09);
-  --theme-button-primary-border-active: var(--gold-09);
-  --theme-button-primary-outline: var(--gold-01);
-  --theme-button-primary-outline-active: var(--gold-07);
-  --theme-button-primary-text: var(--gold-00);
-  --theme-button-primary-text-hover: var(--gold-00);
-
-  /* Buttons — secondary */
-  --theme-button-secondary-surface: transparent;
-  --theme-button-secondary-surface-hover: var(--gold-01);
-  --theme-button-secondary-surface-active: var(--gold-01);
-  --theme-button-secondary-border: var(--gold-09);
-  --theme-button-secondary-border-active: var(--gold-09);
-  --theme-button-secondary-outline: var(--gold-09);
-  --theme-button-secondary-outline-active: var(--gold-09);
-  --theme-button-secondary-text: var(--gold-09);
-  --theme-button-secondary-text-hover: var(--gold-09);
-
-  /* Buttons — tertiary */
-  --theme-button-tertiary-surface: var(--slate-01);
-  --theme-button-tertiary-text: var(--gold-09);
-  --theme-button-tertiary-border-active: var(--gold-09);
-  --theme-button-tertiary-outline-active: var(--gold-09);
-}
+### 3. Run the generator
+
+```bash
+npm run generate:ramps
 ```
 
-### 4. Create the dark theme override
+Produces in `app/assets/styles/setup/02.colours/`:
 
-Create `app/assets/styles/setup/03.theming/default/_dark.css`.
+- `_gold.css` — `--gold-00` … `--gold-10` (literal oklch values, using the layer's lightness/chroma curve)
+- `_palette-params.css` — `--palette-gold-hue`, `--palette-gold-chroma`
 
-Selector is `:where(html.dark)`. Dark mode typically inverts the scale direction — light values for text/borders, dark values for backgrounds:
+### 4. Import the generated files
+
+Create `app/assets/styles/setup/02.colours/index.css`:
 
 ```css
-:where(html.dark) {
-  /* Color scale */
-  --colour-theme-1: var(--gold-01);
-  --colour-theme-2: var(--gold-02);
-  --colour-theme-3: var(--gold-03);
-  --colour-theme-4: var(--gold-04);
-  --colour-theme-5: var(--gold-05);
-  --colour-theme-6: var(--gold-06);
-  --colour-theme-7: var(--gold-07);
-  --colour-theme-8: var(--gold-08);
-  --colour-theme-9: var(--gold-09);
-  --colour-theme-10: var(--gold-10);
-
-  /* Body */
-  --page-bg: var(--slate-08);
-  --colour-text-default: var(--slate-01);
-  --colour-text-accent: var(--gold-05);
-  --colour-text-eyebrow: var(--gold-05);
-
-  /* Links */
-  --colour-link-default: var(--gold-03);
-  --colour-link-hover: var(--gold-04);
-
-  /* Form inputs */
-  --theme-input-surface: var(--slate-10);
-  --theme-input-surface-hover: var(--slate-09);
-  --theme-input-border: var(--gold-06);
-  --theme-input-border-hover: var(--gold-05);
-  --theme-input-border-focus: var(--gold-04);
-  --theme-input-outline: var(--gold-06);
-  --theme-input-outline-focus: var(--gold-04);
-  --theme-input-visible-outline: var(--gold-04);
-  --theme-focus-visible-shadow: 0 0 0 2px var(--gold-02);
-  --theme-input-placeholder: var(--slate-04);
-  --theme-input-text-color-normal: var(--slate-01);
-
-  /* Checkbox / radio */
-  --theme-checkbox-symbol-surface: var(--theme-input-surface);
-  --theme-checkbox-symbol-color: var(--gold-02);
-  --theme-checkbox-decorator-color: var(--gold-02);
-
-  /* Buttons — primary */
-  --theme-button-primary-border: var(--gold-07);
-  --theme-button-primary-border-active: var(--gold-07);
-  --theme-button-primary-text: var(--gold-00);
-  --theme-button-primary-text-hover: var(--gold-00);
-
-  /* Buttons — secondary */
-  --theme-button-secondary-surface: var(--gold-01);
-  --theme-button-secondary-border-active: var(--gold-01);
-  --theme-button-secondary-text: var(--gold-09);
-
-  /* Buttons — tertiary */
-  --theme-button-tertiary-surface: transparent;
-  --theme-button-tertiary-text: var(--gold-01);
-  --theme-button-tertiary-border-active: var(--gold-01);
-  --theme-button-tertiary-outline-active: var(--gold-09);
-}
+@import "./_palette-params";
+@import "./_gold";
 ```
 
-### 5. Create the theming index
+### 5. Set the palette as the theme default
 
-Create `app/assets/styles/setup/03.theming/default/index.css`:
+Create `app/assets/styles/setup/03.theming/_default.css`:
 
 ```css
-@import "./_light";
-@import "./_dark";
+:where(html) {
+  --theme-hue:    var(--palette-gold-hue);
+  --theme-chroma: var(--palette-gold-chroma);
+
+  /* Page-level tokens — readable named steps, not raw oklch */
+  --page-bg: light-dark(var(--slate-00), var(--slate-08));
+  --colour-text-default:  light-dark(var(--slate-09), var(--slate-01));
+  --colour-text-accent:   light-dark(var(--gold-09), var(--gold-04));
+  --colour-text-eyebrow:  light-dark(var(--gold-09), var(--gold-04));
+}
 ```
 
+Only `--theme-hue` and `--theme-chroma` are strictly required — all component tokens update
+automatically from there. Add page-level overrides only for tokens that reference the old blue
+palette by name.
+
 ### 6. Create the setup index
 
-Create `app/assets/styles/setup/index.css` that imports colours then theming (order matters — colours must be defined before theming references them):
+`app/assets/styles/setup/index.css`:
 
 ```css
 @import "./02.colours/";
-@import "./03.theming/default/";
+@import "./03.theming/_default.css";
 ```
 
 ### 7. Wire up the CSS entry point
 
-In your consuming app's `app/assets/styles/main.css` (or equivalent), import your setup after the layer's styles are applied:
+`app/assets/styles/main.css`:
 
 ```css
 @import "./setup/";
 ```
 
-Then register it in `nuxt.config.ts`:
+Registered in `nuxt.config.ts`:
 
 ```ts
 export default defineNuxtConfig({
   extends: "srcdev-nuxt-components",
-  css: ["~/assets/styles/main.css"],
+  css: [
+    "srcdev-nuxt-components/app/assets/styles/main.css",
+    "~/assets/styles/main.css",
+  ],
 });
 ```
 
-The consuming app's CSS loads after the layer's, so your token overrides win via the cascade.
+## How it works
+
+The layer's `theme-ramp.css` declares the formula on `:where(html, [data-theme], [data-invalid])`.
+When your override sets `--theme-hue`/`--theme-chroma` on `:where(html)`, every `--colour-theme-*`
+step recalculates to your palette. Semantic slots (`--theme-surface`, `--theme-text`, etc.) are
+declared on that same selector using `light-dark()` — light/dark mode continues to work without
+any extra declarations.
+
+The generated `_gold.css` gives you a named alias for each step (`--gold-09` etc.) so your
+page-level token values stay readable. The values match what the formula would produce for
+that hue/chroma pair.
+
+## What you do NOT need to do
+
+- Define `--colour-theme-0` through `--colour-theme-10` — the formula handles it
+- Redeclare `--theme-surface`, `--theme-border`, `--theme-ring` etc. — they auto-update
+- Write separate light/dark files — use `light-dark()` in a single file
+- Override any button or input component tokens — they all consume semantic slots
 
 ## rem sizing
 
-`html` has `font-size: 62.5%` set in `app/assets/styles/setup/01.config/_head.css`, making `1rem = 10px`. Use this when writing any rem values in your theme or component styles:
+`html` has `font-size: 62.5%` set by the layer, making `1rem = 10px`:
 
 | px   | rem    |
-| ---- | ------ |
+|------|--------|
 | 8px  | 0.8rem |
 | 12px | 1.2rem |
 | 16px | 1.6rem |
 | 24px | 2.4rem |
 | 32px | 3.2rem |
 
-## Token reference
-
-See `CONSUMER-STYLING.md` in the layer package root for the full list of available tokens grouped
-by category. This is the authoritative reference when deciding which tokens to include in your
-override files.
-
 ## Notes
 
-- The `--slate-*` scale comes from the layer and does not need to be redefined — keep all neutral/background tokens pointing at `--slate-*`.
-- Only redefine tokens that change. You do not need to copy tokens that stay identical between layer and your override.
-- Dark mode is triggered by the `dark` class on `<html>`. The layer handles toggling this via `data-color-scheme` and the colour scheme store.
-- If you need additional component-specific tokens (e.g. `--stepper-list-*`, `--glass-panel-*`), add them to `_light.css` and `_dark.css` following the same pattern.
-- Use an oklch colour picker (e.g. oklch.com) to build and preview your scale before committing values.
+- `--slate-*` neutrals ship with the layer — no need to redefine for page backgrounds/text
+- To add a custom `[data-theme]` variant using your generated palette, see `theming-colour-ramps.md`
+- The `warning` theme overrides `--theme-surface` and `--theme-surface-hover` to lighter steps (5/4 and 7/5) so warning buttons read as warm/alert rather than the default dark surface — this pattern is available for any custom theme that needs a non-default surface step
+- `--theme-accent` (step 5/4) is separate from `--theme-surface` (step 7/9) — accent is for decorative strips in `DisplayPrompt` and `DisplayToast`; surface is for interactive elements like buttons

package/.claude/skills/theming-partial-override.md

@@ -2,130 +2,143 @@
 
 ## Overview
 
-Use this skill when you need to override a specific category of tokens (e.g. form inputs, buttons,
-colours) without replacing the entire default theme. The full token reference is in
-`CONSUMER-STYLING.md` at the root of the layer package.
+Use this skill when you need to tweak a specific colour role (page background, text, buttons,
+inputs) without replacing the entire default theme. For a full palette swap see
+`theming-override-default.md`. For the full architecture see `theming-colour-ramps.md`.
 
 ## How it works
 
 All library tokens are declared inside `@layer theming`. Any CSS written outside a layer wins
-automatically — no `!important` or specificity tricks required. Override files just need to be
-imported **after** the layer styles.
+automatically — no `!important` or specificity tricks required. Override files just need to load
+after the layer styles.
+
+## Semantic slots — the tokens to override
+
+All themed components share a 9-slot vocabulary. Overriding these affects buttons, inputs,
+prompts, and toasts simultaneously:
+
+| Token                   | Default (light → dark)     | Role                              |
+|-------------------------|----------------------------|-----------------------------------|
+| `--theme-surface`       | `--colour-theme-7` / `9`   | Filled button/chip surface        |
+| `--theme-surface-hover` | `--colour-theme-9` / `7`   | Hover state of filled surface     |
+| `--theme-accent`        | `--colour-theme-5` / `4`   | Decorative accent strip (prompt/toast left edge) |
+| `--theme-surface-subtle`| `--colour-theme-1` / `9`   | Subtle body bg for prompt/toast, outline element hover |
+| `--theme-border`        | `--colour-theme-6` / `5`   | Input/card border                 |
+| `--theme-border-focus`  | `--colour-theme-4` / `3`   | Focused border                    |
+| `--theme-ring`          | `--colour-theme-1` / `9`   | Focus ring (outline)              |
+| `--theme-on-surface`    | `--colour-theme-0`         | Text/icon on filled surface       |
+| `--theme-text`          | `--colour-theme-9` / `2`   | Text on page, outline element text|
+
+Input-specific tokens:
+
+| Token                           | Role                      |
+|---------------------------------|---------------------------|
+| `--theme-input-surface`         | Input field background    |
+| `--theme-input-surface-hover`   | Input hover background    |
+| `--theme-input-text-color-normal` | Input text colour       |
+| `--theme-input-placeholder`     | Placeholder text colour   |
+| `--theme-checkbox-symbol-surface` | Checkbox surface        |
+
+Page-level tokens:
+
+| Token                    | Role                  |
+|--------------------------|-----------------------|
+| `--page-bg`              | Page background       |
+| `--colour-text-default`  | Body text             |
+| `--colour-text-accent`   | Accent / heading text |
+| `--colour-text-eyebrow`  | Eyebrow text          |
 
 ## Steps
 
 ### 1. Create your override file
 
-Create a CSS file for the category you want to override. Place it anywhere in your app's assets —
-`app/assets/styles/` is conventional.
+#### Shift the default palette hue (amber instead of blue)
 
-**Example: form input overrides**
+```css
+/* app/assets/styles/overrides.css */
+:where(html) {
+  --theme-hue: 75;      /* amber */
+  --theme-chroma: 0.19;
+}
+```
+
+#### Override button surface only
 
 ```css
-/* app/assets/styles/form-overrides.css */
-:root {
-  --theme-input-surface: oklch(0.98 0.005 250);
-  --theme-input-border: oklch(0.45 0.08 270);
-  --theme-input-border-focus: oklch(0.55 0.18 280);
-  --theme-input-outline-focus: oklch(0.55 0.18 280);
-  --theme-focus-visible-shadow: 0 0 0 2px oklch(0.80 0.12 280);
-  --theme-input-placeholder: oklch(0.60 0.02 255);
-  --theme-input-text-color-normal: oklch(0.20 0.02 255);
+/* Make primary buttons darker/more saturated (step-7/9 defaults, step-9/7 hover) */
+:where(html) {
+  --theme-surface:       light-dark(oklch(48% 0.18 85), oklch(32% 0.20 85));
+  --theme-surface-hover: light-dark(oklch(32% 0.18 85), oklch(48% 0.20 85));
 }
 ```
 
-**Example: add a red colour scale and remap accent tokens**
+#### Override input colours only
 
 ```css
-/* app/assets/styles/red-palette.css */
-:root {
-  /* Red scale — 00 (lightest) to 10 (darkest) */
-  --red-00: oklch(0.99 0.005 20);
-  --red-01: oklch(0.96 0.020 20);
-  --red-02: oklch(0.90 0.055 20);
-  --red-03: oklch(0.82 0.105 20);
-  --red-04: oklch(0.72 0.155 20);
-  --red-05: oklch(0.62 0.185 20);
-  --red-06: oklch(0.53 0.185 20);
-  --red-07: oklch(0.44 0.165 20);
-  --red-08: oklch(0.36 0.140 20);
-  --red-09: oklch(0.28 0.110 20);
-  --red-10: oklch(0.20 0.080 20);
-
-  /* Remap semantic accent tokens to red */
-  --colour-text-accent: var(--red-08);
-  --colour-text-eyebrow: var(--red-08);
-  --colour-link-default: var(--red-09);
-  --colour-link-hover: var(--red-08);
+:where(html) {
+  --theme-input-surface:           light-dark(oklch(0.99 0 0), oklch(0.12 0.01 255));
+  --theme-input-text-color-normal: light-dark(oklch(0.20 0.01 255), oklch(0.95 0.01 255));
+  --theme-input-placeholder:       light-dark(oklch(0.60 0.01 255), oklch(0.40 0.01 255));
 }
 ```
 
-**Example: button overrides only**
+#### Override page-level tokens for a different neutral palette
 
 ```css
-/* app/assets/styles/button-overrides.css */
-:root {
-  --theme-button-primary-surface: oklch(0.55 0.20 280);
-  --theme-button-primary-surface-hover: oklch(0.48 0.22 280);
-  --theme-button-primary-surface-active: oklch(0.42 0.22 280);
-  --theme-button-primary-text: oklch(1 0 0);
-  --theme-button-primary-text-hover: oklch(1 0 0);
+:where(html) {
+  --page-bg:             light-dark(oklch(0.98 0 0), oklch(0.10 0 0));
+  --colour-text-default: light-dark(oklch(0.20 0 0), oklch(0.93 0 0));
+  --colour-text-accent:  light-dark(oklch(0.30 0.16 85), oklch(0.65 0.18 85));
 }
 ```
 
 ### 2. Register it in nuxt.config.ts
 
-Import your override file **after** the layer styles:
-
 ```ts
 export default defineNuxtConfig({
   extends: "srcdev-nuxt-components",
   css: [
-    "~/assets/styles/form-overrides.css",   // or whichever file(s) you created
+    "srcdev-nuxt-components/app/assets/styles/main.css",
+    "~/assets/styles/overrides.css",
   ],
 });
 ```
 
-The layer's own CSS loads via the `extends` mechanism before app CSS, so your unlayered overrides
-always win.
+The layer's own CSS loads via `extends` before app CSS, so your unlayered overrides always win.
 
-### 3. Dark mode (optional)
+## Scoped overrides (section or component level)
 
-If you need dark mode variants of your overrides, add them in the same file using the `html.dark`
-class selector:
+To restrict an override to a specific section, scope to a wrapper class instead of `:where(html)`:
 
 ```css
-:root {
-  --theme-input-surface: oklch(0.98 0.005 250);
+.pricing-section {
+  /* Entire section uses green theme */
+  --theme-hue: 157;
+  --theme-chroma: 0.19;
 }
 
-:where(html.dark) {
-  --theme-input-surface: oklch(0.15 0.02 255);
+.hero-cta {
+  /* Just these buttons use a different surface colour */
+  --theme-surface:       light-dark(oklch(48% 0.16 85), oklch(32% 0.18 85));
+  --theme-surface-hover: light-dark(oklch(32% 0.14 85), oklch(48% 0.16 85));
 }
 ```
 
-## Scoped overrides (section or component level)
+## Overriding a specific component theme
 
-To restrict an override to a specific section of the page, scope to a wrapper class instead of
-`:root`:
+To change how `data-theme="success"` looks without affecting other themes:
 
 ```css
-.pricing-section {
-  --theme-button-primary-surface: oklch(0.55 0.20 140);  /* green for pricing CTA */
+[data-theme="success"] {
+  /* Shift to teal instead of green */
+  --theme-hue: 185;
+  --theme-chroma: 0.17;
 }
 ```
 
-## Token reference
-
-See `CONSUMER-STYLING.md` in the layer package for the full list of available tokens, grouped
-by category (typography, colours, form inputs, buttons, checkboxes, toggle, glass panel,
-StepperList).
-
 ## Notes
 
-- Only override the tokens you actually need — unset tokens fall back to layer defaults.
-- Use oklch for all colour values. Use an oklch colour picker (e.g. oklch.com) to build scales.
-- For a full palette replacement (replacing the entire default theme), use
-  `theming-override-default.md` instead.
-- `--slate-*` neutral tokens come from the layer and do not need to be redefined unless you
-  genuinely want different neutrals.
+- Only override the tokens you actually need — everything else falls back to layer defaults
+- Use `light-dark()` in a single rule rather than separate `:where(html.light)` / `:where(html.dark)` blocks — the layer's `color-scheme` infrastructure handles mode switching
+- `--slate-*` neutral tokens come from the layer and do not need to be redefined unless you genuinely want different neutrals
+- For a full palette replacement (changing the layer default), use `theming-override-default.md` instead