srcdev-nuxt-components 9.5.3 → 9.5.5

package/.claude/skills/components/section-parallax.md

@@ -57,7 +57,7 @@ The component sets:
 - `background-position: var(--section-parallax-background-position, center)`
 - `background-size: var(--section-parallax-background-size, cover)`
 - `min-height: var(--section-parallax-min-height, 100svh)`
-- `background-color: var(--section-parallax-background-colour, light-dark(var(--slate-01), var(--slate-08)))` (visible if image fails to load)
+- `background-color: var(--section-parallax-background-colour, var(--slate-01))` (visible if image fails to load)
 
 Inside `@media (hover: hover) and (pointer: fine) { @supports (background-attachment: fixed) { ... } }`:
 

package/.claude/skills/components/select-menu.md

@@ -17,7 +17,7 @@ open between picks.
 
 ## Components
 
-### SelectMenu
+### SelectMenu props
 
 | Prop | Type | Default | Notes |
 |---|---|---|---|
@@ -29,9 +29,10 @@ open between picks.
 | `showChevron` | `boolean` | `true` | Show the trailing chevron in the trigger. |
 | `multiple` | `boolean` | `false` | Allow selecting more than one option. Each option gets a checkbox indicator, `v-model` becomes an array, and picking an option leaves the popover open so more can be toggled. Trigger icon is not shown when `true` (no single option to represent). |
 | `showSelectionInTrigger` | `boolean` | `false` | Multiple mode only. When `true`, the trigger text updates to a comma-separated list of the currently checked options instead of staying fixed on `placeholder`/`label`. No effect outside `multiple`. |
+| `inputVariant` | `InputUiVariant` | `"normal"` | Trigger border style, same prop as `InputSelect`: `"normal"` (bordered box) or `"underlined"` (bottom border only, square corners), added as a class on the root. `"outlined"` has no CSS, same as the `05.forms` inputs. |
 | `styleClassPassthrough` | `string \| string[]` | `[]` | Extra classes on the root `<div>`. |
 
-**v-model**
+#### v-model
 
 `defineModel<string | number | (string | number)[] | undefined>({ default: undefined })` — the
 selected value(s). In single-select mode (default) it's the one selected option's `value`, or
@@ -44,7 +45,7 @@ is optional by design (see that rule's `defineModel` gap noted in the repo's led
 docs). For several independent single-select categories, place multiple `SelectMenu` instances
 side by side rather than using `multiple` on one instance — see the "Filter bar" section below.
 
-**Type import**
+#### Type import
 
 ```ts
 import type { SelectMenuOption } from "~/types/components/select-menu";
@@ -170,8 +171,11 @@ Quick reference:
 
 ## Notes
 
-- **Popover API + CSS anchor positioning** — same mechanism as `ActionMenu`. Broadly supported
-  (Chrome 114+, Firefox 125+, Safari 17+). No polyfill is included.
+- **Popover API + CSS anchor positioning** — same mechanism as `ActionMenu`. The Popover API is
+  broadly supported (Chrome 114+, Firefox 125+, Safari 17+), but CSS anchor positioning is much
+  newer (Chromium 125+, Safari 26+), and without it the popover isn't placed under the trigger. No
+  polyfill or fallback is included, so check support before using this where older devices
+  matter; a native `<select>` (`InputSelect`) is the safer choice there.
 - **Left-aligned popover** (`left: anchor(left)`) — unlike `ActionMenu` which right-aligns. Matches
   native `<select>` dropdown behaviour. Flips above the trigger near the bottom of the viewport.
 - **Keyboard navigation** follows the WAI-ARIA listbox pattern: `ArrowDown`/`ArrowUp` move between
@@ -184,6 +188,16 @@ Quick reference:
   `[role="option"]` if one exists (in `multiple` mode, the first checked item), otherwise the first
   option (unlike `ActionMenu`, which always focuses the first item since it has no selection state).
 - **`aria-multiselectable="true"`** is set on the listbox only when `multiple` is `true`.
+- **Selected rows are tinted** via `[aria-selected="true"]` (`--select-menu-item-surface-selected`,
+  default `--theme-surface-subtle`), in both single and multiple mode. Hover/focus is declared after
+  it at equal specificity, so the hover surface still shows on a selected row. Selected text colour,
+  font weight and border colour have their own `-selected` tokens falling back to the resting ones.
+  The row border width (`--select-menu-item-border-width`, default `0`) applies to every row with a
+  transparent resting colour, so a selected border never shifts layout. A hidden `::after` carrying
+  `data-label` in the selected weight reserves the label column's width, so a bolder selected
+  weight doesn't resize the popover. Hover/focus has `-text-color-hover` and `-border-hover`, which
+  fall back to the row's *current* state (selected or resting), not always to resting. There's no
+  hover font-weight token on purpose: the width reserve only covers one alternate weight.
 - **Chevron rotation is pure CSS** via `:has(.select-menu-popover:popover-open)` on the root — no
   JS state drives the visual. `isOpen` is still tracked internally, but only to set `aria-expanded`
   on the trigger.

package/.claude/skills/components/triple-toggle-switch.md

@@ -28,7 +28,7 @@ for that for a theme switch; use `TripleToggleSwitch` directly for any other thr
 | `name` | `string` | `"triple-toggle-switch"` | Shared radio `name`. Give each instance on a page its own. |
 | `aria-label` | `string` | `""` | Accessible name for the `role="radiogroup"`. Omitted from the DOM when empty. Always pass one. |
 | `theme` | `FormUiTheme` | `"default"` | Rendered as `data-theme`. |
-| `step-animation-duration` | `string` | `"250ms"` | Marker slide duration. Ignored under `prefers-reduced-motion`. |
+| `step-animation-duration` | `string` | `"250ms"` | Marker slide duration; also times the icon colour swap (see Behaviour). Ignored under `prefers-reduced-motion`. |
 | `style-class-passthrough` | `string \| string[]` | `[]` | Classes on the root. |
 
 Option `id`s are used as element ids (and as a class on each icon), so they must be unique on the
@@ -66,6 +66,12 @@ const options = ref<IFormMultipleOptions>({
 - The marker is measured from the first option's width on mount and fades in after ~250ms. It
   isn't re-measured on resize, so changing the icon-size/padding tokens after mount (e.g. toggling
   a class) leaves the marker at its old size.
+- Icon colour swaps are timed to the marker: the newly active icon waits half of
+  `stepAnimationDuration`, then fades to the active colour over the other half, so it lands as the
+  marker arrives rather than turning white on the bare track. The previous icon fades back straight
+  away. The marker takes the same time whatever the distance, so no per-index delay is needed.
+- Option circles are sized by their content (1em icon + equal padding) with `place-items: center`,
+  not `aspect-ratio`; older iPad Safari mis-centred the icons under the `aspect-ratio` version.
 - Marker gradients only exist for the values `system`, `light` and `dark`; other values get the
   plain `--triple-toggle-switch-marker-surface` background.
 

package/.claude/skills/composable-colour-scheme.md

@@ -59,6 +59,8 @@ The three valid values are:
 | `"light"` | Forces light theme regardless of OS setting |
 | `"dark"` | Forces dark theme regardless of OS setting |
 
+The attribute only switches schemes; the layer ships light colour values only. The app supplies the dark values, see `theming-dark-mode.md`.
+
 ## Notes
 
 - `onMounted` is used to read `localStorage` — `currentColourScheme` is always `"auto"` during SSR and hydrates client-side. Do not read it server-side.

package/.claude/skills/index.md

@@ -32,10 +32,12 @@ Each skill is a single markdown file named `<area>-<task>.md`.
 ├── theming-override-default.md      — replace the entire default theme with a custom palette (set --theme-hue/--theme-chroma)
 ├── theming-partial-override.md      — override a specific colour token category (palette, buttons, inputs) without a full theme replacement
 ├── theming-form-geometry-tokens.md  — non-colour form/button/input tokens (padding, border-radius, gaps): full inventory, why partial override doesn't need duplicating the source files
-├── theming-component-token-pattern.md — standard shape for overridable component colours: public token + inline fallback, no bare var()/no private-only indirection; the three tiers (theme slots / cross-component families / component-scoped); rollout status
+├── theming-component-token-pattern.md — standard shape for overridable component colours: public token + inline fallback, no bare var()/no private-only indirection; the three tiers (theme slots / cross-component families / component-scoped); line-clamp tokens for overflowing text; rollout status
+├── theming-dark-mode.md            — add a dark scheme in a consumer app (layer is light-only): enable plumbing, full dark token set without light-dark(), light-dark() alternative, light-only pinning
 ├── colour-scheme-disable.md         — disable light/dark scheme support in a consumer app
 ├── component-dynamic-slots.md        — named dynamic slots ($slots iteration) vs indexed dynamic slots (itemCount pattern)
 ├── component-naming.md               — Control/Field naming convention (InputNumber + InputNumberField, no Core/Default/WithLabel suffixes), rename procedure, backlog with consumer usage
+├── component-compliance-checklist.md — definition of done for every component (tier, props, tokens, CONSUMER-STYLING.md layout, tests, story, skill doc, snippet, a11y, i18n, naming, pitfalls); shared by /new-component and /migrate-component
 ├── component-local-style-override.md — overriding a component from a consumer app: public tokens on an ancestor, unscoped page blocks, per-instance class/passthrough, consumer `<style scoped>` + :deep() rules, never @layer overrides
 ├── component-prop-driven-container-layout.md — vary CSS grid layout inside @container queries using data-* attribute selectors
 ├── page-transitions.md               — pageTransition/layoutTransition setup; the self-wrapped <NuxtLayout> + layout:false anti-pattern that pulls the header/nav into the transition boundary; fade CSS
@@ -80,6 +82,7 @@ Each skill is a single markdown file named `<area>-<task>.md`.
     ├── page-hero-highlights.md — PageHeroHighlights template: hero + highlights strip grid, CSS custom property theming
     ├── slider-gallery.md       — SliderGallery: full-screen image carousel, IGalleryData, pause-on-hover/reduced-motion auto-advance, prefixed classes, CSS tokens
     ├── services-card.md        — ServicesCard props (incl. eyebrowConfig/heroConfig), actions slot, CSS tokens, page boilerplate
+    ├── google-reviews.md        — GoogleReviews + GoogleReviewCard: Google Places reviews in a scrolling row; env vars, server route, useGoogleReviews, props, slots, tokens, Google terms
     ├── services-card-grid.md        — ServicesCardGrid props, config pass-through, CSS tokens, full page boilerplate
     ├── service-summary-grid.md      — ServiceSummaryGrid props, useAlternateReverse zigzag layout, page boilerplate
     ├── service-summary.md           — ServiceSummary props, summary-link slot, DisplayPill duration/price (renamed/stripped from ServicesSection — full mode is now ServiceDetail)
@@ -137,6 +140,7 @@ Each skill is a single markdown file named `<area>-<task>.md`.
     ├── input-button.md           — InputButton (renamed from InputButtonCore 2026-09-28): button/NuxtLink/a, variants, icon slots, readonly (aria-disabled, activation blocked), tokens
     ├── input-range-core.md       — InputRangeCore: native range-slider primitive, markers/datalist slots, dead --theme-form-range-accent-color token fixed, CSS token API; Variants section covers InputRangeDefault
     ├── input-number.md           — InputNumber: native number-input primitive, left/right step-button slots, missing base class/placeholder/mismatched slot-selector bugs fixed, CSS token API; Variants section covers InputNumberField
+    ├── input-otp.md              — InputOtp: one-time-code digit boxes (paste/autofill spreading, Backspace/arrow/Home/End nav, Enter submits, leading zeros kept, complete event, hidden input); Variants section covers InputOtpField
     ├── form-field.md             — FormField: layout wrapper for one form control (width cap, gutter, field spacing), data-width/data-has-gutter/data-invalid hooks, dead .underline rule removed, CSS token API
     ├── form-fieldset.md          — FormFieldset: shared fieldset+legend for checkbox/radio groups, groupRole prop (hardcoded radiogroup bug fixed), aria-required only on radiogroup, dead description slot removed, legend token API
     ├── input-error.md            — InputError: red error strip every *Field wrapper renders under its control, data-visible/data-detached/data-input-variant hooks, generic .inner/.message class names prefixed, dead compact prop and hidden-state border CSS removed, icon prop, CSS token API

package/.claude/skills/new-app-scaffold.md

@@ -339,5 +339,5 @@ npm install
 - If security modules are not wanted, omit `nuxt-security` from `dependencies` and remove it
   from `modules` and the `security` config block in `nuxt.config.ts`. Same for `@nuxtjs/robots`.
 - The `colourScheme.enabled: false` default is correct for most consumer apps — enable only if
-  the app needs light/dark switching.
+  the app needs light/dark switching (then follow `theming-dark-mode.md`: the layer ships light values only).
 - Check the latest `srcdev-nuxt-components` version on npm before writing `package.json`.

package/.claude/skills/theming-colour-ramps.md

@@ -254,8 +254,8 @@ In `app/assets/styles/setup/02.colours/index.css` (create if it doesn't exist):
   --theme-chroma: var(--palette-gold-chroma);
 
   /* Page-level tokens — readable named steps, not raw oklch */
-  --colour-text-accent:  light-dark(var(--gold-09), var(--gold-04));
-  --colour-text-eyebrow: light-dark(var(--gold-09), var(--gold-04));
+  --colour-text-accent:  var(--gold-09);
+  --colour-text-eyebrow: var(--gold-09);
 }
 
 /* Optional: make it available as a data-theme variant too */
@@ -295,37 +295,10 @@ approach whenever you need `--gold-09` style references in your CSS.
 
 ## Light / dark mode
 
-Semantic slots use `light-dark()`, which responds to `color-scheme` on `html` (set by the layer's
-`_head.css`):
-
-```css
-html {
-  color-scheme: light dark;   /* OS preference */
-  &.light { color-scheme: light; }
-  &.dark  { color-scheme: dark; }
-}
-```
-
-Use `light-dark()` in your own override values too:
-
-```css
-:where(html) {
-  --theme-hue: 85;
-  --theme-chroma: 0.20;
-  --page-bg: light-dark(var(--slate-00), var(--slate-08));
-}
-```
-
-**Multi-value caveat**: `light-dark()` cannot contain comma-separated values (e.g. box-shadow
-lists). Use intermediate scalar vars:
-
-```css
---_shadow-a: light-dark(0.08, 0.5);
---my-shadow: 0 8px 32px rgba(0, 0, 0, var(--_shadow-a));
-```
-
-The `useColourScheme()` composable toggles the `.light` / `.dark` class on `<html>`. See
-`composable-colour-scheme.md` for the full API.
+The layer ships light values only (since 2026-10-04): no token uses `light-dark()`, because older
+iPad Safari doesn't support it. Dark mode is the consumer app's decision. `theming-dark-mode.md`
+has the full setup: enabling the scheme plumbing, the complete dark token set to copy (works on
+older Safari), and the shorter `light-dark()` alternative for apps that don't need it.
 
 ## Hue angle reference
 

package/.claude/skills/theming-component-token-pattern.md

@@ -53,6 +53,36 @@ an inline fallback, even if that fallback happens to be a Tier 1 or Tier 2 token
   colour, fixed on purpose across states), reuse the base token — don't manufacture a second name
   for a value that never diverges.
 
+## Line-clamp tokens
+
+Text that could overflow (names, titles, descriptions, body text) gets one public token per
+element, `--{component}-{element}-line-clamp`. It covers both ellipsis cases: `1` is single-line
+ellipsis, any other number caps the lines with an ellipsis on the last, `none` shows everything.
+Prefer this over a prop: line count is presentation, and CSS handles it without a re-render.
+
+```css
+.google-review-card-author-name {
+  display: -webkit-box;
+  -webkit-box-orient: vertical;
+  overflow: hidden;
+  overflow-wrap: anywhere; /* unbroken strings still wrap before the clamp applies */
+  -webkit-line-clamp: var(--google-reviews-author-line-clamp, 2);
+  line-clamp: var(--google-reviews-author-line-clamp, 2);
+}
+```
+
+- Default to `none` unless the layout clearly needs a cap (a row of equal-height cards, say). Use
+  `none` for "no clamp", never a large number like `100` (`ServicesCard`'s
+  `--description-line-clamp: 100` predates this; switch it to `none` when it's next migrated).
+- Don't clamp text that must stay readable: legal or attribution text, error messages, link text
+  that names its destination.
+- Clamped text stays in the DOM, so screen readers read all of it; sighted users lose the rest,
+  which is why `none` is the default. If a clamped item has nowhere else to read it in full,
+  consider a "read more" link or a `title`.
+- `display: -webkit-box` makes an inline element (`<a>`, `<span>`) block-level; check the
+  layout around it.
+- Document it in `CONSUMER-STYLING.md` with its default and the `1`/`none` options.
+
 ## Multi-level fallback chains are fine
 
 A component that wants to *look like* another component's default (rather than duplicating a

package/.claude/skills/theming-dark-mode.md

@@ -0,0 +1,243 @@
+# Dark Mode in a Consumer App
+
+## Overview
+
+Since 2026-10-04 this layer ships **light colour values only**. No token in the layer uses
+`light-dark()`, because older iPad Safari doesn't support it. A custom property holding an
+unsupported `light-dark()` is stored without complaint, then every property that reads it becomes
+invalid at computed-value time: transparent backgrounds, `currentColor` borders, no console error.
+
+Dark mode is the consumer app's decision. The layer still provides all the switching plumbing:
+
+| Part | What it does |
+|---|---|
+| `runtimeConfig.public.colourScheme.enabled` | Turns the plumbing on. `new-app-scaffold.md` defaults it to `false`, so set it to `true` (see `colour-scheme-disable.md` for the config shape) |
+| Head script (`modules/colour-scheme.ts`, `utils/colour-scheme-init.ts`) | Before first paint, sets `html[data-color-scheme]` to the saved `auto`, `light` or `dark` (default `auto`) |
+| `useColourScheme()` | Reads/writes the saved scheme. See `composable-colour-scheme.md` |
+| `DisplayThemeSwitch` | Ready-made system/light/dark picker. See `components/display-theme-switch.md` |
+
+What the app supplies is the dark **values**, and the CSS `color-scheme` property. The layer
+doesn't declare `color-scheme` at all (removed 2026-10-04), so browsers render native UI
+(scrollbars, date and select pickers, form control internals) light unless the app says
+otherwise. There are two ways to do it.
+
+---
+
+## Option A: attribute + media query (works on older Safari)
+
+Redeclare the tokens you want dark under `html[data-color-scheme="dark"]`, and again inside a
+`prefers-color-scheme: dark` media query for `auto`. The two blocks hold the same declarations;
+that duplication is the cost of not using `light-dark()`.
+
+Put it in its own file, imported **last** in the app's `03.theming/index.css` (see
+`consumer-styles-structure.md`). The selectors are wrapped in `:where()` like every other consumer
+token file, so they have zero specificity and win over the app's own light values by coming later.
+
+```css
+/* setup/03.theming/index.css */
+@import "./_default.css";
+@import "./_forms.css";
+@import "./_dark.css";   /* last */
+```
+
+### Full token set
+
+These are the dark values the layer used to ship, so starting from this file gives you back the
+previous built-in dark mode exactly. Delete what you don't need, or swap in your own palette's steps
+(`--gold-04` etc.). If your `_default.css` changed a page-level token to another palette (e.g.
+`--colour-text-accent: var(--gold-09)`), use that palette's step here too.
+
+```css
+/* Dark scheme: token values for html[data-color-scheme="dark"], and "auto" on a dark OS. */
+
+/* ---- 1. Page-level, a11y and input tokens: html only ---- */
+:where(html[data-color-scheme="dark"]) {
+  color-scheme: dark; /* native UI goes dark too */
+
+  --page-bg: var(--slate-08);
+  --colour-text-default: var(--slate-01);
+  --colour-text-accent: var(--blue-05);
+  --colour-text-eyebrow: var(--blue-05);
+  --colour-link-default: var(--blue-02);
+  --colour-link-hover: var(--blue-03);
+
+  --theme-input-surface: var(--slate-10);
+  --theme-input-surface-hover: var(--slate-09);
+  --theme-input-text-color-normal: var(--slate-01);
+  --theme-input-placeholder: var(--slate-04);
+
+  --focus-box-shadow-colour-on: var(--slate-00);
+  --box-shadow-on: 0 0 0 0.3rem var(--slate-00);
+
+  /* Only if you use StepperList */
+  --stepper-list-counter-circle-text: var(--blue-02);
+  --stepper-list-counter-circle-border: var(--blue-02);
+  --stepper-list-counter-disc-background: var(--blue-02);
+  --stepper-list-counter-disc-border: var(--blue-02);
+  --stepper-list-counter-square-text: var(--blue-02);
+  --stepper-list-counter-square-border: var(--blue-02);
+  --stepper-list-connector-color: var(--blue-02);
+  --stepper-list-icon-color: var(--blue-02);
+
+  /* Only if you use TreatmentConsultant */
+  --treatment-consultant-primary-colour: var(--amber-02);
+  --treatment-consultant-primary-foreground: var(--amber-02);
+  --treatment-consultant-muted-colour: var(--amber-05);
+  --treatment-consultant-muted-foreground: var(--amber-05);
+  --treatment-consultant-background: var(--amber-10);
+  --treatment-consultant-foreground: var(--amber-02);
+  --treatment-consultant-border-colour: var(--amber-03);
+  --treatment-consultant-checked-surface-colour: var(--green-10);
+  --treatment-consultant-checked-stroke-colour: var(--green-03);
+  --treatment-consultant-conflict-surface-colour: var(--sunset-09);
+  --treatment-consultant-conflict-stroke-colour: var(--sunset-03);
+}
+
+/* ---- 2. Semantic slots: html AND every themed element ---- */
+:where(
+  html[data-color-scheme="dark"],
+  html[data-color-scheme="dark"] [data-theme],
+  html[data-color-scheme="dark"] [data-invalid]
+) {
+  --theme-surface: var(--colour-theme-9);
+  --theme-surface-inverted: var(--colour-theme-2);
+  --theme-surface-hover: var(--colour-theme-7);
+  --theme-accent: var(--colour-theme-4);
+  --theme-surface-subtle: var(--colour-theme-9);
+  --theme-border: var(--colour-theme-5);
+  --theme-border-focus: var(--colour-theme-3);
+  --theme-ring: var(--colour-theme-9);
+  --theme-text: var(--colour-theme-2);
+  --theme-text-inverted: var(--colour-theme-7);
+}
+
+/* ---- 3. Warning keeps its AA-safe step 6 surface in both schemes ---- */
+:where(html[data-color-scheme="dark"] [data-theme="warning"]) {
+  --theme-surface: var(--colour-theme-6);
+  --theme-surface-hover: var(--colour-theme-7);
+}
+
+/* ---- 4. Form error tokens ---- */
+:where(
+  html[data-color-scheme="dark"] [data-invalid],
+  html[data-color-scheme="dark"] [data-theme="error"]
+) {
+  --theme-error-surface: var(--red-07);
+  --theme-error-border: var(--red-07);
+  --theme-error-outline: var(--red-05);
+}
+
+/* ---- 5. "auto" on a dark OS: repeat blocks 1-4 with data-color-scheme="auto" ---- */
+@media (prefers-color-scheme: dark) {
+  :where(html[data-color-scheme="auto"]) {
+    /* block 1 declarations */
+  }
+  :where(
+    html[data-color-scheme="auto"],
+    html[data-color-scheme="auto"] [data-theme],
+    html[data-color-scheme="auto"] [data-invalid]
+  ) {
+    /* block 2 declarations */
+  }
+  :where(html[data-color-scheme="auto"] [data-theme="warning"]) {
+    /* block 3 declarations */
+  }
+  :where(
+    html[data-color-scheme="auto"] [data-invalid],
+    html[data-color-scheme="auto"] [data-theme="error"]
+  ) {
+    /* block 4 declarations */
+  }
+}
+```
+
+### Why the selectors look like that
+
+- **Semantic slots must be redeclared on `[data-theme]` and `[data-invalid]` elements**, not only
+  on `html`. The layer declares them on all three (`_theme-slots.css`) so `var(--colour-theme-N)`
+  resolves against each themed element's own hue. A dark value set only on `html` would be
+  computed once with the default hue and inherited, and every `data-theme="success"`/`"error"`
+  element would turn the default blue.
+- **`[data-theme="warning"]` needs its own block** because the layer gives warning a fixed step 6
+  surface (the lightest orange step where light text still passes AA). Block 2 would otherwise
+  overwrite it.
+- **No `data-color-scheme` attribute at all** only happens if the plumbing is disabled. If you
+  render before the head script can run (rare), add `html:not([data-color-scheme])` next to the
+  `auto` selector in block 5.
+
+### Component tokens
+
+Components whose own public tokens default to fixed light values (e.g.
+`--clipped-panel-background-colour`, `--glass-panel-*`, `--carousel-flip-*`,
+`--dashboard-quad-grid-*`) don't change with the semantic slots. Add any you use to block 1 (and
+block 5). Each component's `CONSUMER-STYLING.md` lists its colour tokens.
+
+---
+
+## Option B: `light-dark()` (shorter, modern browsers only)
+
+If the app doesn't need to support older Safari (`light-dark()` needs Safari 17.5+, Chrome 123+,
+Firefox 120+), set each token once with both values. `light-dark()` picks its branch from the
+`color-scheme` property, which the layer doesn't set, so the app declares it, following the
+attribute:
+
+```css
+html {
+  color-scheme: light dark; /* "auto": follow the OS */
+
+  &[data-color-scheme="light"] { color-scheme: light; }
+  &[data-color-scheme="dark"]  { color-scheme: dark; }
+}
+
+:where(html) {
+  --page-bg: light-dark(var(--slate-00), var(--slate-08));
+  --colour-text-default: light-dark(var(--slate-09), var(--slate-01));
+}
+
+:where(html, [data-theme], [data-invalid]) {
+  --theme-surface: light-dark(var(--colour-theme-7), var(--colour-theme-9));
+  --theme-text: light-dark(var(--colour-theme-9), var(--colour-theme-2));
+  /* ...the rest of block 2 from Option A, each as light-dark(layer value, dark value) */
+}
+```
+
+The light value for each token is the layer's current default (see
+`app/assets/styles/setup/03.theming/` and `a11y/_variables.css` in the package). The same rules
+apply: semantic slots on `[data-theme]`/`[data-invalid]` too, and a separate rule for
+`[data-theme="warning"]`.
+
+**Multi-value caveat**: `light-dark()` can't hold comma-separated values (e.g. a box-shadow list).
+Put the varying part in a scalar var:
+
+```css
+--_shadow-a: light-dark(0.08, 0.5);
+--my-shadow: 0 8px 32px rgba(0, 0, 0, var(--_shadow-a));
+```
+
+On a browser without `light-dark()`, Option B fails the same silent way described in the
+Overview. Don't mix: if older Safari matters for any page, use Option A everywhere.
+
+---
+
+## Light-only apps
+
+If the app has no dark mode, leave `colourScheme.enabled: false` (the scaffold default) and add
+nothing. With no `color-scheme` declared anywhere, native UI stays light even on a dark OS.
+
+---
+
+## Storybook in a consumer app
+
+This repo's own Storybook is set up as a consumer and is a working reference:
+`.storybook/color-scheme.css` holds blocks 1-4, and `.storybook/preview.ts` turns its "Follow OS"
+toolbar option into `data-color-scheme="light"`/`"dark"` using `matchMedia`, so it needs no block 5.
+Those files aren't in the npm package; the token set above is the same content.
+
+---
+
+## Related
+
+- `composable-colour-scheme.md`: `useColourScheme()` API
+- `colour-scheme-disable.md`: the `enabled` flag and turning everything off
+- `theming-colour-ramps.md`: ramps, semantic slots, palettes for your dark values
+- `consumer-styles-structure.md`: where `_dark.css` sits in the app's CSS tree

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

@@ -120,10 +120,10 @@ Create `app/assets/styles/setup/03.theming/_default.css`:
   --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));
+  --page-bg: var(--slate-00);
+  --colour-text-default:  var(--slate-09);
+  --colour-text-accent:   var(--gold-09);
+  --colour-text-eyebrow:  var(--gold-09);
 }
 ```
 
@@ -172,8 +172,8 @@ export default defineNuxtConfig({
 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.
+declared on that same selector with light values only. The layer ships no dark scheme; to add
+one, see `theming-dark-mode.md`.
 
 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
@@ -183,7 +183,6 @@ that hue/chroma pair.
 
 - 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

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

@@ -88,8 +88,8 @@ Page-level tokens:
 ```css
 /* 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));
+  --theme-surface:       oklch(48% 0.18 85);
+  --theme-surface-hover: oklch(32% 0.18 85);
 }
 ```
 
@@ -97,9 +97,9 @@ Page-level tokens:
 
 ```css
 :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));
+  --theme-input-surface:           oklch(0.99 0 0);
+  --theme-input-text-color-normal: oklch(0.20 0.01 255);
+  --theme-input-placeholder:       oklch(0.60 0.01 255);
 }
 ```
 
@@ -107,9 +107,9 @@ Page-level tokens:
 
 ```css
 :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));
+  --page-bg:             oklch(0.98 0 0);
+  --colour-text-default: oklch(0.20 0 0);
+  --colour-text-accent:  oklch(0.30 0.16 85);
 }
 ```
 
@@ -140,8 +140,8 @@ To restrict an override to a specific section, scope to a wrapper class instead
 
 .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));
+  --theme-surface:       oklch(48% 0.16 85);
+  --theme-surface-hover: oklch(32% 0.14 85);
 }
 ```
 
@@ -160,6 +160,6 @@ To change how `data-theme="success"` looks without affecting other themes:
 ## Notes
 
 - 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
+- The layer ships light values only (no `light-dark()`, for older iPad Safari). For dark mode, redeclare tokens under `html[data-color-scheme="dark"]` plus a `prefers-color-scheme` block for `auto`, or use `light-dark()` yourself if you accept the browser-support cost. Full setup in `theming-dark-mode.md`.
 - `--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

package/.vscode/srcdev-component-google-reviews.code-snippets

@@ -0,0 +1,78 @@
+{
+  "SRCDEV GoogleReviews Basic": {
+    "description": "GoogleReviews fed by useGoogleReviews() (needs NUXT_GOOGLE_REVIEWS_API_KEY and NUXT_GOOGLE_REVIEWS_PLACE_ID)",
+    "scope": "vue,html",
+    "body": [
+      "<GoogleReviews :data=\"${1:googleReviews}\" />"
+    ]
+  },
+  "SRCDEV GoogleReviews Script": {
+    "description": "Fetch Google reviews from the layer's server route",
+    "scope": "typescript,javascript,vue",
+    "body": [
+      "const { data: ${1:googleReviews} } = await useGoogleReviews();"
+    ]
+  },
+  "SRCDEV GoogleReviews With Heading": {
+    "description": "GoogleReviews labelled by its own heading, optionally filtered",
+    "scope": "vue,html",
+    "body": [
+      "<GoogleReviews :data=\"${1:googleReviews}\" :min-rating=\"${2:0}\">",
+      "  <template #heading=\"{ headingId }\">",
+      "    <h2 :id=\"headingId\">${3:What clients say}</h2>",
+      "  </template>",
+      "</GoogleReviews>"
+    ]
+  },
+  "SRCDEV GoogleReviews Custom Card": {
+    "description": "GoogleReviews with each card rendered through the card slot",
+    "scope": "vue,html",
+    "body": [
+      "<GoogleReviews :data=\"${1:googleReviews}\">",
+      "  <template #card=\"{ review }\">",
+      "    <GoogleReviewCard :review=\"review\" :style-class-passthrough=\"['${2:my-review}']\" />",
+      "  </template>",
+      "</GoogleReviews>"
+    ]
+  },
+  "SRCDEV GoogleReviews CSS Override": {
+    "description": "CSS override scaffold for GoogleReviews — scope to a page or section class. See CONSUMER-STYLING.md for the full token list.",
+    "scope": "css",
+    "body": [
+      ".$1my-page {",
+      "  .google-reviews {",
+      "    --google-reviews-gap: ;",
+      "    --google-reviews-card-width: ;",
+      "    --google-reviews-scroll-padding: ;",
+      "    --google-reviews-scrollbar-width: ;",
+      "    --google-reviews-scrollbar-thumb-colour: ;",
+      "    --google-reviews-scrollbar-track-colour: ;",
+      "    --google-reviews-summary-rating-font-size: ;",
+      "    --google-reviews-focus-outline-width: ;",
+      "    --google-reviews-focus-outline-colour: ;",
+      "",
+      "    --google-reviews-card-gap: ;",
+      "    --google-reviews-card-padding: ;",
+      "    --google-reviews-card-border-width: ;",
+      "    --google-reviews-card-border-colour: ;",
+      "    --google-reviews-card-border-radius: ;",
+      "    --google-reviews-card-surface: ;",
+      "    --google-reviews-card-text-colour: ;",
+      "    --google-reviews-avatar-surface: ;",
+      "    --google-reviews-avatar-text-colour: ;",
+      "    --google-reviews-author-font-weight: ;",
+      "    --google-reviews-author-line-clamp: ;",
+      "    --google-reviews-text-line-height: ;",
+      "    --google-reviews-text-line-clamp: ;",
+      "    --google-reviews-link-colour: ;",
+      "",
+      "    --google-reviews-star-size: ;",
+      "    --google-reviews-star-colour: ;",
+      "    --google-reviews-star-empty-colour: ;",
+      "    --google-reviews-meta-font-size: ;",
+      "    --google-reviews-meta-text-colour: ;",
+      "  }",
+      "}"
+    ]
+  }
+}