srcdev-nuxt-components 9.2.5 → 9.2.7

package/.claude/settings.json

@@ -59,7 +59,41 @@
       "Bash(node -e \"JSON.parse\\(require\\('fs'\\).readFileSync\\('/Users/simoncornforth/websites/nuxt-components/.vscode/srcdev-component-services-section.code-snippets','utf8'\\)\\); console.log\\('valid json'\\)\")",
       "WebFetch(domain:luxury-locs-by-natasha-nuxt3.vercel.app)",
       "Bash(cd /Users/simoncornforth/websites/nuxt-components *)",
-      "Bash(node -e \"JSON.parse\\(require\\('fs'\\).readFileSync\\('/Users/simoncornforth/websites/nuxt-components/.vscode/srcdev-component-banner-video.code-snippets','utf8'\\)\\); console.log\\('valid json'\\)\")"
+      "Bash(node -e \"JSON.parse\\(require\\('fs'\\).readFileSync\\('/Users/simoncornforth/websites/nuxt-components/.vscode/srcdev-component-banner-video.code-snippets','utf8'\\)\\); console.log\\('valid json'\\)\")",
+      "Bash(python3 -c \"import json; json.load\\(open\\('/Users/simoncornforth/websites/nuxt-components/.vscode/srcdev-component-expanding-panel.code-snippets'\\)\\)\")",
+      "Bash(node -e \"JSON.parse\\(require\\('fs'\\).readFileSync\\('/Users/simoncornforth/websites/nuxt-components/.vscode/srcdev-component-expanding-panel.code-snippets','utf8'\\)\\); console.log\\('OK'\\)\")",
+      "Bash(npx eslint *)",
+      "Bash(git stash *)",
+      "Bash(rm /Users/simoncornforth/websites/nuxt-components/app/components/02.molecules/expandable/expanding-panel/tests/repro.spec.ts)",
+      "Bash(npx playwright *)",
+      "Bash(break)",
+      "Bash(cp /tmp/pw-test.mjs /Users/simoncornforth/websites/nuxt-components/pw-test.mjs)",
+      "Bash(node pw-test.mjs)",
+      "Bash(ls ~/Library/Caches/ms-playwright 2>/dev/null)",
+      "Read(//Users/simoncornforth/Library/Caches/ms-playwright/**)",
+      "Bash(lsof -nP -iTCP:3000 -sTCP:LISTEN)",
+      "Bash(ps -p 3241 -o pid,etime,command)",
+      "Bash(pkill -f \"nuxt dev\" -u simoncornforth)",
+      "Bash(lsof -nP -iTCP:3000,3001 -sTCP:LISTEN)",
+      "Bash(curl -s http://localhost:3000/ui/layout-grid-a -o /tmp/a.html -w \"%{http_code}\\\\n\")",
+      "Bash(curl -s http://localhost:3000/ui/layout-grid-b -o /tmp/b.html -w \"%{http_code}\\\\n\")",
+      "Bash(grep -o \"desktopCanvas[^,{]*{[^}]*}\" /tmp/a.html)",
+      "Bash(grep -o \"desktopCanvas[^,{]*{[^}]*}\" /tmp/b.html)",
+      "Bash(curl -s \"http://localhost:3000/_nuxt/components/canvas-switcher/CanvasSwitcher.vue?vue&type=style&index=0&lang.css\")",
+      "Bash(ps -p 9159 -o pid,command)",
+      "Bash(curl -s -o /dev/null -w \"%{http_code}\\\\n\" http://localhost:3000/ui/layout-content-docs)",
+      "Bash(node /private/tmp/claude-501/-Users-simoncornforth-websites-nuxt-components/3e6d42b1-c0ff-4b71-a082-656f9e15e24c/scratchpad/debug-breakpoints.mjs)",
+      "Bash(sed -i '' 's/from \"playwright\"/from \"@playwright\\\\/test\"/' /Users/simoncornforth/websites/nuxt-components/debug-breakpoints.mjs)",
+      "Bash(node debug-breakpoints.mjs)",
+      "Bash(grep -v \"ERR_PACKAGE_PATH_NOT_EXPORTED\\\\|Resolve plugin\\\\|at exportsNot\\\\|at packageExports\\\\|at resolveExports\\\\|at Module\\\\|at wrapResolve\\\\|at resolveForCJS\\\\|at resolve \\\\|at CompilerOptions\\\\|at Object.createParsed\\\\|code: 'ERR'\\\\|^}$\")",
+      "Bash(lsof -i :6006 -sTCP:LISTEN -t)",
+      "Bash(curl -s \"http://127.0.0.1:6006/index.json\")",
+      "Bash(curl -s \"http://127.0.0.1:6006/iframe.html?id=atoms-content-wrappers-contentdocs--default&viewMode=story\" -o /dev/null -w \"%{http_code}\\\\n\")",
+      "Bash(SRCDEV_STANDALONE=true npx playwright test app/components/01.atoms/content-wrappers/docs-pages/playwright/content-docs.playwright.ts --project=chromium --update-snapshots)",
+      "Bash(SRCDEV_STANDALONE=true npx playwright test app/components/01.atoms/content-wrappers/docs-pages/playwright/content-docs.playwright.ts --project=chromium)",
+      "Bash(git rm *)",
+      "Bash(awk '{print $1}')",
+      "Bash(git reset *)"
     ],
     "additionalDirectories": [
       "/Users/simoncornforth/websites/instepreflexology",

package/.claude/skills/components/content-docs.md

@@ -0,0 +1,165 @@
+# ContentDocs Component
+
+## Overview
+
+`ContentDocs` is a docs-page layout shell: a primary nav column, a main content column, and an "on this page" nav column, arranged via CSS `@container` queries (not viewport breakpoints) so the layout adapts to the space actually available — correct even when a consumer page has its own decoration (e.g. a site-wide left nav) eating into the viewport.
+
+`docsNav` and `docsPageNav` are **not** slots — they're rendered internally as `ExpandingPanel` accordions driven by `docsNavItems`/`docsPageNavItems` props. Only `docsContent` remains a slot, since it's arbitrary page content. The two side panels auto force-open/collapse based on the component's own measured width via `useContainerBreakpoints`, and share a native `<details name>` accordion group only on mobile (see "Breakpoint behaviour" below).
+
+---
+
+## Props reference
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `tag` | `"div" \| "section" \| "article" \| "main"` | `"div"` | Root element tag. |
+| `docsNavItems` | `DocsNavItem[]` | `[]` | Items rendered in the `docsNav` panel. Panel (and its `.docs-nav` wrapper) is omitted entirely when empty. |
+| `docsPageNavItems` | `DocsNavItem[]` | `[]` | Items rendered in the `docsPageNav` panel. Panel omitted entirely when empty. |
+| `docsNavLabel` | `string` | `"Navigation"` | Heading text for the `docsNav` panel's `#summary`. |
+| `docsPageNavLabel` | `string` | `"On this page"` | Heading text for the `docsPageNav` panel's `#summary`. |
+| `styleClassPassthrough` | `string \| string[]` | `[]` | Extra CSS classes applied to the root `.content-docs` element. |
+
+`DocsNavItem` (from `~/types/components`):
+
+```ts
+interface DocsNavItem {
+  label: string;
+  to: string;
+  icon?: string; // Icon name, e.g. "lucide:rocket"
+}
+```
+
+## Model
+
+| Model | Type | Default | Notes |
+|-------|------|---------|-------|
+| `v-model:activeNavItem` | `string \| undefined` | `undefined` | The `to` of the currently-active `docsNav` item. Updates automatically on click; bind externally (e.g. to route matching) to control it. |
+| `v-model:activePageNavItem` | `string \| undefined` | `undefined` | Same, for `docsPageNav`. |
+
+Open/expanded state of the two panels is **not** exposed as a model — it's driven entirely by the container-width breakpoint logic (see below), not user-controllable.
+
+---
+
+## Slots
+
+| Slot | Purpose |
+|------|---------|
+| `#docsContent` | Main page content. Only slot this component exposes. |
+
+---
+
+## Usage example
+
+```vue
+<script setup lang="ts">
+import type { DocsNavItem } from "~/types/components";
+
+const docsNavItems: DocsNavItem[] = [
+  { label: "Getting started", to: "/docs", icon: "lucide:rocket" },
+  { label: "Installation", to: "/docs/install" },
+];
+const docsPageNavItems: DocsNavItem[] = [
+  { label: "Overview", to: "/docs#overview" },
+];
+
+const activeNavItem = ref<string | undefined>(docsNavItems[0]?.to);
+const activePageNavItem = ref<string | undefined>(undefined);
+</script>
+
+<template>
+  <ContentDocs
+    v-model:active-nav-item="activeNavItem"
+    v-model:active-page-nav-item="activePageNavItem"
+    :docs-nav-items="docsNavItems"
+    :docs-page-nav-items="docsPageNavItems"
+  >
+    <template #docsContent>
+      <h1>Page title</h1>
+      <p>Page content.</p>
+    </template>
+  </ContentDocs>
+</template>
+```
+
+---
+
+## Breakpoint behaviour
+
+Widths are measured on the component's own root element (`useContainerBreakpoints`, container-name `contentDocs`), **not** the viewport — this is deliberate, so nested page decoration (nav rails, sidebars) that shrinks the actual available space is correctly accounted for. Thresholds: `tablet: 768px`, `desktop: 1024px`, matching the `@container contentDocs` queries in this component's own `<style>` block. If you change one, change the other.
+
+| Width | `docsNav` | `docsPageNav` |
+|-------|-----------|----------------|
+| < 768px (mobile) | collapsible, closed by default | collapsible, closed by default |
+| 768–1023px (tablet) | collapsible, closed by default | **forced open**, no toggle icon |
+| ≥ 1024px (desktop) | **forced open**, no toggle icon | **forced open**, no toggle icon |
+
+### Why the two panels share a `name` only on mobile
+
+Both panels are `ExpandingPanel`s using the native `<details name="...">` grouping feature, which makes same-named panels mutually exclusive (browser force-closes one when the other opens). That's the wanted behaviour on mobile (accordion — only one open at a time), but at tablet/desktop both panels must be open **simultaneously** — a shared name there would make the browser silently force-close one of them the moment both try to be open. So the component computes distinct names (`"docsNav"` / `"docsPageNav"`) once past mobile, and a shared name (`"docsPanelGroup"`) only while mobile.
+
+### Related fix in ExpandingPanel.vue
+
+Building this component's forced-open/forced-closed cycling surfaced a real bug in `ExpandingPanel.vue`: `forceOpened` driving the native `open` attribute fires the element's own `toggle` event, which — before the fix — leaked into `isPanelOpen` (the user-click model), leaving the panel permanently "remembered open" even after `forceOpened` reverted to `false`. Fixed by ignoring toggle events while `forceOpened` is `true`. See `expanding-panel.md` and the `ExpandingPanel.spec.ts` regression test ("does not leak forceOpened into isPanelOpen...").
+
+---
+
+## Icons
+
+`DocsNavItem.icon` is optional (any icon name resolvable by `<Icon>`, e.g. Lucide set: `"lucide:rocket"`). Items without an icon still align correctly with icon-bearing items — the link is `display: grid` with a fixed-width icon column (`--docs-nav-link-icon-size`), not `flex`, so an absent icon doesn't collapse the label leftward.
+
+To move the icon to the end of the link instead of the start, set `--docs-nav-link-icon-order` (or `--docs-page-nav-link-icon-order`) to `rtl` (default `ltr`). This uses a `direction` flip to mirror which physical side the fixed-width column renders on, rather than swapping `grid-column` values directly — swapping columns would put the label into the icon-sized track and squeeze it. The icon and label content reset `direction: ltr` internally so text/glyphs don't visually mirror.
+
+---
+
+## CSS Token Customization
+
+All `--content-docs-*` tokens can be overridden at global, page, or instance scope. Each has a **shared** version (applies to both `docsNav` and `docsPageNav`) and a **per-side** override (`content-docs-nav-*` / `content-docs-page-nav-*`) that falls back to the shared token if unset.
+
+**Heading tokens** (shared: `--content-docs-heading-*`, per-side: `--content-docs-{nav,page-nav}-heading-*`):
+- `-font-size`, `-font-weight`, `-color`, `-bg`, `-margin`, `-padding-block`, `-padding-inline`
+
+**Panel tokens** (shared: `--content-docs-panel-*`, per-side: `--content-docs-{nav,page-nav}-panel-bg`):
+- `-bg` (default: `light-dark(var(--slate-00), var(--slate-10))`, the project's standard card-surface token), `-padding-block`, `-padding-inline`, `-border-radius`
+
+**Link tokens** (shared: `--content-docs-link-*`, per-side: `--content-docs-{nav,page-nav}-link-*`):
+- `-font-size`, `-padding-block`, `-padding-inline`, `-margin-block`, `-border-radius`, `-color`, `-bg`, `-hover-bg`, `-hover-color`, `-active-bg`, `-active-color`
+
+**Column-width tokens** (fixed-width grid tracks at tablet/desktop):
+- `--content-docs-nav-column-width` (default `23rem`, desktop `docsNav` track)
+- `--content-docs-page-nav-column-width` (default `22rem`, desktop `docsPageNav` track)
+- `--content-docs-page-nav-column-width-tablet` (default `20rem`, tablet's single fixed track — `docsNav` is full-width at tablet)
+
+**Icon tokens** (not `content-docs-` prefixed — shared with the link, not per-side by default):
+- `--docs-nav-link-icon-gap`, `--docs-nav-link-icon-size`, `--docs-nav-link-icon-order` (`ltr`/`rtl`), `--docs-page-nav-link-icon-order`
+
+---
+
+## Local style override scaffold
+
+```vue
+<ContentDocs :style-class-passthrough="['my-docs']" ...>
+  ...
+</ContentDocs>
+
+<style>
+.content-docs {
+  &.my-docs {
+    --content-docs-panel-bg: var(--surface-2);
+    --content-docs-link-active-bg: var(--brand-01);
+    --content-docs-link-active-color: var(--brand-10);
+  }
+}
+</style>
+```
+
+---
+
+## Notes
+
+- `docsContent` visibility is slot-detected (`useSlots().docsContent`); `docsNav`/`docsPageNav` visibility is item-array-length-detected (`docsNavItems.length > 0`) — different mechanisms, since only `docsContent` is still a real slot.
+- `NuxtLink` resolved via `resolveComponent("NuxtLink")`, not imported from `#components` — required so this component works inside Storybook (see `feedback_no_components_import_storybook`).
+- Auto-imported in Nuxt — no manual import needed.
+- File: `app/components/01.atoms/content-wrappers/docs-pages/ContentDocs.vue`
+- Types: `app/types/components/content-docs.d.ts` (`DocsNavItem`)
+- Tests: `app/components/01.atoms/content-wrappers/docs-pages/tests/ContentDocs.spec.ts`
+- Demo page: `app/pages/ui/layout-content-docs.vue`

package/.claude/skills/components/expanding-panel.md

@@ -13,6 +13,7 @@
 | `name` | `string` | `useId()` | Identifies the panel. Used in ARIA attributes (`id-{name}-trigger`, `id-{name}-content`). If omitted, a unique id is generated automatically. |
 | `animationDuration` | `number` | `400` | Expand/collapse transition duration in milliseconds. Pass `0` to disable animation. |
 | `forceOpened` | `boolean` | `false` | When `true`, the panel is always open. The toggle icon is hidden and clicks do not close the panel. |
+| `contentIsOnTop` | `boolean` | `false` | When `true`, the content region is taken out of flow and absolutely positioned directly below the summary, raised above surrounding page content via `z-index` — instead of pushing layout down when it opens. Applies a `content-is-on-top` class to the root `.expanding-panel` element (not the content div). |
 | `styleClassPassthrough` | `string \| string[]` | `[]` | Extra CSS classes applied to the root `.expanding-panel` element. |
 
 ## Model
@@ -98,6 +99,29 @@ const isOpen = ref(false);
 </ExpandingPanel>
 ```
 
+### Content on top (overlay instead of pushing layout)
+
+```vue
+<ExpandingPanel name="overlay" :content-is-on-top="true" :style-class-passthrough="['my-overlay-panel']">
+  <template #summary><span>Open me — content overlays what's below</span></template>
+  <template #content>
+    <!-- Wrapper INSIDE the slot carries the visual styling — see
+         "Styling the content when contentIsOnTop" below for why it can't go on .inner -->
+    <div class="my-overlay-panel-body">
+      <p>Positioned absolutely below the summary, doesn't push page content down.</p>
+    </div>
+  </template>
+</ExpandingPanel>
+
+<style>
+.my-overlay-panel-body {
+  background-color: white;
+  padding: 1rem;
+  box-shadow: 0 4px 12px rgb(0 0 0 / 15%);
+}
+</style>
+```
+
 ---
 
 ## ARIA / accessibility
@@ -117,6 +141,36 @@ Always supply a meaningful `name` prop when using multiple panels on the same pa
 
 ---
 
+## Styling the content when contentIsOnTop
+
+When `contentIsOnTop` is `true`, the component deliberately does **not** set `background-color`, `padding`, or a shadow on `.inner` — and consumers must not set them on `.inner` either. Always style a wrapper element placed *inside* the `#content` slot (see example above).
+
+Why: `.expanding-panel-content` collapses via `grid-template-rows: 0fr → 1fr`, and `.inner` relies on `overflow: hidden` on its own box to clip its *children* to 0px when collapsed. `overflow: hidden` clips overflow content, but does not shrink the element's own padding/border/background — those are part of `.inner`'s own box model and still render at full size even while the row track is `0fr` and the panel is closed, producing a visible gap under the summary. A wrapper placed inside the slot is a *child* of `.inner`, so its box — including any padding/background/shadow — is correctly clipped to 0px by `.inner`'s `overflow: hidden` while closed. Baking styling into `.inner` itself would require also gating it on the open state (e.g. `.expanding-panel-details[open] ~ .expanding-panel-content .inner`), which is unnecessary complexity — styling the slot content is the correct fix, not a workaround.
+
+---
+
+## Constraint: don't stack contentIsOnTop panels as direct siblings
+
+`contentIsOnTop` takes the content out of document flow (`position: absolute`) specifically so opening the panel does **not** push whatever comes after it down the page — that's the entire point of the prop. The tradeoff: the panel's own container still only occupies the height of its `<summary>` row, so a *sibling* element positioned directly after it in the DOM sits exactly where the overlay renders. When that sibling is another `ExpandingPanel`, opening the first one visually covers the second one's summary — this happens whether or not the two are grouped via a shared `name` (linked accordion) or opened simultaneously; it isn't specific to linking.
+
+`contentIsOnTop` is designed for a **single** panel overlaying unrelated trailing page content (e.g. a promo banner, a footer strip) — not for stacking multiple `contentIsOnTop` panels beside each other expecting normal accordion behaviour. If you need several linked/stacked panels, leave `contentIsOnTop` off (the default, in-flow layout handles that case correctly).
+
+---
+
+## CSS Token Customization
+
+All `--expanding-panel-*` tokens can be overridden at global, page, or instance scope. See `CONSUMER-STYLING.md` in the component directory for full token documentation and examples.
+
+**Tokens:**
+
+- `--expanding-panel-summary-gap` — gap between summary label and icon
+- `--expanding-panel-summary-padding-block` — summary row vertical padding
+- `--expanding-panel-icon-size` — toggle icon size
+- `--expanding-panel-content-z-index` — stacking order when `contentIsOnTop` is `true`
+- `--expanding-panel-content-gap` — space between summary and content when `contentIsOnTop` is `true`
+
+---
+
 ## Local style override scaffold
 
 When consuming this component, scaffold a style block using `styleClassPassthrough`. Delete the block if unused.
@@ -150,6 +204,7 @@ See [component-local-style-override.md](../component-local-style-override.md) fo
 ## Notes
 
 - The open/close animation uses `grid-template-rows: 0fr → 1fr` — no JS height measurement needed.
+- `content-is-on-top` is applied to the root `.expanding-panel` element, not `.expanding-panel-content` — style overrides must scope through it, e.g. `.expanding-panel.my-panel .expanding-panel-content .inner { ... }`.
 - When `forceOpened` is `true`, `open` stays `true` regardless of `v-model`, but `v-model` still updates internally on clicks (useful if you later set `forceOpened` back to `false`).
 - Group panels into a native accordion (only one open at a time) by passing the same `name` to multiple panels or use `AccordianCore` which handles this automatically.
 - Auto-imported in Nuxt — no manual import needed.

package/.claude/skills/index.md

@@ -28,6 +28,7 @@ Each skill is a single markdown file named `<area>-<task>.md`.
 ├── testing-add-playwright.md   — create a Playwright visual regression test
 ├── setup-postinstall.md             — automate nuxt prepare + Claude skills copy via postinstall so neither is forgotten after npm install
 ├── theming-colour-ramps.md          — parametric oklch ramp system: formula, named palettes, semantic slots, generator, consumer setup
+├── theming-typography-tokens.md     — --step-N fluid font-size scale, 62.5% root reset gotcha (1rem=10px, not 16px), page-heading-*/page-body-* utility classes
 ├── 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 token category (palette, buttons, inputs) without a full theme replacement
 ├── colour-scheme-disable.md         — disable light/dark scheme support in a consumer app
@@ -45,7 +46,7 @@ Each skill is a single markdown file named `<area>-<task>.md`.
 ├── vercel-node-version.md            — .nvmrc pinned to Node 24 is required; without it Vercel uses npm 10 which crashes on versionless optional stubs
 ├── robots-env-aware.md               — @nuxtjs/robots: allow crawling on prod domain only, block on preview/staging via env var
 ├── new-app-scaffold.md               — scaffold a new Nuxt consumer app extending this layer (package.json, nuxt.config, app structure, CLAUDE.md)
-├── qa-panel.md                       — collapsible dev-only panel for toggling component props live on a page (demo pages and consuming apps)
+├── qa-panel.md                       — collapsible panel for toggling component props live on a page (always on for /pages/ui/ demo pages; gate with isDev in consuming apps)
 ├── release-notes.md                  — produce release notes as a fenced markdown block from git log
 ├── pull-request-description.md       — produce a PR description as a fenced markdown block from git diff vs main
 ├── using-component-skills.md         — discover and use component skills in consumer apps: where skills land, browsing patterns, workflow for deciding build vs. compose
@@ -71,7 +72,8 @@ Each skill is a single markdown file named `<area>-<task>.md`.
     ├── services-section.md          — ServicesSection props (incl. heading/CTA copy), summary-link/cta/cta-panel slots, summary vs full mode
     ├── contact-section.md      — ContactSection props (stepperIndicatorSize pass-through), 3-item info+form layout, slot API
     ├── stepper-list.md         — StepperList dynamic slots (item-{n}/indicator-{n}), props, connector behaviour
-    ├── expanding-panel.md      — ExpandingPanel v-model, forceOpened, slots (summary/icon/content), ARIA wiring
+    ├── expanding-panel.md      — ExpandingPanel v-model, forceOpened, contentIsOnTop overlay mode, slots (summary/icon/content), ARIA wiring, CSS token API
+    ├── content-docs.md         — ContentDocs docs-page shell: prop-driven docsNav/docsPageNav (not slots), DocsNavItem icons, container-width breakpoint behaviour, shared/per-side CSS token API
     ├── glass-panel.md          — GlassPanel props, slots, CSS token API (--glass-panel-bg/border-color/shadow/highlight), theming override
     ├── navigation-horizontal.md — NavigationHorizontal props, NavItemData type, CSS token API, import path gotcha
     ├── pricing-card.md         — PricingCard: SaaS-style plan card with highlight, feature list, #cta slot for button customization, CSS token API

package/.claude/skills/qa-panel.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-A collapsible dev-only panel that lets you toggle component props live on a page — without touching the component or breaking the visual layout. Hidden in production via `import.meta.dev`. Uses a native `<details>`/`<summary>` so it takes up no space when collapsed. Useful on both demo pages in this library and on pages in consuming apps.
+A collapsible panel that lets you toggle component props live on a page — without touching the component or breaking the visual layout. Uses a native `<details>`/`<summary>` so it takes up no space when collapsed. Every page under `app/pages/ui/` in this library is a demo-only page already, so the panel always renders there — no `isDev` gate needed. If you add one to a page in a consuming app that also serves real production traffic, gate it behind that app's own dev/staging check.
 
 ## Structure
 
@@ -19,8 +19,7 @@ Each group controls one prop. The status `<code>` in the summary mirrors the cur
 ### 1. Add the reactive state to `<script setup>`
 
 ```ts
-// ── QA controls (dev only) ────────────────────────────────────────
-const isDev = import.meta.dev;
+// ── QA controls ────────────────────────────────────────────────────
 
 // One ref per controllable prop
 const qaMyBoolean = ref(true);
@@ -47,8 +46,8 @@ const myStringPresets = ["a", "b", "c"] as const;
 Place directly above (or below) the component being QA'd, outside any layout wrapper that clips content:
 
 ```vue
-<!-- ── QA Panel (dev only) ───────────────────────────────── -->
-<div v-if="isDev" class="qa-panel">
+<!-- ── QA Panel ─────────────────────────────────────────────── -->
+<div class="qa-panel">
   <details class="qa-panel__details">
     <summary class="qa-panel__summary">
       <span class="qa-panel__title">QA — MyComponent</span>
@@ -219,7 +218,7 @@ Scope inside your page body class (e.g. `.my-page`) so styles don't bleed. The p
 
 ## Notes
 
-- **Production safety**: `import.meta.dev` is `false` in production builds — the entire `v-if="isDev"` block is tree-shaken. No runtime cost.
+- **Consuming apps on real production traffic**: if the page hosting the panel isn't demo-only (unlike everything under `app/pages/ui/` in this library), gate the panel with that app's own dev/staging check, e.g. `v-if="isDev"` with `const isDev = import.meta.dev;`. `import.meta.dev` is `false` in production builds, so the gated block is tree-shaken with no runtime cost.
 - **Consuming apps**: The active chip color (`oklch(55% 0.18 240)`) is a neutral blue. Replace with a brand accent token if preferred: `background: var(--color-brand-accent)`.
 - **Panel placement**: Outside any `overflow: hidden` or clipping container, otherwise the panel may be clipped or push layout unexpectedly. Placing it as a direct sibling of the component row works well.
 - **Computed CSS vars**: When a prop controls a CSS custom property (e.g. max-height tiers), use a `computed` that returns a style object and bind it with `:style` on the component wrapper:

package/.claude/skills/theming-typography-tokens.md

@@ -0,0 +1,109 @@
+# Typography Tokens
+
+## Overview
+
+`html { font-size: 62.5%; }` is set globally by this layer (`setup/01.config/_head.css`), which
+redefines `1rem` to `10px` instead of the browser default `16px`. Every font-size in this design
+system is calibrated against that 10px root, via the fluid `--step-N` custom properties and the
+`page-heading-*`/`page-body-*` utility classes built on top of them — never a raw `rem` literal.
+
+**The trap**: a raw value like `font-size: 0.85rem` looks like a reasonable ~13.6px in a normal
+16px-root project. In a consumer of this layer it renders at 8.5px — because `1rem` here is `10px`,
+not `16px`. This silently produces illegibly small text with no error or warning; it only shows up
+visually. Always use `var(--step-N)` (or a `page-heading-*`/`page-body-*` utility class) instead of
+a raw `rem`/`px` font-size when writing new component or page-local CSS in a consumer app.
+
+## The token scale
+
+Defined in `setup/05.typography/01.tokens/_reponsive-font-sizes.css`, on `:where(html)`. Each step
+is a fluid `clamp()` — smallest at narrow viewports, largest at wide ones:
+
+| Token | Approx. range (px, at 10px root) |
+|---|---|
+| `--step-1` | ~7.8–8 |
+| `--step-2` | ~9.4–10 |
+| `--step-3` | ~11.25–12.5 |
+| `--step-4` | ~13.5–15.6 (body default) |
+| `--step-5` | ~16.2–19.5 |
+| `--step-6` | ~19.4–24.4 |
+| `--step-7` | ~23.3–30.5 |
+| `--step-8` | ~28–38.1 |
+| `--step-9` | ~33.6–47.7 |
+| `--step-10` | ~40.3–59.6 |
+
+Plus purpose-specific tokens for hero/eyebrow text: `--hero-text-display`, `--hero-text-title`,
+`--hero-text-heading`, `--hero-text-subheading`, `--hero-text-label`, `--eyebrow-text-large`,
+`--eyebrow-text-medium`, `--eyebrow-text-small`.
+
+`body` itself is set to `font-size: var(--step-4)` (`setup/01.config/_head.css`), so plain `<p>`/`<li>`
+text inherits the correct scaled size automatically — you only need to reach for a token explicitly
+when setting a font-size on something other than ambient body text (labels, nav links, table cells,
+code blocks, etc.).
+
+## Utility classes built on the scale
+
+`setup/05.typography/02.utility-classes/_font-classes-page-heading.css` and
+`_font-classes-page-body.css` map the steps to semantic classes:
+
+| Class | Token |
+|---|---|
+| `.page-heading-1` | `--step-8` |
+| `.page-heading-2` | `--step-7` |
+| `.page-heading-3` | `--step-6` |
+| `.page-heading-4` | `--step-5` |
+| `.page-heading-5` | `--step-4` |
+| `.page-heading-6` | `--step-3` |
+| `.page-body-large` | `--step-6` |
+| `.page-body-medium` | `--step-5` |
+| `.page-body-normal` | `--step-4` |
+| `.page-body-small` | `--step-3` |
+| `.page-body-xsmall` | `--step-2` |
+
+`page-body-*` also has `-light`/`-semibold`/`-bold` weight variants (e.g. `.page-body-normal-bold`).
+
+## Steps
+
+### 1. Prefer the utility classes for standalone text
+
+If a heading or paragraph in your markup can just be a plain element with one of these classes,
+use the class rather than writing new CSS:
+
+```vue
+<h1 class="page-heading-1">Dashboard</h1>
+<p class="page-body-normal">Overview of your account activity.</p>
+```
+
+### 2. Use `var(--step-N)` inside component-scoped CSS
+
+For font-sizes inside a component's own `<style>` block (sidebar labels, table text, code blocks,
+badges, etc.), reference the token directly rather than a class:
+
+```css
+.my-component__label {
+  font-size: var(--step-4);
+}
+```
+
+Don't go below `--step-4` for anything a user is expected to actually read (nav links, table
+cells, code, captions) — `--step-2`/`--step-3` look reasonable in isolation but read as too small
+once placed in real dense UI (sidebars, TOCs, code blocks) next to normal body text. Reserve
+`--step-1`–`--step-3` for genuinely decorative/secondary marks (eyebrow labels, badge counters)
+where legibility isn't the point.
+
+### 3. Pick a step by relative scale, not by trying to hit a literal px target
+
+Since every step is fluid (`clamp()`), don't reason about "I want 12px" — reason about it relative
+to body text (`--step-4`): one step down (`--step-3`) for slightly smaller text (small labels, table
+cells), two steps down (`--step-2`) for compact caption/label text (sidebar nav group titles, tab
+labels), and so on upward for headings.
+
+## Notes
+
+- This applies to *any* consumer app extending this layer, not just components inside this repo —
+  a local/custom component written in a consuming app (e.g. a docs page's own sidebar/TOC component)
+  needs the same `var(--step-N)` treatment, since it inherits the same `62.5%` root reset via the
+  layer's global CSS.
+- Caught in the wild: a docs-page sidebar/TOC/code-block set of components in a consumer app
+  (`guidemyhair`) shipped with raw `0.75rem`/`0.85rem`/`0.9rem` font-sizes, assuming a 16px root —
+  rendered far too small once the layer's `62.5%` reset applied. Fixed by switching every one to the
+  matching `--step-N` token.

package/.vscode/srcdev-component-content-docs.code-snippets

@@ -0,0 +1,129 @@
+{
+  "SRCDEV ContentDocs Basic": {
+    "description": "ContentDocs with nav + on-this-page items and active-item v-models",
+    "scope": "vue,html",
+    "body": [
+      "<ContentDocs",
+      "  v-model:active-nav-item=\"$1activeNavItem\"",
+      "  v-model:active-page-nav-item=\"$2activePageNavItem\"",
+      "  :docs-nav-items=\"$3docsNavItems\"",
+      "  :docs-page-nav-items=\"$4docsPageNavItems\"",
+      ">",
+      "  <template #docsContent>",
+      "    <p>$5Page content goes here.</p>",
+      "  </template>",
+      "</ContentDocs>"
+    ]
+  },
+  "SRCDEV ContentDocs Custom Labels" : {
+    "description": "ContentDocs with custom docsNav / docsPageNav panel headings",
+    "scope": "vue,html",
+    "body": [
+      "<ContentDocs",
+      "  v-model:active-nav-item=\"$1activeNavItem\"",
+      "  v-model:active-page-nav-item=\"$2activePageNavItem\"",
+      "  :docs-nav-items=\"$3docsNavItems\"",
+      "  :docs-page-nav-items=\"$4docsPageNavItems\"",
+      "  docs-nav-label=\"$5Sections\"",
+      "  docs-page-nav-label=\"$6Contents\"",
+      ">",
+      "  <template #docsContent>",
+      "    <p>$7Page content goes here.</p>",
+      "  </template>",
+      "</ContentDocs>"
+    ]
+  },
+  "SRCDEV ContentDocs Items Script": {
+    "description": "docsNavItems / docsPageNavItems + active-item refs for ContentDocs",
+    "scope": "typescript,vue",
+    "body": [
+      "const docsNavItems: DocsNavItem[] = [",
+      "  { label: \"$1Getting started\", to: \"$2/docs\" },",
+      "];",
+      "",
+      "const docsPageNavItems: DocsNavItem[] = [",
+      "  { label: \"$3Overview\", to: \"$2/docs#overview\" },",
+      "];",
+      "",
+      "const activeNavItem = ref<string | undefined>(docsNavItems[0]?.to);",
+      "const activePageNavItem = ref<string | undefined>(undefined);"
+    ]
+  },
+  "SRCDEV ContentDocs Items With Icons Script": {
+    "description": "docsNavItems / docsPageNavItems with per-item icons for ContentDocs",
+    "scope": "typescript,vue",
+    "body": [
+      "const docsNavItems: DocsNavItem[] = [",
+      "  { label: \"$1Getting started\", to: \"$2/docs\", icon: \"$3lucide:rocket\" },",
+      "];",
+      "",
+      "const docsPageNavItems: DocsNavItem[] = [",
+      "  { label: \"$4Overview\", to: \"$2/docs#overview\", icon: \"$5lucide:list\" },",
+      "];",
+      "",
+      "const activeNavItem = ref<string | undefined>(docsNavItems[0]?.to);",
+      "const activePageNavItem = ref<string | undefined>(undefined);"
+    ]
+  },
+  "SRCDEV ContentDocs CSS Override — Icons": {
+    "description": "CSS override scaffold for ContentDocs nav-link icon tokens (gap, size, and start/end order)",
+    "scope": "css",
+    "body": [
+      ".$1my-content-docs {",
+      "  .content-docs {",
+      "    --docs-nav-link-icon-gap: $2;",
+      "    --docs-nav-link-icon-size: $3;",
+      "    --docs-nav-link-icon-order: $4rtl; /* icon at the end */",
+      "    --docs-page-nav-link-icon-order: $5ltr; /* icon at the start (default) */",
+      "  }",
+      "}"
+    ]
+  },
+  "SRCDEV ContentDocs CSS Override — Shared Theme": {
+    "description": "CSS override scaffold for ContentDocs heading/panel/link tokens, applied to both docsNav and docsPageNav at once",
+    "scope": "css",
+    "body": [
+      ".$1my-content-docs {",
+      "  .content-docs {",
+      "    --content-docs-heading-font-size: $2;",
+      "    --content-docs-heading-color: $3;",
+      "    --content-docs-heading-bg: $4;",
+      "    --content-docs-heading-padding-block: $5;",
+      "",
+      "    --content-docs-panel-bg: $6;",
+      "    --content-docs-panel-padding-block: $7;",
+      "    --content-docs-panel-padding-inline: $8;",
+      "",
+      "    --content-docs-link-font-size: $9;",
+      "    --content-docs-link-color: $10;",
+      "    --content-docs-link-hover-bg: $11;",
+      "    --content-docs-link-active-bg: $12;",
+      "    --content-docs-link-active-color: $13;",
+      "",
+      "    --content-docs-nav-column-width: $14;",
+      "    --content-docs-page-nav-column-width: $15;",
+      "    --content-docs-page-nav-column-width-tablet: $16;",
+      "  }",
+      "}"
+    ]
+  },
+  "SRCDEV ContentDocs CSS Override — Per Side": {
+    "description": "CSS override scaffold for independently theming docsNav vs docsPageNav heading/panel/link tokens",
+    "scope": "css",
+    "body": [
+      ".$1my-content-docs {",
+      "  .content-docs {",
+      "    /* docsNav (primary) */",
+      "    --content-docs-nav-heading-color: $2;",
+      "    --content-docs-nav-panel-bg: $3;",
+      "    --content-docs-nav-link-active-bg: $4;",
+      "",
+      "    /* docsPageNav (on-this-page / secondary) */",
+      "    --content-docs-page-nav-heading-color: $5;",
+      "    --content-docs-page-nav-panel-bg: $6;",
+      "    --content-docs-page-nav-link-active-bg: $7;",
+      "  }",
+      "}"
+    ]
+  }
+}