srcdev-nuxt-components 9.5.2 → 9.5.4

package/.claude/skills/components/input-otp.md

@@ -0,0 +1,120 @@
+# InputOtp Component
+
+## Overview
+
+`InputOtp` is a one-time-code entry control: a row of single-digit boxes for verification codes
+sent by email or SMS (sign-in, two-factor, email confirmation). It has no label, description or
+error rendering of its own; that's composed by the `InputOtpField` variant below.
+
+Most consumers should reach for **InputOtpField**.
+
+Location: `app/components/05.forms/input-otp/`. Styling: `CONSUMER-STYLING.md` in that folder.
+
+---
+
+## Behaviour
+
+- Only digits are accepted. Typing a digit fills the box and moves focus to the next one.
+- Typing into a box that already holds a digit replaces it (focusing a box selects its contents).
+- Backspace in an empty box clears the previous box and moves focus there; Backspace in a filled
+  box only clears that box.
+- Pasting spreads the digits across the boxes, strips non-digits and truncates to `length`. A
+  full-length paste always fills from the first box; a shorter one fills from the focused box.
+  Focus lands on the last box filled.
+- Autofill works: the first box has `autocomplete="one-time-code"`, and several characters landing
+  in one box (iOS/Android SMS autofill) are spread the same way as a paste.
+- Enter submits the parent form via `form.requestSubmit()` (with the native implicit submission
+  suppressed, so it never submits twice). Several single-character inputs don't otherwise get
+  implicit submission when the form has no submit button.
+- Left/Right arrows move between boxes; Home/End jump to the first/last box.
+- The first box is focused on mount only when `autofocus` is set. When `fieldHasError` turns on,
+  focus moves to the first box so the user can retype straight away.
+- `complete` fires with the code whenever a change leaves every box filled.
+- Each box has a visually hidden label built from `digitLabel` (translatable). In
+  `InputOtpField` the fieldset legend names the group; on its own, `groupLabel` adds
+  `role="group"` + `aria-label`.
+- On error every box gets `aria-invalid="true"` and the `aria-describedby` ids.
+- With `name` set, a hidden input carries the full code, so a native form submit sends one value.
+  The boxes themselves have no `name`.
+- **Leading zeros are kept.** The model is a `string` and the boxes are `type="text"` with
+  `inputmode="numeric"`; nothing is ever converted to a number, so `"012345"` stays `"012345"`.
+- `length` is clamped to 1–12. Non-digits and overflow in an incoming model value are ignored
+  for display (they show as empty boxes).
+
+---
+
+## Props reference
+
+> Write camelCase props hyphenated in templates (`:field-has-error`, `:digit-label`).
+
+| Prop (template form) | Type | Default | Notes |
+|------|------|---------|-------|
+| `:id` | `string` | (required) | Box ids are `{id}-0`, `{id}-1`, ... |
+| `:name` | `string` | `""` | Name of the hidden input holding the full code. No hidden input when empty. |
+| `:length` | `number` | `6` | Number of boxes, clamped 1–12. |
+| `:autofocus` | `boolean` | `false` | Focus the first box on mount. Use when the field appears as the direct result of a user action (e.g. after submitting an email step). |
+| `:required` | `boolean` | `false` | Native `required` on every box. |
+| `:group-label` | `string` | `""` | When set, root gets `role="group"` and this `aria-label`. Leave empty inside `InputOtpField`. |
+| `:digit-label` | `string` | `"Digit {index} of {length}"` | Per-box hidden label; `{index}` (1-based) and `{length}` are replaced. |
+| `:field-has-error` | `boolean` | `false` | `data-invalid` on the root, `aria-invalid` on each box, focuses the first box when it turns on. |
+| `:aria-describedby` | `string` | `""` | Forwarded to every box. |
+| `:theme` | `FormUiTheme` | `"default"` | `data-theme` on the root. |
+| `:input-variant` | `InputUiVariant` | `"normal"` | `normal` (bordered boxes) or `underlined`. `outlined` has no CSS, same as the other `05.forms` inputs. |
+| `:style-class-passthrough` | `string \| string[]` | `[]` | Classes on the `.input-otp` root. |
+
+### v-model
+
+`v-model`: `string`, **required**. Digits only; unfilled trailing boxes are trimmed, so a
+half-entered code is e.g. `"123"`. A gap in the middle (box 2 cleared while box 3 is filled)
+is a space.
+
+### Events
+
+| Event | Payload | When |
+|------|------|------|
+| `complete` | `code: string` | A change leaves every box filled. Use it to auto-submit. |
+
+---
+
+## Variants
+
+### InputOtpField
+
+`FormFieldset` (the label is the `<legend>`) + `InputDescription` + `InputOtp` + `InputError`,
+with ids linked through `useAriaDescribedById`. Root class `.input-otp-field` (on the fieldset).
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `name` | `string` | (required) | Used for the ids and the hidden input's name. |
+| `label` | `string` | (required) | Fieldset legend. |
+| `errorMessage` | `string \| object` | `""` | Shown in `InputError` when `fieldHasError`. |
+| `length`, `autofocus`, `required`, `digitLabel`, `fieldHasError`, `theme`, `inputVariant`, `styleClassPassthrough` | | | As on `InputOtp`; passthrough goes on the fieldset. |
+
+Slots: `descriptionText`, `descriptionHtml` (linked via `aria-describedby`). Emits `complete`.
+
+```vue
+<form @submit.prevent="verify">
+  <InputOtpField
+    v-model="code"
+    name="code"
+    label="Verification code"
+    autofocus
+    :error-message="codeError"
+    :field-has-error="Boolean(codeError)"
+    @complete="verify"
+  >
+    <template #descriptionText>Enter the 6-digit code we sent to your email.</template>
+  </InputOtpField>
+</form>
+```
+
+---
+
+## Migrating from an app-local `InputOtp`
+
+This was ported from a consumer app's own `InputOtp.vue` (2026-10-04). Differences: the app version
+took `id` + `label` in one component; use `InputOtpField` with `name` instead of `id`. It always
+focused the first box on mount; pass `autofocus` to keep that. Its boxes were named `{id}-{index}`;
+read the code from `v-model` or the hidden input (`name`) instead. Rename the app's file away (or
+delete it) once on the layer release that ships this, or the app's own `InputOtp` shadows the
+layer's.

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

package/.claude/skills/components/services-card.md

@@ -12,6 +12,7 @@
 | `tag`                   | `"div" \| "section" \| "article"` | `"div"`     | no       |
 | `href`                  | `string`                           | `undefined` | no       |
 | `external`              | `boolean`                          | `false`     | no       |
+| `titlesWithinImageWrapper` | `boolean`                       | `false`     | no       |
 | `eyebrowConfig`         | `ServicesCardEyebrowConfig`                    | `{}`        | no       |
 | `heroConfig`            | `ServicesCardHeroConfig`                       | `{}`        | no       |
 | `durationText`          | `string`                           | `undefined` | no       |
@@ -30,6 +31,17 @@ If an `actions` slot is provided, the card stays as a static `tag` element (no h
 
 `is-clickable` is added to the root class list when whole-card-clickable mode is active, giving `cursor: pointer` and removing default link colour/underline. It's also what gates the border/outline hover/focus interaction-state tokens — see "Interaction states (whole-card-clickable only)" in `CONSUMER-STYLING.md`; they're a no-op when the card isn't clickable, since only `.is-clickable` has a `:hover`/`:focus-visible` rule.
 
+### Titles over the image (`titlesWithinImageWrapper`)
+
+When `true`, the eyebrow and title move out of `.details-wrapper` and sit over the bottom of the image instead. The image wrapper is a `GridStack`: the image is layer 1, and `.image-wrapper-details` (eyebrow + title) is layer 2. The description, meta row and actions stay below the image.
+
+- A gradient scrim behind the text keeps it readable. Its colour comes from `--image-wrapper-details-scrim-colour` (default black), and `--image-wrapper-details-scrim` replaces the whole background (`none` removes it).
+- Text colour uses `contrast-color()` against the scrim colour where supported (black or white, whichever reads better), falling back to white. It reads the scrim colour only, not the photo, so if you remove the scrim, set `--image-wrapper-details-text-colour` yourself.
+- The eyebrow's gradient fill is turned off over the image; it takes the text colour (or `--image-wrapper-details-eyebrow-text-colour`).
+- The eyebrow's default `fontSize` is `"medium"` in this mode (vs `"large"` below the image). `eyebrowConfig`/`heroConfig` still apply.
+
+See "Titles over the image" in `CONSUMER-STYLING.md` for the token list.
+
 ### EyebrowConfig
 
 Exported as `ServicesCardEyebrowConfig` (and `ServicesCardHeroConfig` below) from `srcdev-nuxt-components` since 2026-09-28.
@@ -37,7 +49,7 @@ Exported as `ServicesCardEyebrowConfig` (and `ServicesCardHeroConfig` below) fro
 | Key        | Type                              | Default   |
 | ---------- | ---------------------------------- | --------- |
 | `tag`      | `"p" \| "div" \| "span"`          | `"div"`   |
-| `fontSize` | `"large" \| "medium" \| "small"`  | `"large"` |
+| `fontSize` | `"large" \| "medium" \| "small"`  | `"large"` (`"medium"` with `titlesWithinImageWrapper`) |
 
 ### HeroConfig
 
@@ -159,6 +171,16 @@ See `CONSUMER-STYLING.md` for the full token list — every token is a plain pub
 consumed directly at its point of use (no `--_`-prefixed private indirection layer), so all of
 them work both globally (`:root`) and scoped like the example above.
 
+## Titles over the image usage
+
+```vue
+<ServicesCard :service-data="service" titles-within-image-wrapper>
+  <template #actions="{ serviceData }">
+    <InputButton variant="secondary" button-text="Enquire" :href="`/services/${serviceData.slug}`" />
+  </template>
+</ServicesCard>
+```
+
 ## Whole-card clickable usage
 
 ```vue
@@ -173,6 +195,7 @@ No `actions` slot — the entire card renders as an anchor (`NuxtLink` for the i
 - The `Service` type is imported from `~/types/types.services`.
 - Root markup is two rows (`grid-template-rows: auto 1fr`): `.image-wrapper`, then a `.details-wrapper` (`display: flex; flex-direction: column`) holding the eyebrow, title, description, and a `.footer` wrapper. Description length is controlled by `--description-line-clamp` (default effectively unclamped) rather than a fixed-height grid row.
 - `.footer` groups the meta row and the `actions` slot and gets `margin-block-start: auto`, pinning them to the bottom of the card. Combined with the root's `1fr` details row, this means when `ServicesCardGrid`'s default `align-items: stretch` makes a card taller than its own content (to match a taller sibling in the same row), the extra height goes to `.footer`'s top margin rather than leaving whitespace below the actions slot — so the meta row and actions/button line up across a row of cards regardless of each card's description length. This does the visual job of CSS subgrid without needing a subgrid chain across `ServicesCard`/`ServicesCardGrid` (which would also break whenever cards in a row don't all render the same optional rows — `.meta` and `actions` are both conditional).
-- Image has a `3/4` aspect ratio with a subtle scale-on-hover effect.
+- Image has a `3/4` aspect ratio with a subtle scale-on-hover effect, triggered by hovering the image only (not the whole card). When the card is a whole-card link styled with its own hover effect (e.g. `--services-card-transform-hover`), set `--image-wrapper-border-image-zoom-transform: none` so the two effects don't stack; the "Dark Overlay Cards" story does this. Keep the zoom for the `actions`-slot layout, where the card itself has no hover state. The hover is on `.image-wrapper`, not the image, so it still fires when the overlaid titles cover the image. `.image-wrapper-details` is `position: relative; z-index: 1` because the image's hover `transform` would otherwise paint over it, and `.image-wrapper` sets `isolation: isolate` so that z-index stays inside the card.
 - `.services-card`, `.image-wrapper`, `.details-wrapper`, and `.footer` all set `min-inline-size: 0`. Without it, an unbreakable child — most commonly a long `actions` slot button label, since `InputButton`'s `.button-text` is `white-space: nowrap` with no ellipsis — forces its content's min-content width up through the flex/grid chain and widens that one card's grid column in `ServicesCardGrid` wider than its siblings (the image just rides along on the widened column; it isn't the actual cause). If you see one card/column wider than the rest with cut-off content, check for a long unbreakable string in a slot before assuming it's an image sizing issue.
 - Usually consumed via `ServicesCardGrid` rather than directly.
+- The "Dark Overlay Cards" story shows a full restyle using tokens only: dark panel, flush image, titles over the image, hover lift (`--services-card-transform-hover`), and EyebrowText typography tokens (`--eyebrow-text-font-style`, `-letter-spacing`, etc.) set on the card so they inherit into its eyebrow.

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/storybook-add-story.md

@@ -277,6 +277,11 @@ Key points:
   (`html[data-color-scheme="light"]`, off-white `--slate-00` stage) by default, whatever the OS
   setting. Use the toolbar "Colour scheme" menu (Light / Dark / Follow OS) to check dark mode.
   Don't hardcode a stage background in a story to get a light canvas; it's already the default.
+- **Edge-aware components need `layout: "fullscreen"`** in the meta's `parameters`. Storybook's
+  default `"padded"` layout insets the canvas by 1rem, which masks viewport gutters, full-bleed
+  tracks and edge alignment (`PageRow`, `SliderGallery`). To swap canvas widths inside a story,
+  add the `CanvasSwitcher` decorator from `PageRow.stories.ts` (container-sized components only;
+  see `components/canvas-switcher.md`).
 - Use `table: { category: "..." }` in `argTypes` when a component has many props — it groups
   them in the Storybook controls panel (e.g. `"Model"`, `"Basic"`, `"Validation"`, `"Styling"`, `"Slots"`).
 - Export multiple named stories (`Default`, `WithError`, `Outlined`, etc.) when you want

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