srcdev-nuxt-components 9.3.11 → 9.3.13

package/.claude/skills/component-aria-landmark.md

@@ -31,9 +31,9 @@ correctly** — always check the console (or run an accessibility audit) after a
 
 This bug class previously shipped to production undetected: eight sections across one site had
 `aria-labelledby` pointing at ids that were never applied to anything, only surfaced by a WAVE
-audit. Two components (`ServicesSection`, `AutoGrid`) were also found to be *structurally* broken
+audit. Two components (`ServiceSummary` (formerly ServicesSection), `AutoGrid`) were also found to be *structurally* broken
 — they set `aria-labelledby` from `tag` alone without ever exposing `headingId` anywhere a
-consumer could bind it, so it was impossible to satisfy correctly. `ServicesSection` now binds
+consumer could bind it, so it was impossible to satisfy correctly. `ServiceSummary` now binds
 `headingId` to its own internal title heading; `AutoGrid` has no heading concept at all, so it no
 longer sets `aria-labelledby` under any circumstance (pass `aria-label` directly if needed).
 
@@ -87,7 +87,7 @@ must bind it to their own heading):
 Self-bound (the component renders its own heading and binds `headingId` internally — no consumer
 action needed):
 
-- `ServicesSection` (03.organisms) — binds it to its own title `HeroText`
+- `ServiceSummary` (03.organisms) — binds it to its own title `HeroText`
 - `LayoutGridByCols` / `LayoutGridByWidth` (01.atoms) — render their own visually-hidden `<p>` from the `label` prop
 
 Not using this pattern:

package/.claude/skills/components/auto-grid.md

@@ -95,7 +95,7 @@ Override `grid-template-columns` directly — there is no single token for this:
 
 `AutoGrid` has no heading concept of its own — its slots are arbitrary named items, not a
 header + body — so it does **not** auto-generate `aria-labelledby` the way `PageRow` or
-`ServicesSection` do (an earlier version of this component did attempt to, and it produced a
+`ServiceSummary` do (an earlier version of this component did attempt to, and it produced a
 guaranteed broken ARIA reference, since there was never any way to bind a heading to it). If
 `tag="section"` needs an accessible name, pass `aria-label` directly:
 

package/.claude/skills/components/page-hero-highlights.md

@@ -61,7 +61,7 @@ Each slot accepts any content, but these library components are natural fits:
 | `#header`     | `HeroText`                        | Heading with accent text, icon, and configurable size — wires `headingId` for `aria-labelledby` |
 | `#highlights` | `ServicesCard` (×n)               | Portrait cards with image, title, description, and CTA slot                                     |
 | `#highlights` | `LayoutGridByCols` wrapping cards | When you want a responsive column grid rather than a single row of cards                        |
-| `#content`    | Any content component             | Below the straddle — safe to use `PageRow`, `ServicesSection`, etc.                             |
+| `#content`    | Any content component             | Below the straddle — safe to use `PageRow`, `ServiceSummary`, `ServiceDetail`, etc.                             |
 
 Example with `HeroText` in the header slot:
 

package/.claude/skills/components/service-detail.md

@@ -21,12 +21,11 @@ CTA banner are each their own `PageRow` too, with their own variant props (`body
 if a particular page wants a section to sit in a different track (e.g.
 `heroContentVariant="inset-content"` for a narrower hero text column).
 
-It is a different shape from [ServicesSection](services-section.md): `ServicesSection` renders
-image-beside-content (used both as a compact summary card in a list and, in full mode, as a
-same-page detail block); `ServiceDetail` is meant to *be* the whole page for one service —
-`headerTag` defaults to `"h1"` accordingly, and there is no summary/compact mode. There is no
-`isSummary` prop and no `v-if` gating of content — everything the component renders is always
-rendered.
+It is a different shape from [ServiceSummary](service-summary.md): `ServiceSummary` renders a
+compact image-beside-content preview for a listing page; `ServiceDetail` is meant to *be* the
+whole page for one service — `headerTag` defaults to `"h1"` accordingly, and there is no
+summary/compact mode. There is no `v-if` gating of content — everything the component renders is
+always rendered.
 
 ## Props
 
@@ -63,12 +62,12 @@ type** — neither is universal enough to belong on `~/types/types.services`. Th
 the whole "You may also like" block simply don't render when they're omitted.
 
 `imageLoading`/`imageFetchPriority` default to eager/high because a `ServiceDetail` page normally
-has exactly one hero image and it's always the LCP candidate — unlike `ServicesSection`, which is
+has exactly one hero image and it's always the LCP candidate — unlike `ServiceSummary`, which is
 often looped and needs the `index` prop to lazy-load everything past the first two instances.
 
 ### `headerTag` vs `subheadingTag`
 
-Unlike `ServicesSection` (one `headerTag` prop applied to every heading, title included),
+Unlike `ServiceSummary` (one `headerTag` prop applied to its single title heading),
 `ServiceDetail` splits these: `headerTag` controls only the hero `<h1>` title; `subheadingTag`
 controls every other heading (What Is It, Process, Ideal For, Aftercare, FAQs, final CTA heading).
 This keeps the page's heading hierarchy correct when `ServiceDetail` is the page's own `<h1>`.
@@ -101,7 +100,7 @@ Defaults to a plain, non-linked two-item trail built from `serviceData.category`
 | `final-cta` | `{ serviceData: Service }` | Button in the closing full-width CTA banner |
 
 All routing decisions (breadcrumb links, book-cta href, related-service links, final-cta href)
-are delegated to the consumer, matching `ServicesSection`'s slot-based routing pattern.
+are delegated to the consumer, matching `ServiceSummary`'s slot-based routing pattern.
 
 ## Usage
 
@@ -155,10 +154,10 @@ pattern, and `CONSUMER-STYLING.md` in the component's own folder for the full to
 - Component is auto-imported in Nuxt — no import needed.
 - The `Service` type is imported from `~/types/types.services`; `BreadcrumbItem` from
   `~/types/components/breadcrumb`.
-- No `isSummary` mode and no content gating — this component always renders everything it's
-  given. If you need a compact summary card for a services listing page, use
-  [ServicesSection](services-section.md) in summary mode or [ServicesCard](services-card.md)
-  instead, and reserve `ServiceDetail` for the individual `/services/[slug]` page.
+- No content gating — this component always renders everything it's given. If you need a compact
+  summary card for a services listing page, use [ServiceSummary](service-summary.md) (via
+  [ServiceSummaryGrid](service-summary-grid.md)) or [ServicesCard](services-card.md) instead, and
+  reserve `ServiceDetail` for the individual `/services/[slug]` page.
 - Uses [Breadcrumb](breadcrumb.md) internally for the hero banner breadcrumb.
 - The two-/three-column layout breakpoints (body columns, ideal-for grid, final CTA row) are
   `@container` queries against the component's own width, not the viewport.
@@ -177,5 +176,5 @@ pattern, and `CONSUMER-STYLING.md` in the component's own folder for the full to
   carry the full-bleed scrim while its child still lands in the configured column.
 - The section gets `aria-labelledby` automatically when `tag` is `"section"`, `"article"`, or
   `"aside"`, pointing at the id `ServiceDetail` binds to its own title `HeroText` internally —
-  same mechanism as `ServicesSection`. `tag="main"` renders a `<main>` element but is never
+  same mechanism as `ServiceSummary`. `tag="main"` renders a `<main>` element but is never
   auto-labelled.

package/.claude/skills/components/service-summary-grid.md

@@ -0,0 +1,141 @@
+# ServiceSummaryGrid Component
+
+## Overview
+
+`ServiceSummaryGrid` renders a vertical stack of [ServiceSummary](service-summary.md) components
+from a `Service[]` array. Column order can be alternated on every other summary via
+`useAlternateReverse`.
+
+All routing decisions are delegated to the consumer via the `summary-link` scoped slot — the grid
+forwards `serviceData` from each `ServiceSummary` iteration so the consumer can build hrefs and
+labels freely.
+
+This is the renamed successor to `ServicesSectionGrid`, following `ServicesSection`'s rename/
+strip to `ServiceSummary` — see [service-summary.md](service-summary.md) for why the old "full
+mode" content went away.
+
+## Props
+
+| Prop | Type | Default | Required |
+|------|------|---------|----------|
+| `servicesData` | `Service[]` | — | **yes** |
+| `tag` | `"div" \| "section" \| "main"` | `"div"` | no |
+| `useAlternateReverse` | `boolean` | `false` | no |
+| `alignment` | `"start" \| "center" \| "end"` | `"center"` | no |
+| `styleClassPassthrough` | `string \| string[]` | `[]` | no |
+
+### `useAlternateReverse`
+
+When `true`, odd-indexed summaries flip their image/content column order (`reverse` prop on each
+`ServiceSummary`), creating a visual zigzag layout. Commonly used on services landing pages with
+three or more services.
+
+### `alignment`
+
+Passed to every `ServiceSummary` as `alignment` — controls vertical alignment of the info column
+content within the grid cell.
+
+## Slots
+
+| Slot | Slot props | Purpose |
+|------|-----------|---------|
+| `summary-link` | `{ serviceData: Service }` | Navigation link below the `whatIsIt` text in each summary |
+
+The slot is forwarded from the inner `ServiceSummary` and receives the current iteration's
+`serviceData` as a scoped prop. It is optional — omitting it leaves that area empty.
+
+## CSS custom properties
+
+| Token | Default | Controls |
+|---|---|---|
+| `--service-summary-grid-row-gap` | `4rem` | Gap between stacked `ServiceSummary` rows |
+
+Each inner `ServiceSummary`'s own tokens (`--service-summary-*`) still apply — see
+`CONSUMER-STYLING.md` in the `service-summary` component folder for the full list.
+
+## Basic usage
+
+```vue
+<ServiceSummaryGrid
+  :services-data="servicesData ?? []"
+  :use-alternate-reverse="true"
+  tag="section"
+>
+  <template #summary-link="{ serviceData }">
+    <LinkText
+      :to="`/services/${serviceData.slug}`"
+      :link-text="`More about ${serviceData.title}`"
+      :style-class-passthrough="['mb-20']"
+    />
+  </template>
+</ServiceSummaryGrid>
+```
+
+## Consumer page boilerplate
+
+```vue
+<template>
+  <div>
+    <NuxtLayout name="default">
+      <template #layout-content>
+        <PageRow tag="div" variant="content" :style-class-passthrough="['mbe-20']">
+          <h1 class="page-heading-1">Our Services</h1>
+        </PageRow>
+
+        <PageRow tag="div" variant="content" :style-class-passthrough="['mbe-20']">
+          <ServiceSummaryGrid
+            :services-data="servicesData ?? []"
+            :use-alternate-reverse="true"
+            tag="section"
+          >
+            <template #summary-link="{ serviceData }">
+              <LinkText
+                :to="`/services/${serviceData.slug}`"
+                :link-text="`More about ${serviceData.title}`"
+                :style-class-passthrough="['mb-20']"
+              />
+            </template>
+          </ServiceSummaryGrid>
+        </PageRow>
+      </template>
+    </NuxtLayout>
+  </div>
+</template>
+
+<script setup lang="ts">
+definePageMeta({ layout: false });
+
+useHead({
+  title: "Services",
+  meta: [{ name: "description", content: "Browse our services" }],
+  bodyAttrs: { class: "page-services" },
+});
+
+const store = useServicesStore();
+const { servicesData } = storeToRefs(store);
+
+if (servicesData.value.length === 0) {
+  await store.fetchServicesData();
+}
+</script>
+
+<style lang="css">
+.page-services {
+  .service-summary-grid {
+    --service-summary-grid-row-gap: 6rem;
+  }
+}
+</style>
+```
+
+## Notes
+
+- Component is auto-imported in Nuxt — no import needed.
+- The `Service` type is imported from `~/types/types.services`.
+- Each `ServiceSummary` receives its array `index` for eager/lazy image loading decisions (first
+  two summaries load eagerly).
+- Pass `servicesData ?? []` as a safe fallback while data loads asynchronously.
+- If a single page needs a per-item entry animation (e.g. wrapping each item in `EntryAnimation`
+  for a scroll-in effect), render `ServiceSummary` directly in your own `v-for` loop instead of
+  using this grid wrapper — `ServiceSummaryGrid` has no slot for wrapping individual items.
+- See [service-summary.md](service-summary.md) for the full `ServiceSummary` prop and slot API.

package/.claude/skills/components/service-summary.md

@@ -0,0 +1,165 @@
+# ServiceSummary Component
+
+## Overview
+
+`ServiceSummary` renders a single service as a compact two-column preview: image on one side,
+eyebrow/title/price-duration pills/`whatIsIt` text on the other, with a `summary-link` slot for
+navigating to the full service page. All routing decisions are delegated to the consumer via the
+slot.
+
+This is a renamed, stripped-down successor to `ServicesSection` — `ServicesSection` used to have
+a second "full mode" (`isSummary: false`) with process/ideal-for/maintenance/FAQ/CTA content, but
+that content shape is now [ServiceDetail](service-detail.md)'s job (a dedicated full-page
+component). `ServiceSummary` only ever renders the compact preview; there is no `isSummary` prop
+because there is no other mode.
+
+Usually consumed via [ServiceSummaryGrid](service-summary-grid.md) rather than directly.
+
+## Props
+
+| Prop | Type | Default | Required |
+|------|------|---------|----------|
+| `serviceData` | `Service` | — | **yes** |
+| `tag` | `"div" \| "section" \| "article" \| "main"` | `"div"` | no |
+| `headerTag` | `"h1" \| "h2" \| "h3"` | `"h2"` | no |
+| `index` | `number` | `0` | no |
+| `alignment` | `"start" \| "center" \| "end"` | `"center"` | no |
+| `reverse` | `boolean` | `false` | no |
+| `styleClassPassthrough` | `string \| string[]` | `[]` | no |
+
+### `index` and image loading
+
+The `index` prop controls both eager/lazy loading and fetch priority. The first two summaries
+(`index` 0 and 1) load eagerly; all others load lazily. Only `index 0` gets `fetchpriority="high"`
+(LCP candidate). Pass the loop index when rendering a list.
+
+### `reverse`
+
+Flips the image to the right column and content to the left (CSS `order: 2` on the image
+wrapper).
+
+### `alignment`
+
+Vertical alignment of the info column's content within the grid cell — useful when the image is
+taller than the text content and you want the eyebrow/title/pills/link block anchored to the top,
+center, or bottom of that space rather than stretching.
+
+## Slots
+
+| Slot | Slot props | Purpose |
+|------|-----------|---------|
+| `summary-link` | `{ serviceData: Service }` | Navigation link below the `whatIsIt` text |
+
+## Duration/price pills
+
+Duration and price render as `DisplayPill` instances (`variant="neutral"`, `size="md"`) — the
+same pattern `ServiceDetail`'s hero uses — rather than the icon+text row the old `ServicesSection`
+had. There are no icon-customisation props (`durationIcon`/`priceIcon` are gone along with the
+icon row).
+
+## Row height and image aspect ratio
+
+By default `.service-summary` has no fixed height — the row sizes to its content: the image
+sizes itself via `--service-summary-image-aspect-ratio` (default `1 / 1`), and the text column
+sizes to its own content, independently. Set `--service-summary-height-mobile`/`-tablet`/
+`-desktop` (on `.service-summary` itself, via `styleClassPassthrough` or page-scoped CSS — there
+is no prop for this) to force a shared row height instead: both the image (which then crops via
+`object-fit: cover`, and the aspect-ratio token stops having any visible effect) and the text
+column (which then has real leftover space for `alignment` to position within) fill that height.
+See `CONSUMER-STYLING.md` for the full token list and the mobile-stacked-layout caveat.
+
+## Basic usage
+
+```vue
+<ServiceSummary :service-data="service" :index="i">
+  <template #summary-link="{ serviceData }">
+    <LinkText
+      :to="`/services/${serviceData.slug}`"
+      :link-text="`More about ${serviceData.title}`"
+      :style-class-passthrough="['mb-20']"
+    >
+      <template #right>
+        <Icon name="mdi:arrow-right" />
+      </template>
+    </LinkText>
+  </template>
+</ServiceSummary>
+```
+
+## Rendering a list
+
+Prefer [ServiceSummaryGrid](service-summary-grid.md) for this — it already handles alternating
+`reverse` and index-based image loading. Rendering the loop by hand looks like:
+
+```vue
+<ServiceSummary
+  v-for="(service, i) in services"
+  :key="service.slug"
+  :service-data="service"
+  :index="i"
+  :reverse="i % 2 !== 0"
+  tag="section"
+>
+  <template #summary-link="{ serviceData }">
+    <LinkText :to="`/services/${serviceData.slug}`" :link-text="`More about ${serviceData.title}`" />
+  </template>
+</ServiceSummary>
+```
+
+## Local style override scaffold
+
+When consuming this component, prefer the `--service-summary-*` CSS custom properties documented
+in `CONSUMER-STYLING.md` (in the component's own folder) over raw class overrides. For anything
+the tokens don't cover, scaffold a style block using `styleClassPassthrough`. Delete the block if
+unused.
+
+See [component-local-style-override.md](../component-local-style-override.md) for the general
+pattern.
+
+```vue
+<ServiceSummary :style-class-passthrough="['my-summary']" :service-data="service">
+  ...
+</ServiceSummary>
+
+<style>
+/* ─── ServiceSummary local overrides ──────────────────────────────
+   Colours, borders, geometry only — do not override behaviour.
+   Delete this block if no overrides are needed.
+   ─────────────────────────────────────────────────────────────────── */
+.service-summary {
+  &.my-summary {
+    --service-summary-image-border-radius: 1.2rem;
+    --service-summary-height-tablet: 32rem;
+    --service-summary-height-desktop: 40rem;
+    --service-summary-image-aspect-ratio: 1 / 1;
+    --service-summary-image-padding-block-mobile: 1.2rem;
+    --service-summary-image-padding-inline-mobile: 1.2rem;
+
+    /* Deeper overrides target the BEM element classes directly, e.g.: */
+    /* .service-summary__pills { } */
+  }
+}
+</style>
+```
+
+## Notes
+
+- Component is auto-imported in Nuxt — no import needed.
+- The `Service` type is imported from `~/types/types.services`.
+- Internal element classes are BEM-namespaced: `service-summary__grid`,
+  `service-summary__image-wrapper`, `service-summary__image`, `service-summary__info-wrapper`,
+  `service-summary__pills`.
+- The section gets `aria-labelledby` automatically when `tag` is `"section"`, `"article"`, or
+  `"aside"`, pointing at the id `ServiceSummary` binds to its own title `HeroText` internally — no
+  consumer action needed. (`tag="main"` renders a `<main>` element but is never auto-labelled; see
+  [component-aria-landmark.md](../component-aria-landmark.md).)
+- For a full single-service page (process, ideal-for, aftercare, FAQs, booking CTA, related
+  services), use [ServiceDetail](service-detail.md) instead — that's the component this one used
+  to duplicate in its old "full mode".
+- The two-column breakpoint, the row-height tokens (`--service-summary-height-*`), and the image
+  padding tokens (`--service-summary-image-padding-block-*`/`-inline-*`, each `-mobile`/`-tablet`/
+  `-desktop`) are all **`@container` queries** against `.service-summary`'s own inline size, not
+  `@media` viewport queries — this keeps the layout correct when the component sits next to a
+  persistent side nav that shrinks its available width without shrinking the viewport. See
+  `CONSUMER-STYLING.md` for the token defaults and fallback
+  chain.

package/.claude/skills/icon-sets.md

@@ -23,7 +23,7 @@ The layer's `modules/icon-sets.ts` runs at dev/build time and logs an info messa
 | `gravity-ui` | `@iconify-json/gravity-ui` | NavigationItems (burger/ellipsis overflow) |
 | `ic` | `@iconify-json/ic` | CarouselBasic, CarouselFlip, CarouselInfinite, SliderGallery, CanvasSwitcher |
 | `lucide` | `@iconify-json/lucide` | ColourFinder, TreatmentConsultant |
-| `material-symbols` | `@iconify-json/material-symbols` | ServicesSection, form components |
+| `material-symbols` | `@iconify-json/material-symbols` | form components |
 | `mdi` | `@iconify-json/mdi` | NavigationHorizontal, form components, ServicesCard |
 | `radix-icons` | `@iconify-json/radix-icons` | InputPasswordWithLabel, InputError, DisplayThemeSwitch |
 

package/.claude/skills/index.md

@@ -32,6 +32,7 @@ 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
 ├── 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-local-style-override.md — styleClassPassthrough + scoped style block for per-usage visual customisation
@@ -69,8 +70,8 @@ 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
     ├── services-card.md        — ServicesCard props (incl. eyebrowConfig/heroConfig), actions slot, CSS tokens, page boilerplate
     ├── services-card-grid.md        — ServicesCardGrid props, config pass-through, CSS tokens, full page boilerplate
-    ├── services-section-grid.md     — ServicesSectionGrid props, useAlternateReverse zigzag layout, page boilerplate
-    ├── services-section.md          — ServicesSection props (incl. heading/CTA copy), summary-link/cta/cta-panel slots, summary vs full mode
+    ├── 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)
     ├── service-detail.md            — ServiceDetail: full service detail page (hero banner, sticky sidebar booking card + related services, closing CTA), headerTag vs subheadingTag split, book-cta/sidebar-note/related-service/final-cta slots
     ├── breadcrumb.md                — Breadcrumb: items (BreadcrumbItem[]) trail, link vs current-page text, CSS token API
     ├── contact-section.md      — ContactSection props (stepperIndicatorSize pass-through), 3-item info+form layout, slot API

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

@@ -0,0 +1,126 @@
+# Component Token Pattern — Public Token + Inline Fallback
+
+## Overview
+
+The standard shape for every overridable CSS value in a component, from now on:
+
+```css
+background-color: var(--{component}-{property}, {real-default-or-shared-fallback});
+```
+
+One name, declared inline at the point of use, with a real default right there in the component
+source. No separate "public token must be declared somewhere else or the component breaks"
+requirement, and no private `--_` indirection standing in for the actual override point.
+`ServicesCard.vue` is the reference implementation — read its `<style>` block for the shape in
+practice.
+
+## Why this replaced the old pattern
+
+Two things used to go wrong, both found while auditing `luxury-locs-by-natasha`'s theming
+overrides (2026-08-25):
+
+1. **Bare `var(--theme-checkbox-symbol-color)` with no fallback anywhere.** The only way for this
+   to resolve to something was a consuming app declaring it globally. When the component was later
+   refactored (buttons moved onto the shared theme-slot system) and stopped reading the token, nothing
+   signalled that to the consumer — the app's declaration became permanently dead, silently. A
+   `var()` with an undefined custom property and no fallback just resolves to the property's
+   initial value; there is no error, no warning, ever.
+2. **Tokens that were "shared" only by accident.** `InputTextCore`, `InputSelectCore`,
+   `InputNumberCore` and the checkbox button all read the exact same `--theme-input-surface`, so a
+   consumer wanting to restyle just text inputs had no way to do that without also restyling every
+   other input type. The private `--_input-text-surface: var(--theme-input-surface);` indirection
+   made this look like it had its own override point when it didn't.
+
+## The three tiers
+
+| Tier | Example | No-fallback allowed? |
+|---|---|---|
+| **1 — theme slots** | `--theme-surface`, `--theme-border`, `--theme-ring`, `--theme-text`, ... (`_theme-slots.css`) | Yes — deliberately global, small, stable set. Changing one is meant to reskin everything that shares it. |
+| **2 — cross-component families** | `--theme-input-surface`, `--theme-checkbox-symbol-surface` | No longer created new. Existing ones stay as the *fallback value* inside Tier 3 tokens, not as the thing components read directly. |
+| **3 — component-scoped** | `--input-button-primary-surface`, `--services-card-border-colour` | Never — always `var(--{component}-token, <fallback>)`. |
+
+Tier 1 is the one deliberate exception. Everything else gets a real component-prefixed name with
+an inline fallback, even if that fallback happens to be a Tier 1 or Tier 2 token underneath.
+
+## Naming convention
+
+`--{component-kebab-name}-{variant-if-any}-{property}[-state]`
+
+- `--input-button-primary-surface` / `-surface-hover` — variant + property + state
+- `--services-card-border-colour` / `-border-colour-hover` — property + state
+- Only add a `-hover`/`-focus`/`-active` suffix if that state's value actually differs from the
+  base token. If hover reuses the exact same value as base (see `InputButtonCore`'s primary text
+  colour, fixed on purpose across states), reuse the base token — don't manufacture a second name
+  for a value that never diverges.
+
+## Multi-level fallback chains are fine
+
+A component that wants to *look like* another component's default (rather than duplicating a
+raw value) chains through it:
+
+```css
+/* InputCopy's copy button defaults to InputButtonCore's primary look */
+--_button-bg: var(--input-copy-button-bg, var(--input-button-primary-surface, var(--theme-surface)));
+```
+
+Three tiers deep here: instance/global override → "look like the primary button" → the theme
+slot underneath that. Each link in the chain is a real, resolvable token — nothing depends on a
+consuming app having declared anything.
+
+## What this does NOT change
+
+- Tier 1 theme slots (`_theme-slots.css`) stay bare `var()`, no fallback, by design.
+- Geometry/typography tokens that already have real component-local defaults
+  (`--button-padding-block: 1rem;` in `06.button-geometry.css`) were never part of this problem —
+  they're declared with real values already, just not inline at the point of use. Leave them.
+
+## Rollout status
+
+- ✅ `InputButtonCore` (primary/secondary/tertiary), `InputCopy`, `PricingCard` — migrated
+  2026-08-25, see their `CONSUMER-STYLING.md` for the full token list. This pass also included a
+  deliberate visual redesign (flat borders, `color-mix()`-darkened hover, transparent resting
+  outline, separated `:focus-visible`), not just the token API change.
+- ✅ `InputCheckboxRadioCore`/`Button` — migrated 2026-08-25, see their `CONSUMER-STYLING.md`.
+  Pure token-rename pass, no visual/default changes (unlike `InputButtonCore`'s redesign above).
+  Added Storybook stories for both (`InputCheckboxRadioCore`, `InputCheckboxRadioButton`) —
+  neither had one before.
+- ✅ `InputTextCore`, `InputSelectCore`, `InputNumberCore` — migrated 2026-08-25, see their
+  `CONSUMER-STYLING.md`. `InputTextCore`/`InputSelectCore` also had this exact problem's original
+  form: a private `--_input-text-*`/`--_input-select-*` naming scheme documented as a second
+  "local override path" alongside the global tokens, added 2026-08-22 (three days before this
+  pattern was formalised) as a workaround for a global-override-not-landing report that was never
+  root-caused. That private-var-as-override-point shape is exactly what this pattern replaces —
+  renamed public with real fallbacks, old two-path docs removed. `InputNumberCore` had no
+  component-scoped tokens at all before this (bare `--theme-input-*` throughout). Added a
+  Storybook story for `InputSelectCore` (didn't have one); `InputNumberCore` still doesn't.
+  `InputTextCore`/`InputSelectCore`'s `.normal` variant also had hover and `:focus-visible` share
+  one token (literally the same rule content duplicated under two selectors) — split into
+  `--input-text-border-hover`/`--input-select-border-hover` alongside the existing `-border-focus`
+  pair, both still defaulting to `--theme-border-focus` so default rendering is unchanged, but
+  mouse and assistive-tech interaction can now be themed independently. `InputNumberCore` has no
+  hover state on its border at all (only a `:focus-visible` box-shadow toggle), so there was
+  nothing to split there.
+- ✅ `ToggleSwitchCore`, `TripleToggleSwitchCore`, `DisplayThemeSwitch` — migrated 2026-08-25, see
+  the first two's `CONSUMER-STYLING.md`. Correction to the two lines this replaces: they claimed
+  `ToggleSwitchCore` read a bare `--theme-toggle-symbol-color-*` — that token doesn't exist
+  anywhere in this codebase and never did; false memory from conflating it with the checkbox
+  fix. `ToggleSwitchCore` itself turned out to be a plain Tier 2 case (real, live tokens, just no
+  component-scoped override point) plus five confirmed-dead private locals (declared, never read
+  anywhere in the file) removed outright. The real dead-token bug was in `TripleToggleSwitchCore`
+  (and duplicated in `DisplayThemeSwitch`'s own override): `--theme-form-radio-border`,
+  `--theme-form-radio-outline`, `--theme-form-checkbox-bg` — all three declared nowhere in the
+  layer. The first two fed two further-unused private locals (removed); the third fed the
+  selected-option marker's background (real bug, narrow impact — only visible when none of the
+  component's `system`/`light`/`dark` `:has()` overrides match).
+
+  Second bug, found while adding the Storybook story `TripleToggleSwitchCore` never had: those
+  `:has()` selectors (and the matching `.option-icon.system/.light/.dark` classes, template-bound
+  to each option's `id`) said `"auto"`, not `"system"` — but the only known consumer,
+  `DisplayThemeSwitch`, has only ever emitted `id`/`value: "system"` (it has to; that literal
+  string is `useSettingsStore.setColourScheme`'s type and the CSS class it applies to `<html>`).
+  `"auto"` never matched anything real, so the system option's green gradient marker had never
+  actually fired — confirmed live before and after the fix. Renamed the selectors to `"system"`
+  rather than the data, since the data value is a real external contract this component's
+  presentational selectors have no business dictating. `TripleToggleSwitchCore` still hardcodes
+  three option values as CSS selectors rather than being genuinely value-agnostic — noted in its
+  `CONSUMER-STYLING.md`, left as a larger separate change.

package/.vscode/srcdev-component-service-summary.code-snippets

@@ -0,0 +1,67 @@
+{
+  "SRCDEV ServiceSummary": {
+    "description": "ServiceSummary — compact preview with summary-link slot",
+    "scope": "vue,html",
+    "body": [
+      "<ServiceSummary",
+      "  :service-data=\"$1service\"",
+      "  :index=\"$2index\"",
+      "  alignment=\"$3center\"",
+      ">",
+      "  <template #summary-link=\"{ serviceData }\">",
+      "    <NuxtLink :to=\"`/services/${serviceData.slug}`\">$4More about {{ serviceData.title }} →</NuxtLink>",
+      "  </template>",
+      "</ServiceSummary>"
+    ]
+  },
+  "SRCDEV ServiceSummary Reversed": {
+    "description": "ServiceSummary with image/content columns swapped",
+    "scope": "vue,html",
+    "body": [
+      "<ServiceSummary :service-data=\"$1service\" :reverse=\"$2true\">",
+      "  <template #summary-link=\"{ serviceData }\">",
+      "    <NuxtLink :to=\"`/services/${serviceData.slug}`\">$3More about {{ serviceData.title }} →</NuxtLink>",
+      "  </template>",
+      "</ServiceSummary>"
+    ]
+  },
+  "SRCDEV ServiceSummaryGrid": {
+    "description": "ServiceSummaryGrid — alternating zigzag listing from a Service[] array",
+    "scope": "vue,html",
+    "body": [
+      "<ServiceSummaryGrid",
+      "  :services-data=\"$1servicesData ?? []\"",
+      "  :use-alternate-reverse=\"$2true\"",
+      ">",
+      "  <template #summary-link=\"{ serviceData }\">",
+      "    <NuxtLink :to=\"`/services/${serviceData.slug}`\">$3More about {{ serviceData.title }} →</NuxtLink>",
+      "  </template>",
+      "</ServiceSummaryGrid>"
+    ]
+  },
+  "SRCDEV ServiceSummary CSS Override": {
+    "description": "CSS override scaffold for ServiceSummary — scope to a page or section class",
+    "scope": "css",
+    "body": [
+      ".$1my-page {",
+      "  .service-summary {",
+      "    --service-summary-grid-gap: ;",
+      "    --service-summary-grid-gap-desktop: ;",
+      "    --service-summary-image-border-radius: ;",
+      "    --service-summary-height-mobile: ;",
+      "    --service-summary-height-tablet: ;",
+      "    --service-summary-height-desktop: ;",
+      "    --service-summary-image-aspect-ratio: ;",
+      "    --service-summary-image-padding-block-mobile: ;",
+      "    --service-summary-image-padding-inline-mobile: ;",
+      "    --service-summary-pills-gap: ;",
+      "    --service-summary-pill-border-colour: ;",
+      "",
+      "    .service-summary__image-wrapper {}",
+      "    .service-summary__info-wrapper {}",
+      "    .service-summary__pills {}",
+      "  }",
+      "}"
+    ]
+  }
+}

package/app/assets/styles/setup/04.elements/forms/06.button-geometry.css

@@ -13,5 +13,14 @@
 
   --button-icon-gap: 1.8rem;
 
-  /* --button-min-height: 4rem; */
+  /* Sized so the button's TOTAL rendered height matches --input-min-height, not its content
+     box alone — .input-button-core keeps box-sizing: content-box (changing that risks shifting
+     icon-only's aspect-ratio: 1 sizing), so its own padding-block and border have to be
+     subtracted back out here, unlike --input-min-height itself which happens to need no such
+     adjustment (InputTextCore has zero padding-block and no full border in its resting state).
+     This is a floor, not a fixed height — icon-only/pill buttons or longer button-text can
+     still grow past it. Textareas are the deliberate exception to this alignment entirely. */
+  --button-min-height: calc(
+    var(--input-min-height) - (2 * var(--button-padding-block)) - (2 * var(--button-border-width))
+  );
 }