@thewhatmatters/wmds 0.2.0

package/dist/typography.css

@@ -0,0 +1,224 @@
+/**
+ * WMDS typography sheet — Astryx-aligned geometric scale + semantic type tokens.
+ * Reference: https://astryx.atmeta.com/docs/typography
+ *
+ * Layer 1: --font-size-* geometric ramp (14px base × 1.2 ratio).
+ * Layer 2: --text-*-{size,weight,leading} semantic triplets.
+ * Layer 3: @utility type-* composites for components (via typographyClass).
+ */
+:root {
+  /* Scale parameters */
+  --type-scale-base: 0.875rem;
+  --type-scale-ratio: 1.2;
+
+  /* Geometric size ramp */
+  --font-size-4xs: 0.375rem;
+  --font-size-3xs: 0.4375rem;
+  --font-size-2xs: 0.5rem;
+  --font-size-xs: 0.625rem;
+  --font-size-sm: 0.75rem;
+  --font-size-base: 0.875rem;
+  --font-size-lg: 1.0625rem;
+  --font-size-xl: 1.25rem;
+  --font-size-2xl: 1.5rem;
+  --font-size-3xl: 1.8125rem;
+  --font-size-4xl: 2.1875rem;
+  --font-size-5xl: 2.625rem;
+  --font-size-6xl: 3.15rem;
+
+  /* Semantic weights */
+  --font-weight-normal: 400;
+  --font-weight-medium: 500;
+  --font-weight-semibold: 600;
+  --font-weight-bold: 700;
+
+  /* Headings */
+  --text-heading-1-size: var(--font-size-2xl);
+  --text-heading-1-weight: var(--font-weight-semibold);
+  --text-heading-1-leading: 1.3333;
+
+  --text-heading-2-size: var(--font-size-xl);
+  --text-heading-2-weight: var(--font-weight-semibold);
+  --text-heading-2-leading: 1.4;
+
+  --text-heading-3-size: var(--font-size-lg);
+  --text-heading-3-weight: var(--font-weight-semibold);
+  --text-heading-3-leading: 1.4118;
+
+  --text-heading-4-size: var(--font-size-base);
+  --text-heading-4-weight: var(--font-weight-semibold);
+  --text-heading-4-leading: 1.4286;
+
+  --text-heading-5-size: var(--font-size-sm);
+  --text-heading-5-weight: var(--font-weight-semibold);
+  --text-heading-5-leading: 1.6667;
+
+  --text-heading-6-size: var(--font-size-xs);
+  --text-heading-6-weight: var(--font-weight-semibold);
+  --text-heading-6-leading: 1.6;
+
+  /* Display — fluid size: mobile floor → desktop ceiling (review at 390 / 768 / 1280). */
+  --text-display-1-size-min: 2.5rem; /* 40px — mobile */
+  --text-display-1-size-max: 5rem; /* 80px — desktop */
+  --text-display-1-size: clamp(
+    var(--text-display-1-size-min),
+    calc(1.4rem + 4.5vw),
+    var(--text-display-1-size-max)
+  );
+  --text-display-1-weight: var(--font-weight-bold);
+  --text-display-1-leading: 1.15;
+  --text-display-1-tracking: -0.04em;
+
+  --text-display-2-size-min: 2rem;
+  --text-display-2-size-max: 3.15rem;
+  --text-display-2-size: clamp(
+    var(--text-display-2-size-min),
+    calc(1.25rem + 2.4vw),
+    var(--text-display-2-size-max)
+  );
+  --text-display-2-weight: var(--font-weight-semibold);
+  --text-display-2-leading: 1.2;
+
+  --text-display-3-size-min: 1.5rem;
+  --text-display-3-size-max: 2.1875rem;
+  --text-display-3-size: clamp(
+    var(--text-display-3-size-min),
+    calc(1.1rem + 1.4vw),
+    var(--text-display-3-size-max)
+  );
+  --text-display-3-weight: var(--font-weight-semibold);
+  --text-display-3-leading: 1.24;
+
+  /* Body & UI */
+  --text-large-size: var(--font-size-lg);
+  --text-large-weight: var(--font-weight-semibold);
+  --text-large-leading: 1.4118;
+
+  --text-body-size: var(--font-size-base);
+  --text-body-weight: var(--font-weight-normal);
+  --text-body-leading: 1.4286;
+
+  --text-label-size: var(--font-size-base);
+  --text-label-weight: var(--font-weight-medium);
+  --text-label-leading: 1.4286;
+
+  --text-supporting-size: var(--font-size-sm);
+  --text-supporting-weight: var(--font-weight-normal);
+  --text-supporting-leading: 1.6667;
+
+  --text-code-size: var(--font-size-base);
+  --text-code-weight: var(--font-weight-normal);
+  --text-code-leading: 1.4286;
+
+  /** WMDS extension — fixed-height control shells (Button, Chip, Input). Phase 4 migrates atoms here. */
+  --text-control-size: var(--font-size-base);
+  --text-control-weight: var(--font-weight-medium);
+  --text-control-leading: 1;
+}
+
+/* Semantic type utilities — size + weight + leading from tokens; color via text-fg / text-muted. */
+@utility type-display-1 {
+  font-family: var(--font-family-heading);
+  font-size: var(--text-display-1-size);
+  font-weight: var(--text-display-1-weight);
+  line-height: var(--text-display-1-leading);
+  letter-spacing: var(--text-display-1-tracking);
+}
+
+@utility type-display-2 {
+  font-family: var(--font-family-heading);
+  font-size: var(--text-display-2-size);
+  font-weight: var(--text-display-2-weight);
+  line-height: var(--text-display-2-leading);
+}
+
+@utility type-display-3 {
+  font-family: var(--font-family-heading);
+  font-size: var(--text-display-3-size);
+  font-weight: var(--text-display-3-weight);
+  line-height: var(--text-display-3-leading);
+}
+
+@utility type-heading-1 {
+  font-family: var(--font-family-heading);
+  font-size: var(--text-heading-1-size);
+  font-weight: var(--text-heading-1-weight);
+  line-height: var(--text-heading-1-leading);
+}
+
+@utility type-heading-2 {
+  font-family: var(--font-family-heading);
+  font-size: var(--text-heading-2-size);
+  font-weight: var(--text-heading-2-weight);
+  line-height: var(--text-heading-2-leading);
+}
+
+@utility type-heading-3 {
+  font-family: var(--font-family-heading);
+  font-size: var(--text-heading-3-size);
+  font-weight: var(--text-heading-3-weight);
+  line-height: var(--text-heading-3-leading);
+}
+
+@utility type-heading-4 {
+  font-family: var(--font-family-heading);
+  font-size: var(--text-heading-4-size);
+  font-weight: var(--text-heading-4-weight);
+  line-height: var(--text-heading-4-leading);
+}
+
+@utility type-heading-5 {
+  font-family: var(--font-family-heading);
+  font-size: var(--text-heading-5-size);
+  font-weight: var(--text-heading-5-weight);
+  line-height: var(--text-heading-5-leading);
+}
+
+@utility type-heading-6 {
+  font-family: var(--font-family-heading);
+  font-size: var(--text-heading-6-size);
+  font-weight: var(--text-heading-6-weight);
+  line-height: var(--text-heading-6-leading);
+}
+
+@utility type-large {
+  font-family: var(--font-family-body);
+  font-size: var(--text-large-size);
+  font-weight: var(--text-large-weight);
+  line-height: var(--text-large-leading);
+}
+
+@utility type-body {
+  font-family: var(--font-family-body);
+  font-size: var(--text-body-size);
+  font-weight: var(--text-body-weight);
+  line-height: var(--text-body-leading);
+}
+
+@utility type-label {
+  font-family: var(--font-family-body);
+  font-size: var(--text-label-size);
+  font-weight: var(--text-label-weight);
+  line-height: var(--text-label-leading);
+}
+
+@utility type-supporting {
+  font-family: var(--font-family-body);
+  font-size: var(--text-supporting-size);
+  font-weight: var(--text-supporting-weight);
+  line-height: var(--text-supporting-leading);
+}
+
+@utility type-code {
+  font-family: var(--font-family-code);
+  font-size: var(--text-code-size);
+  font-weight: var(--text-code-weight);
+  line-height: var(--text-code-leading);
+}
+
+@utility type-control {
+  font-family: var(--font-family-body);
+  font-size: var(--text-control-size);
+  font-weight: var(--text-control-weight);
+  line-height: var(--text-control-leading);
+}

package/docs/README.md

@@ -0,0 +1,27 @@
+# WMDS docs for apps and agents
+
+These files ship in the npm package at `node_modules/@thewhatmatters/wmds/docs/`. They match the installed version, so an agent in a consuming app reads them instead of guessing from memory or from a newer Storybook.
+
+| File | What it is |
+|------|------------|
+| `exports.json` | Every export with its tier, category, one-line summary, Storybook page, and the ids of its patterns. Also the CSS entries, peer dependencies, planned components, and lib helpers. |
+| `components.md` | The component and token contracts: props, patterns, composition rules, and what not to do. |
+| `component-contracts.md` | Long-form contracts for FooterReveal, HeroTileStack, TextSequence, ScrollHorizontal, RiveHand, and PromptBar. |
+| `patterns/index.json` | One row per pattern: id, Storybook title, pattern name, file. |
+| `patterns/<id>.tsx` | A pattern's Show code, exactly as Storybook shows it, with a header naming the pattern and the package version. |
+| `consumer-agents.md` | A block to paste into a consuming repo's `AGENTS.md` / `CLAUDE.md`. |
+| `../CHANGELOG.md` | Every release, with the **Consumer actions** an app takes to move to it. |
+| `../CONSUMING.md` | Install, styles, dark mode, grid, and per-component setup. |
+
+## How to use them
+
+1. **Find the component.** Search `exports.json` by name, category, or summary. Planned components are listed under `planned` — they do not exist yet.
+2. **Read its contract** in `components.md` (and `component-contracts.md` for the six long ones).
+3. **Use a pattern when one matches.** Look up the component's `patterns` ids, open `patterns/<id>.tsx`, and copy the file verbatim, header included. The header lets an upgrade find every pasted pattern (`grep -r "@thewhatmatters/wmds@" src`).
+4. **Missing something?** Do not hand-roll it in the app. Report the gap to WMDS (see `consumer-agents.md`).
+
+Storybook ids in these files (`?path=/story/<id>`, `?path=/docs/<id>--docs`) append to the WMDS Storybook URL.
+
+## In the WMDS repository
+
+`exports.json`, `components.md`, and `patterns/` are generated by `npm run docs:generate` from `src/package.manifest.ts`, `src/storybook/componentCatalog.ts`, `AGENTS.md`, and each story's Show code. CI runs `npm run check:docs` and fails when a committed file differs from Storybook. The rest of this folder — `adr/`, `audits/`, `releasing.md` — is for WMDS contributors and does not ship.

package/docs/component-contracts.md

@@ -0,0 +1,27 @@
+# Component contracts — long form
+
+The full contracts for the marketing and prompt components. `AGENTS.md` carries a short summary of each and points here. Read the section before changing the component, its stories, or a page that composes it. Storybook **Pattern** stories stay the copy source; this file records the details behind them.
+
+## FooterReveal
+
+marketing page root — **FooterReveal.Content** (cover, at least `100dvh`, page background, z-index 1) then **FooterReveal.Footer** (sticky bottom, z-index -1). Scrubs opacity, scale (origin `50% 100%`), and blur (12px → 0) across one footer-height of scroll via `useScroll` / `useTransform`. `will-change` only while that scrub is in progress. Reduced motion: fully visible, no scale or blur, including SSR (`useSyncExternalStore` server snapshot is sharp). The root does not clip, so **GridOverlay** guides still cover the hero and stop at the footer. The marketing hero's guide host is `grid-page bg-body !py-0`, so the expanded **ScrollHorizontal** tile meets the footer with no page-background strip. On the navy field, footer guides use the same tracks and sit under the headline and CTA (`z-0` under `z-[1]`). The wordmark spans the footer width and is cropped at the bottom of the brand panel. Field: **`footerRevealFieldClasses`** (`bg-brand` / `text-on-brand`, `#011272`). The wordmark uses **`--color-brand-soft`**. **FooterReveal.Brand** — headline, **Button** `role="inverse"` `type="button"` (`onCtaClick` opens the project modal; optional `ctaHref` renders an anchor only when a link is passed), `socialLinks` (label + href; `https` opens in a new tab with `rel="noopener"`), and an `aria-hidden` wordmark that spans the footer width (`100cqi` divided by the measured advance width in em) and is cropped at the bottom edge. Links on that field: **`footerRevealFieldLinkClasses`**. Scrollbar stays visible (`scrollbar-gutter: stable` in the grid). Paste **Components/FooterReveal → Pattern — marketing page** or **Pattern — marketing hero**. **FooterReveal.Ruled** is the cream marketing footer on **`footerRevealRuledFieldClasses`** (`bg-body` / `text-brand`, `#011272`). The field and the ruled shell are at least `100vh` and grow when the content is taller. The nav, wordmark, and quiet row are one block, vertically centered in the field when that block fits. Top padding still clears the pinned site nav. A centered stack — Services, Resources, About — is **TextLink**. The list sets Geist sans (the heading and body face) so the links inherit it: `--font-size-4xl` below `sm`, `4rem` from `sm` (no type token is 4rem). Those three links set `!text-brand` (`#011272`) so **TextLink**'s `text-fg` does not paint them near black. **TextLink** keeps its solid underline, medium weight, and focus ring. The WhatMatters wordmark is fitted to the footer width (`100cqi` / measured em) and stays fully visible at 390, 1440, and 2560. The quiet row is the WM mark with WhatMatters © 2026, randy@whatmatters.so, and Created by WhatMatters 2024–2026. Below `md` that row stacks and stays centered. There is no cropped wordmark, no two-column nav, and no social row. Dark theme keeps the field on `--color-on-brand`. **No content defaults:** **FooterReveal.Ruled** requires `wordmark`; `links`, `email` (+ `emailHref`), `mark`, `copyright`, and `credit` render only when passed. **FooterReveal.Brand** requires `headline`, `ctaLabel`, and `wordmark`; `socialLinks` renders only when passed. The app owns every string and address. Paste **Pattern — ruled grid footer**. **Pattern — marketing hero ruled grid** uses it under the existing hero. **FooterReveal.Brand** stays the navy field and still crops its own wordmark. See **ADR-0030**.
+
+## HeroTileStack
+
+marketing hero image fan — `tiles` (`src`, `alt`, optional resting `offsetX` / `offsetY` / `rotate` / `zIndex`). A fine pointer over the stack pushes each card left or right away from the pointer's x (closer = stronger) through `useSpring` on x and rotate. Default `strength` (`120`) is a gentle shift that stays near the stack; raise it for a wider scatter. Vertical offset comes from pointer velocity (`useVelocity`): `velocityFactor` (default `0.02`) and `maxVertical` (default `24`) set a small clamped y nudge that springs back to 0 when the pointer slows. Tiles are square, at most **400px** (`tileSize` / `--hero-tile-size`), and scale with the stack; below `md` they form a tighter pile. Scatter distances scale with the painted tile. The root clips the inline axis (`overflow-x-clip`); the row does not clip. Reduced motion: resting fan, no scatter. Coarse pointers: a tap scatters once from the tap point (same gentle horizontal push, no velocity nudge), holds, then springs back. The marketing hero pattern places **SiteNav** above the fan and sizes the hero with `min-h-[calc(100svh-var(--site-nav-height))]`, `shrink-0`, and `justify-center-safe` (`--site-nav-height` is the expanded band). When the copy is taller than that minimum, the section grows and the content starts below the nav with the section's top padding. Hero lines use `text-wrap: balance`. “Austin,” and “Texas” stay together on the default lead (non-breaking space). The sequenced hero keeps “Austin,” and “TX” together the same way (`whitespace-nowrap`). Paste **Components/HeroTileStack → Pattern — marketing hero**. **HeroIntro** is the page `h1` on **`type-display-2`** at normal weight and display-2 leading, the same size and line-height as the gallery statement. There is no display-1 We Are WhatMatters headline. The sequenced hero h1 is only “An Austin, TX studio specializing in brand and product design.” A rock **RiveHand** sits inline immediately after “TX”, inside the same nowrap phrase (`inline`, about 1.15em drawn, centered on the line, `aria-hidden`). That heading has no second sentence and no circle or pill. The default hero still passes “We're a design and product studio based in Austin, Texas.” as `lead` without a sequence. The point hand sits inline in the gallery statement after “is a first impression”, in place of the pill. `lead` is the first sentence (it wraps, including from `md`) and children always start on the next line, centered. **HeroIntro** sits on `grid-page` (same `--grid-max`, margin, gap, and column count as the guides), columns 4–9 from `lg` (`lg:col-start-4 lg:col-end-10`), full width of that page grid below `lg`. The tile fan is last in the hero. See **ADR-0032**, **ADR-0034**, **ADR-0035**.
+
+## TextSequence
+
+masked word reveal — children mix text and **`TextSequence.Shape`** (`variant` `asterisk` \| `pill` \| `diamond` \| `dots` \| `double-pill` \| `circle` \| `smiley`, `tone` `brand` \| `brand-soft` \| `accent` \| `info-muted`). Words slide up behind a mask; shapes pop (scale/rotate) halfway between neighbors. `stagger`, `delay`, `trigger` (`mount` \| `inView`), `idle` (default off: asterisk spin, pill stretch), `lines` (default on, so wrap re-splits), `emphasis` (`alternate` default \| `none`). Parent owns the type step. `className` is layout only. Shapes are inline SVG about 1.15em tall (pills about 2.2em wide) with a 14px floor, centered on the line without growing the leading. Fills are `brand`, `brand-soft`, `accent`, and `info-muted` (softer tones are two-stop token gradients). `aria-hidden`. `prefers-reduced-motion` skips the split and the idle loop; server and no-JS render that rest state. GSAP + SplitText + `useGSAP` are imported only here (ADR-0037); the rest of WMDS stays on `motion/react`. **HeroTileStack → Pattern — marketing hero text sequence** sequences the intro only. That copy is **HeroIntro** `step="display"` as the page `h1` (`type-display-2`, normal weight, display-2 leading, the same size and line-height as the gallery statement). A rock **RiveHand** sits inline immediately after “TX”. The sequenced hero heading is only that Austin sentence. **ScrollHorizontal.Intro** runs the gallery statement through it inside the real `h2` (`emphasis="none"`, `trigger="inView"`, once when that panel scrolls into view). The heading keeps the plain sentence. **FooterReveal → Pattern — marketing hero with sequenced gallery** shows the hero subtext sequence and that statement together. Copy **Components/TextSequence**.
+
+## ScrollHorizontal
+
+marketing gallery directly under the hero — `items` (`id`, `label`, optional `color`), optional `heading` (`sr-only` while the window is pinned, visible above the row when motion is reduced; omitted when `intro` is set), optional `intro` (**`ScrollHorizontal.Intro`** — **Badge** label pill (neutral, the category pill), `type-display-2` statement at normal weight through **TextSequence** (`emphasis="none"`, once when the panel scrolls into view; shapes about 1.15em: asterisk after screen, point **RiveHand** after impression, diamond after yours; plain accessible name “Every screen is a first impression and we make yours the one they remember.”), **Button** `role="secondary"` labeled Start a project (no className, no icon); first panel of the track, left edge on the page-grid content start (`--grid-margin` inside centered `--grid-max`), then translates off with the tiles; clears `--site-nav-height`; the badge names the section; reduced motion stacks it above the native row and keeps that inset), `expandLast` (default false), optional `expanded`, `className` on the root only. A `300svh` track (`shrink-0`, so a flex parent keeps that height) and a sticky `h-svh` window (one card wide, centered) translate the row from the first card centered to the last: `(items.length - 1) * (item width + gap)`, measured from the DOM. From `sm`: **400×500**, `gap-8` (32px). Below `sm`: **280×350**, `gap-4` (16px). Radius `rounded-xl` (`--radius-xl`, 12px). Each card is a solid token fill. The label is `sr-only` (the accessible name). Omitted colors cycle `--color-brand` (`#011272`), `--color-brand-soft`, `--color-primary`, `--color-info-muted`, and `--color-accent`. `prefers-reduced-motion` and `MotionConfig` `reducedMotion="always"`: no transform, height auto, not sticky, native horizontal overflow, `py-12`. SSR stays on the motion shell; the OS query is applied in `useLayoutEffect` before paint, and `motion-reduce:` covers that paint. **`expandLast`** (default false) lengthens the track to **`400svh`** (`shrink-0`) so the horizontal travel keeps the same scroll distance and one extra viewport grows the last tile. The grow is a `clip-path` inset on a full-viewport layer: the centered card expands to the `h-svh` window edge to edge and the radius reaches 0. Earlier tiles fade. The window then releases and that full-bleed tile scrolls away. **`expanded`** is an optional slot on that section (mounted for the motion layer and the reduced-motion section; one is hidden). Reduced motion keeps the native scroller and follows it with the last tile as a static `h-svh` section. Paste **Components/ScrollHorizontal → Pattern — project gallery**. The marketing hero patterns place it under the hero and pass `expandLast`. The section ends on that tile. **FooterReveal → Pattern — marketing hero** sets `!py-0` on the guide `grid-page` after the gallery so the tile meets the footer with no page-background strip. Reduced motion's static `h-svh` section meets it the same way. See **ADR-0036**.
+
+## RiveHand
+
+decorative hand on the marketing hero headline, from `public/rive/interactive-icon-set.riv` (`@rive-app/react-canvas`). `hand` `'point'` (`31_Cigarette`, cigarette removed) or `'rock'` (`29_Rock`). `size` is the box (`em` tracks the headline). `active` sets `Boolean 1`. `idle` (default true) holds that input for 1.1s, then waits a random 1–2s before the next pulse, per hand, while the tab is visible and the sized hand box is in view. `entrance` is `slide-up` (rock, clipped at the baseline), `grow` (point, 200ms later, origin at the grip), or `none`. `aria-hidden` defaults to true. `handFill` reads `--color-surface` (fallback `--color-background-surface`; white in light mode); `outline` reads `--color-brand` (`#011272` in both themes; hardcoded fallback `#011272`). `inline` places the hand in a text line. The canvas is larger than the artboard padding so the drawn hand is about 1.15em, the drawn hand is centered on the line, and a zero-height slot keeps the line box. Inside a TextSequence that slot pops on the beat halfway between the words beside it, with the same scale, rotation, and `back.out(1.8)` ease as the circle and pill. Idle starts after that pop. The sequenced hero places the rock hand inline immediately after “TX”, inside the same nowrap phrase. It pops on the beat after TX. The gallery statement places the point hand inline after “is a first impression”, in place of the pill. `entrance="none"`. `aria-hidden` stays true. Outline stays `--color-brand` (`#011272`). Reduced motion draws one static frame once the canvas box has size, then pauses. The sequence pop and idle timers stay off. The server and the hydration render both use that resting pose (no `translateY(100%)` or `scale(0)`); the entrance starts after mount only when motion is allowed. CC BY 4.0, Silvia Sguotti and Gabriele Montinaro (`public/rive/CREDITS.md`). Consumers install `@rive-app/react-canvas`, serve the file at `/rive/interactive-icon-set.riv`, serve the runtime at `/rive/rive.wasm` (`riveHandWasmSrc` — copy `node_modules/@rive-app/canvas/rive.wasm`; when it is missing the runtime falls back to its CDN build and logs a warning), and paste a `"use client"` module. Paste **Components/HeroTileStack → Pattern — marketing hero**. See **ADR-0034**.
+
+## PromptBar
+
+wide prompt pill — inline **TextArea** (`rows={1}`, one line when empty, grows through **3 lines**, then scrolls) and an **IconButton** `sm` send control (Lucide **ArrowRight**) inset with even padding. The pill owns focus; the send control does not draw a second ring. Placeholder **Ask anything…**. Enter sends; Shift+Enter inserts a newline. Send stays disabled and muted until the draft has text, then uses **`--color-brand`** (`#011272` / `bg-brand`). No new Button role. Voice and attachments are not part of this version. Copy **Components/PromptBar → Pattern — prompt bar**. The ask page is **Sites/WhatMatters/Prompt chat → Pattern — landing to chat**: a centered display headline, then a thread that keeps growing on a narrowed page grid (`--grid-max: 40rem`; the page shell is `h-[100svh]` so the thread scrolls inside that column when it is taller than the viewport, without a height-constrained parent, and reserves the composer's measured height plus the space under the pill, including while a reply is still growing, so the reply and its follow-ups finish above the composer; the trailing pill, plain reply, follow-ups, and **PromptBar** share that column and the bar stays pinned). A follow-up or another send appends the next user line in the same thread. Previous messages stay. Send uses **motion** (`motionTransitionProp`). The headline fades, and the sent line fades in where it rests. Before the reply, a collapsed sparkle row shows a live Thought-for timer (`type-supporting` and `text-muted`, not brand navy). The user can expand it while thinking to read the steps; on this pattern the whole row leaves when the reply starts (Reasoning, Search, and Coding keep the settled disclosure). The reply then streams word by word out of a blur, with one inline **TextLink**. Copy / thumbs **IconButton** actions sit under that reply and stay hidden until hover (or a touch open on that reply only), then full-width **Button** `role="outline"` `emphasis="quiet"` `align="start"` follow-up pills (the quiet `--color-border` hairline). Expanded steps show a Lucide circle spinner that becomes a check, beside a left rule. The chat keeps **SiteNav** as it exists; the brand mark returns to the landing. **Start Project** in the nav end slot opens a gated starter **Card** that replaces **PromptBar** in place (thread stays); Cancel restores the composer. `prefers-reduced-motion` skips the fade and the trace play, and shows the finished reply. **PromptBar** also mounts on the **marketing homepage**: **Components/PromptBar → Pattern — marketing composer** pins it to the bottom of the viewport on the page grid (`--grid-max: 40rem`, above the safe area, under **SiteNav**), and sending hands off to the ask page — the app routes to `/ask?q=…` and passes `q` to **AskWhatMatters** as `initialPrompt`, which opens on that first exchange instead of the landing headline. Do not hand-roll the pin, and do not restyle **SiteNav**.

package/docs/components.md

@@ -0,0 +1,61 @@
+# @thewhatmatters/wmds — component contracts
+
+Version 0.2.0. Generated from the WMDS repository's AGENTS.md (Storybook-first) by `scripts/generate-package-docs.mjs` — do not edit here.
+
+Storybook paths such as **Components/Button/Button → Pattern — …** name a story; its Show code is in `patterns/` (see `patterns/index.json`). Longer contracts for FooterReveal, HeroTileStack, TextSequence, ScrollHorizontal, RiveHand, and PromptBar are in `component-contracts.md`. ADR numbers refer to decision records in the WMDS repository.
+
+- **Theme** lives in `src/theme/` — `colors.css` (semantic roles) + `theme.css` (Tailwind `@theme` bridge). Storybook is the source of truth, not Paper.
+- **Dark mode:** `[data-theme="dark"]` on `<html>` or any ancestor — same token names, swapped values in `colors.css`.
+- **Consuming apps:** use exported components and typed props; `className` for layout only — not re-theming. Page layout utilities (`gap`, `grid`, `max-w`) are fine between components.
+- **Theme tokens:** Semantic roles in **`src/theme/colors.css`**; typography in **`src/theme/typography.css`** (`type-*` utilities, geometric scale; **display-1/2/3** are fluid via `clamp` — display-1 hits **5rem** on desktop and scales down to **2.5rem** on mobile); motion in **`src/theme/motion.css`**; page spine in **`src/theme/grid.css`** (`--grid-*`, `grid-page` / `band`, `--leading-base`). **`--spacing` stays 4px** — do not re-scale; baseline is 8px. See **ADR-0007**, **ADR-0008**, **ADR-0009**, **ADR-0010**, **DESIGN.md → Grid**. Use **`typographyClass()`** — not raw `text-sm` in document copy.
+- **Page layout:** Every Storybook **Sites** / **Guides** page and consuming product page starts on **`grid-page`**; use **`band`** + responsive column spans for content alignment. Constrain a specific experience by overriding **`--grid-max`** on that wrapper (for example, `960px`) rather than replacing the grid with an arbitrary centered container.
+- **Scroll fade:** use **`scroll-fade-y`** / **`scroll-fade-x`** on the element that owns overflow to hint at clipped list or rail content. The mask is scroll-aware, disappears when no overflow exists in supporting browsers, and follows inline direction for RTL. Keep the surface fill/border on a wrapper; customize with `--scroll-fade-size` only when the default 12% / 40px cap does not fit. Copy **Foundations → Scroll fade → Pattern — …**.
+- **Motion:** Duration tiers in **`src/theme/motion.css`** — **fast** (hover/focus), **medium** (panels/layout), **slow** (rare). Single **`--ease-standard`**. CSS via `motionTransition()`; Motion via `motionTransitionProp()`. Choreography tokens `--motion-stagger`, `--motion-beat`, `--motion-blur-reveal` through `motionStaggerSeconds()`, `motionBeatSeconds(n)`, `motionBlurReveal(reduce)`, and `readMotionDurationSeconds(tier)` — Show code never hard-codes a blur, stagger, or duration. See **ADR-0008**. Storybook wraps `<MotionConfig reducedMotion="user">`.
+- **Icons:** **[Lucide](https://lucide.dev/icons/) only** until further notice — import from **`lucide-react`** in components, stories, and examples. Peer dependency, not bundled; use `stroke-current` / `ButtonIcon` for sizing. See **Foundations → Icons**.
+- **Button:** pill by default; **`layout="row"`** for flat full-width detail/settings lines (**`width="hug"`** sizes a row to its content with a tight gap — inline disclosure triggers); **`align="start"`** left-aligns a pill label and **`emphasis="quiet"`** puts `role="outline"` on the `border-border` hairline (full-width suggestion pills — **Pattern — suggestion pills**); **`layout="nav"`** for **NavList** rows (`selected`). Six **roles** (`primary`, `secondary`, `ghost`, `destructive`, **`inverse`** — surface fill and brand text, for a brand-blue field, **`outline`** — hairline border and transparent fill). Patterns: action, **`row`**, **`nav`**, `icon`, `count`, `status` morph, **`mono`** + **`endIcon`** (accent arrow square) — mutually exclusive where documented. No slots. [Motion reference](https://motion.dev/examples/react-multi-state-badge).
+- **Avatar:** circular identity — required `name`, optional `src`, initials → **User** fallback; sizes `xsm` / `sm` / `md` (default) / `lg` / `xl` (20–128px). Optional `presence={{ tone, label, pulsing? }}` — rim dot via **Status** dot tokens (not the **Status** component). **`avatarSizeForCluster()`** for header rows; **`size="sm"`** in **Dropdown.Item** `start`. Not clickable — wrap at call site. Agents: copy **Components/Avatar → Pattern — …**; see **ADR-0017**.
+- **IconButton:** circular icon-only control. Patterns: toolbar (ghost), `fab`, `loading`, native `title`, **`inset`** (compact dismiss inside Chip), **`render={<a/>}`** (circular brand / icon links). Compose **Tooltip** for tokenized hover/focus labels and pass `title=""` to avoid duplicate native UI. **`aria-label` required** — use `Button` when text is needed.
+- **Kbd:** semantic keyboard keycap — one physical key per **Kbd**; compose multiple keycaps for shortcuts. Sizes `sm` | `md`; add `aria-label` when symbolic labels need spoken expansion. Display-only — never interactive on the keycap itself. Numbered choice rows pair trailing **Kbd** digits with **`useKbdChoiceKeys`** so `1`–`4` select the same way a click does while focus is not in a text field (see **Pattern — numbered choice keys** and the AskWhatMatters Start Project gate). Copy **Components/Kbd → Pattern — keyboard shortcut**.
+- **TextLink:** inline anchor for navigation inside prose — canonical solid underline, stronger hover decoration, and focus ring. `external` opens a new tab and appends Lucide **SquareArrowOutUpRight** with spoken context. Inherits surrounding type size; `className` is layout only. Use **Button** for actions. Copy **Components/TextLink → Pattern — inline prose link**.
+- **Tooltip:** short supplemental label — **`Tooltip.Provider`** shares hover delay; **`Tooltip.Trigger render={...}`** composes a ref/DOM-prop-forwarding control; **`Tooltip.Content`** portals with collision-aware physical or logical placement. Opens on hover/focus, closes with Escape, and does not open on touch. No essential or interactive content. Disabled native controls need the documented focusable wrapper. Copy **Components/Tooltip → Pattern — …**.
+- **Badge:** solid and **muted** semantic fills. Patterns: label, **`emphasis="muted"`**, `count`, `icon`, **`avatar`**, **`iconOnly`** — mutually exclusive where documented. **`avatar={{ src, alt }}`** renders **Avatar** at the badge size (`badgeAvatarSize`: sm → 20px, md → 24px). **`BadgeSegmentCount`** for filter/tab segment totals (Chip trailing count). No **Status** dot inside Badge. See **ADR-0033**.
+- **Chip:** filter/toggle molecule — composes **`BadgeIcon`** / **`ButtonIcon`**, **`IconButton inset`** (remove), **`BadgeSegmentCount`** (count). Patterns: **multi-select filter** (`ChipFilterGroup` + `value`), single-select group, standalone `selected`, **removable** (`onRemove`), **read-only**. Sizes `sm` | `md` | `lg`. Optional `icon`, `count` — not with `onRemove`. No slots.
+- **SegmentedControl:** connected **segmented control** — one track, Motion sliding thumb, mutually exclusive **`SegmentedControl.Item`** segments (`role="radiogroup"`). Patterns: **shape/settings toggle** (`layout="hug"`), **view switcher** (`layout="stretch"`). Sizes **`sm` | `md` | `lg`** — cluster tiers (28 / 36 / 44px), **1:1 with Chip**; pair **Button** via `buttonSizeForCluster()` and **IconButton** via `iconButtonSizeForCluster()`. Not multi-select — use **ChipFilterGroup**; not many options — use **Select**. **Badge** `sm`/`md` is inline label scale, not cluster header pairing.
+- **DisplayControls:** compact page-utility molecule — controlled grid visibility + theme mode (`auto` | `light` | `dark`); composes **Button** + **Kbd**. Global **G** toggles grid and **T** cycles theme. When paired with **GridOverlay**, set `keyboardShortcut={false}` on the overlay. `className` is placement only. Copy **Components/DisplayControls → Pattern — page display controls**.
+- **PageHeader:** horizontal page chrome — `start` | `title` | `end`; **`variant="app"`** (56px page band + hairline), **`page`** (section `h2`), **`toolbar`** (`role="toolbar"`, cluster row). Pair **SegmentedControl** / **Button** / **Avatar** at one cluster tier. Not **Card.Header**. See **ADR-0018**.
+- **FooterReveal:** marketing page root — **FooterReveal.Content** covers a sticky **FooterReveal.Footer**, which sharpens from blur as the cover scrolls away. **FooterReveal.Brand** is the navy field (`footerRevealFieldClasses`); **FooterReveal.Ruled** is the cream ruled footer (`footerRevealRuledFieldClasses`). Neither ships content defaults: pass the wordmark, headline, CTA label, links, and email. Reduced motion renders it sharp, including SSR. Paste **Components/FooterReveal → Pattern — marketing page**, **Pattern — marketing hero**, or **Pattern — ruled grid footer**. See **ADR-0030**. Full contract: **docs/component-contracts.md → FooterReveal**.
+- **HeroTileStack:** marketing hero image fan — `tiles`; a fine pointer pushes cards away from the pointer, a coarse pointer scatters once on tap, reduced motion keeps the resting fan. **HeroIntro** is the page `h1` on `type-display-2` and sits on `grid-page`. Paste **Components/HeroTileStack → Pattern — marketing hero**. See **ADR-0032**, **ADR-0034**, **ADR-0035**. Full contract: **docs/component-contracts.md → HeroTileStack**.
+- **TextSequence:** masked word reveal — children mix text and **`TextSequence.Shape`**; `trigger` (`mount` \| `inView`), `emphasis`, `idle`, `lines`, `stagger`, `delay`. Parent owns the type step; `className` is layout only. The only component that imports GSAP (**ADR-0037**) — the rest of WMDS stays on `motion/react`. Reduced motion and the server render the rest state. Copy **Components/TextSequence**. Full contract: **docs/component-contracts.md → TextSequence**.
+- **ScrollHorizontal:** marketing gallery directly under the hero — `items`, optional `heading`, `intro` (**`ScrollHorizontal.Intro`**), `expandLast`, `expanded`; `className` on the root only. A sticky window translates the row from the first card to the last; `expandLast` then grows the last tile to full bleed. Reduced motion is a native horizontal scroller. Paste **Components/ScrollHorizontal → Pattern — project gallery**. See **ADR-0036**. Full contract: **docs/component-contracts.md → ScrollHorizontal**.
+- **RiveHand:** decorative hand on the marketing headline (`@rive-app/react-canvas`) — `hand` (`point` \| `rock`), `size`, `inline`, `active`, `idle`, `entrance`; `aria-hidden` by default. Apps serve two files beside each other: `/rive/interactive-icon-set.riv` and `/rive/rive.wasm` (`riveHandWasmSrc`, copied from `node_modules/@rive-app/canvas/rive.wasm`). Reduced motion draws one static frame. Paste **Components/HeroTileStack → Pattern — marketing hero**. See **ADR-0034**. Full contract: **docs/component-contracts.md → RiveHand**.
+- **SiteNav:** marketing site header — `start` | `middle` | `end` slots; **page chrome** (`placement="fixed"`, optional `scrollContainer`) vs **specimen** (`placement="inline"`); expanded is **in flow** (scrolls away); after scroll past `collapseAt` (default **50% of scrollport**) a **narrower hug pill pins 1rem from the top** (`compactLayout="grid"` optional); mega panel stays **grid-wide** above a light dim; mega body: **SiteNav.Featured** / **ReadRow** / **MenuMedia** / **MenuLinkGrid** (paste **Pattern — mega menu**); below `md` mega sections stack; **SiteNav.Links** / **Link** / **Menu** / **MenuSection** / **MenuLink** (Base UI NavigationMenu) with Tab-style **More** overflow when the middle track is tight; `mobile` → **Sheet** `side="end"`. Compose **Button** `render={<a/>}` for anchors. Brand: circular **IconButton** via `icon` + `aria-label` (or wordmark **Button**). Not app chrome. See **ADR-0028**.
+- **NavList:** sectioned secondary nav — **`sections`** + **`activeId`** / **`onSelect`**, or **NavList.Section** + **NavList.Item**. Inset pills via **Button** `layout="nav"` + **ButtonIcon**; optional counts; **`labelAlign="brand"`** reserves a 56px first-section band. Not primary navigation. See **ADR-0019**.
+- **FloatingActionButton:** compact vertical action menu — `items` (2–4) + `onAction`; optional trigger/open icons, labels, and backdrop. Composes **IconButton** for trigger/actions; Motion `offsetPath` opens straight above the trigger; visible labels stay beside every icon. `className` is placement only. See **ADR-0024**.
+- **Tab:** responsive peer-page/view navigation — **Tab.Group** + **Tab** (`tablist` / `tab`); inactive labels are regular-weight `text-muted`, active labels are medium-weight `text-fg` with the shared Motion bottom rule, and the muted pill fill is hover-only; optional `count`. Width overflow reserves a **More** Dropdown; selecting a hidden tab promotes it into the final visible slot before More. Not **SegmentedControl** (settings choice) or **Chip** (filter). See **ADR-0022**.
+- **Stat:** at-a-glance metric tile — required `label`, `value`; optional `trend` (muted **Badge**), `start` / `end`, `loading`. **`Stat.Group`** — responsive grid (`columns` 2–4, 2-up mobile). **`size="sm"`** for insights rows; **`size="md"`** for hero KPI above charts. Inline mono trend (`chartKpiTrend*`) stays on **Chart**-paired KPIs — not **Badge**. Section heading + actions → **PageHeader** `variant="page"`.
+- **TaskRows:** expandable task rows — composes **Accordion** for disclosure; adds status (**Badge**, **Status**), **meta**, detail rails, and **TaskRows.Detail**. Patterns: **status rows**; **capsules**; **action details** (`detailsLayout="actions"` + `TaskRows.Detail variant="button"` → **Button** `size="xs"`); **tag chips** (`detailsLayout="chips"` + read-only **Chip** `size="sm"`); **detail lines** (`TaskRows.Detail` + `onPress` → **Button** `layout="row"`). Optional **Card.Body**.
+- **Accordion:** generic expand/collapse — **leading**, **label**, **trailing**, built-in chevron, `motion-collapse` panel. Variants: `list`, `capsule`, `plain`. **TaskRows** is the task-status pattern on top.
+- **Card:** `Card.Header`, `Card.Body`, `Card.Footer`. Layout cards (`padding="none"`): header/footer on the shell; **`Card.Header`** is two horizontal slots (`start` | `end`) at **16px** (`px-4`). **`end` is always trailing** (`ml-auto`) — overflow / **MoreMenu** stays on the right even when `start` is omitted. **`Card.Body` is a square composition slot** with a **2px** horizontal gutter — no inner pad, no radius, **no default fill**. The **occupant** dictates how the body region looks; use **`cardLayoutBodyOccupantInsetXClasses`** (`px-3.5` / 14px) + **`cardLayoutBodyOccupantPadYClasses`** (`py-[16px]` / literal 16px vertical) when body content should align with header/footer (2px + 14px = 16px horizontal). Shape config lives in **`src/theme/shape.css`**: shell **`--radius-card-shell: 16px`**, body occupant **`--radius-card-body: 14px`**. Radius-only media → **`cardLayoutBodyOccupantRadiusClasses`**; inset gray/chart wells → **`cardLayoutBodyOccupantWellClasses`** or **`cardLayoutBodyOccupantDotGridWellClasses`**. A headerless layout **Card.Body** densifies the shell top to 2px (`pt-[2px]`) — same density as footerless / `bodyTerminal` bottom; **`headerless`** is only an override for wrapped slot composition. A direct terminal **`Card.Body`** automatically fills stretched cards and gets the 2px bottom shell inset; **`bodyTerminal`** is only an override for wrapped slot composition. Pin a layout height on the root (`className`) with Header + Body + Footer — Header/Footer stay put; **Card.Body** scrolls (2px gutter unchanged; no new variant). See **Components/Card/Card → Pattern — pinned height**. `variant="surface"` is elevated; **`variant="outlined"`** uses **`shadow-soft-card`** with no stroke (same elevation as layout `surface`). Radius stays **`--radius-card-shell`**. Default **`shape="rounded"`**. **`shape="flush"`** only when a parent owns outer chrome. Simple cards: `padding="md"`.
+- **Input:** pill-only. Optional leading `icon`; trailing `endBadge` or status / `loading`. Hero search with inset button → **Search** molecule. See **ADR-0006**.
+- **PromptBar:** wide prompt pill — inline **TextArea** (one line when empty, grows through 3 lines, then scrolls) and an inset **IconButton** `sm` send control. Enter sends; Shift+Enter inserts a newline; send stays disabled until the draft has text. No new Button role. Copy **Components/PromptBar → Pattern — prompt bar**; the ask page is **Sites/WhatMatters/Prompt chat → Pattern — landing to chat**. On the **marketing homepage** it is pinned to the bottom of the viewport on the page grid and hands off to the ask page (`/ask?q=…` → **AskWhatMatters** `initialPrompt`): copy **Components/PromptBar → Pattern — marketing composer**; do not hand-roll the pin. Do not restyle **SiteNav**. Full contract: **docs/component-contracts.md → PromptBar**.
+- **TextArea:** element-radius multiline — same optional `label`, `description`, `status`, `message`, and `loading` as **Input**; default `resize="vertical"`. See **ADR-0006**.
+- **Field:** label/layout wrapper — `orientation="vertical" | "horizontal"`; never required. Validation stays on **Input** / **TextArea**. See **ADR-0006**.
+- **Checkbox:** boolean toggle — label row + optional `description`, `indeterminate`, `status` / `message`, and `loading`. See **ADR-0006**.
+- **Radio:** single option circle — same label row rhythm as **Checkbox**; compose in **RadioGroup**. See **ADR-0006**.
+- **RadioGroup:** mutually exclusive options — `value` / `onValueChange`, vertical or horizontal layout, group validation band.
+- **Switch:** instant on/off — pill track + sliding thumb; `layout="settings"` for label-left rows. See **ADR-0006**.
+- **CheckboxGroup:** multi-select options — `values` / `onValuesChange`, vertical or horizontal layout, group validation band.
+- **Select:** pill trigger matched to **Input** shell + floating listbox (**Dropdown.Menu** / **Dropdown.Item**). **`size="sm"`** in Card headers beside **Chip sm**. Options support **`start`** / **`end`** slots for icons and shortcuts. See **Components/Select**, **Components/Dropdown**.
+- **Dropdown:** shared menu panel (`p-0.5` inset) + three-slot rows (`start` | label | `end`) — composed by **Select**; action menus via **MoreMenu**.
+- **MoreMenu:** kebab **IconButton** + floating **Dropdown** action menu — **Card.Header** `end` (right) only; never left-align overflow. Menu right-aligns to trigger; expanded trigger retains the ghost hover surface; **`items`** + **`onAction`**. Sizes **`xs` | `sm` | `md` | `lg`** (**IconButton** scale). Not for single-select — **Select** / **SegmentedControl**.
+- **Toast:** temporary notification organism — mount one **`Toaster`** at the app root and call **`toast.add()`** / `update()` / `dismiss()`. Six `position` values (top/bottom × left/center/right), default five-item layered deck (newest interactive in front, older surfaces offset behind), semantic tones, optional action (**Button**) and dismiss (**IconButton**). Errors announce as `alert`; other tones as `status`. `duration: null` persists. Blocking decisions use **AlertDialog**. See **ADR-0025**.
+- **Confetti:** celebratory burst — mount one **`ConfettiProvider`**. After an async success, render the confirmation surface and call **`useConfettiOnMount(options?)`** there (once per mount; a ref skips StrictMode and re-renders). **`useConfetti().fire(options?)`** is the same burst when the moment is not a mount. `origin` is an element, a ref (center of the box), or a viewport `{ x, y }` point; default is the viewport center. Confirmation pages pass the top-center of the viewport and a wide `spread`. Overlapping bursts are kept. Removed `duration + 0.5s` after start. Reduced motion: `fire()` does nothing. Colors default to chart categorical 1–7 (`confettiDefaultColors`). There is no trigger component. Paste **Sites/WhatMatters/RFP submitted → Pattern — RFP submitted**. See **ADR-0031**.
+- **Dialog:** modal overlay — portal scrim, focus trap, scroll lock, **medium** enter/exit; composes **Card** shell + **IconButton** close. **`Dialog.Content`** — `title`, `description`, `footer`, `size` (`sm` | `md` | `lg`); header/footer pinned, body scrolls; **no section hairlines** — brief/direct copy + `gap-4` section rhythm. **`AlertDialog`** — blocking confirm with cancel + confirm **Button** roles; `confirmRole="destructive"` for irreversible actions; scrim dismiss off by default.
+- **IntakeModal:** full-screen Start a project shell — typographic **WM** + **WhatMatters** wordmark (no separate logo asset), **IconButton** close (Lucide **X**, name **Close**), **StepProgress** (navy segments, pill label **Step N of 4**), pinned **Back** / **Continue** footer. Focus trap, Escape, scroll lock, `aria-modal`. **SelectableCard** is the multi-select grid (2 columns mobile, 3 from `lg`) with a `toggle` slot for hugged **SegmentedControl** and a **Badge** `iconOnly` check. **PillGroup** is the wrapping radio pills; **Not sure yet** uses existing **Badge** neutral `emphasis="muted"` — no new Badge emphasis. **IntakeForm** is **Field** + **Input** / **TextArea** (optional Link URL); required fields show `status` + `message` on blur; company and link stay optional; the details counter is the field description. **CalEmbed** is the calendar frame plus **TextLink** skip; with no embed mounted it shows a visitor-facing empty state (`emptyTitle`, `emptyDescription`), never developer notes. **CalEmbed.Skip** is that same skip; in a **Card** gate put it in **Card.Footer** and pass `skip={false}` so the in-body link is omitted. **IntakeConfirmation** (`booked` | `emailed`) calls **`useConfettiOnMount`** with `intakeConfettiColors` (includes `--color-brand`); optional `bookingTime` / `videoHref` / `googleCalendarHref` / `icsHref` reuse **TextLink** and **Button**. Paste **Sites/WhatMatters/Intake → Pattern — start a project**. See **ADR-0038**.
+- **Sheet:** dismissible edge overlay — `side="bottom" | "end" | "start"` only (**no `top`** — not a product pattern); same scrim/focus/scroll lock as **Dialog**; bottom drawer or side detail rail; header/footer pinned, body scrolls; **hairline borders** on scroll regions. Mobile **16px inset on trailing edge only** (e.g. `end` → left gap for scrim; entry/top/bottom flush); tablet+ side sheets fully edge-flush. **`Sheet.Content`** — Card header rhythm, scrollable body, optional footer.
+- **Panel:** persistent edge flyover — `side="end" | "start"` only; **non-blocking visual scrim** (clicks pass through), **no scroll lock**, **no focus trap**; `aria-modal="false"`; page stays interactive. Same width tokens and hairline scroll chrome as **Sheet** side panels. Use for peek/detail rails; use **Sheet** when the canvas should block.
+- **Status:** fixed-scale indicators — **`variant="ring"`** (24px task progress: `active`, `step`) or **`variant="dot"`** (8px semantic: `tone`, `pulsing`). `besideLabel` / `label` for a11y. Not inside Badge.
+- **Skeleton:** layout placeholder blocks — Motion horizontal shimmer ([Motion skeleton shimmer](https://motion.dev/examples/react-skeleton-shimmer)); **`index`** staggers sweep. Compose to mirror resolved chrome (title, **Select**, well, footer). **`aria-busy`** on **Card** / page region; shapes **`aria-hidden`**. Not chart-mark state — swap region for **Chart.Loading** or live marks. See **Components/Skeleton**, **Components/Chart** Card pattern stories.
+- **Chart:** composes **[@visx/visx](https://airbnb.io/visx/)** primitives — peer dep, not bundled. WMDS owns shell, tooltip, legend, and **`chartTheme.ts`** token maps. Chart-type selection: **`.cursor/skills/wmds-visx-charts/lieflat-mapping.md`** (Lieflat catalog → WMDS patterns + example data; Lieflat HTML is reference-only). **`Chart.SegmentedBar`** — capacity meter; **`Chart.RankedBars`** — ordered percentage comparisons; **`Chart.UnitGrid`** — exact part-to-whole composition; **`Chart.DistributionStrip`** — one measure across peers; **`Chart.Heatmap`** — categorical row × column intensity; **`Chart.Cartesian`** + **`Chart.Cartesian.Area`** — time series with crosshair tooltip + optional **`Chart.Legend`**. Pass **`null`** (not `0`) for missing points — in-series hatch + muted **Badge** (**Pattern — Cartesian no-data gaps**, ADR-0027); default gap when every plotted series key is null. Entirely missing / all-zero series → product Card.Body empty (not a full-plot hatch). Initial mark animation is opt-in via **`animate="initial"`**. **`Chart.Loading`** — spinner + copy for in-flight fetch (**Card.Body**; header stays mounted). Loading model: **Skeleton** (initial layout) → **Chart.Loading** (fetch) → live marks with enter animation. Series colors: semantic **`chartSeriesConfigFromTone`** or categorical **`chartSeriesConfigFromKeys`** / **`chartSeriesColor(index)`** (ADR-0013). Tooltip portal: visx **`unstyled`** — styling only on **`Chart.Tooltip.Content`**. Responsive chart hosts measure the full parent width and use explicit **`minHeight`**; give adjacent plots the same value so chart areas align. See **ADR-0012**, **ADR-0014**, **ADR-0015**, **ADR-0027**.
+- **Responsive:** **Mobile-first** — unprefixed utilities = mobile; `sm:` / `md:` / `lg:` scale up. Review at Mobile (390px), Tablet (768px), Desktop (1280px). Grid columns step on that same scale (4 / 8 / 12). Atoms: min **44×44px** touch targets. No hover-only core actions. See **ADR-0003** and **Foundations → Grid**.
+- **Cluster scale:** shared heights for controls in one row (Card headers, filter rails) — **sm / md / lg** → 28 / 36 / 44px. **Chip** `sm|md|lg` pairs with **IconButton** `xs|sm|md` and compact **Button** `xs|sm|md`. See **Foundations → Cluster** and **ADR-0011**. Use `iconButtonSizeForCluster()` when composing headers.

package/docs/consumer-agents.md

@@ -0,0 +1,34 @@
+# Block for a consuming repo's AGENTS.md
+
+Paste everything between the lines into the app's `AGENTS.md` (or `CLAUDE.md`). It is short on purpose: the details live in the installed package, so they always match the version the app uses.
+
+---
+
+## UI: WhatMatters Design System (WMDS)
+
+This app's UI is built on `@thewhatmatters/wmds`. Before writing or changing UI, read the docs that ship with the installed version:
+
+- `node_modules/@thewhatmatters/wmds/docs/README.md` — where to look
+- `node_modules/@thewhatmatters/wmds/docs/exports.json` — every component, its category, and its patterns
+- `node_modules/@thewhatmatters/wmds/docs/components.md` — component and token contracts
+- `node_modules/@thewhatmatters/wmds/docs/patterns/` — Show code for every Storybook pattern
+- `node_modules/@thewhatmatters/wmds/CHANGELOG.md` — what changed, and **Consumer actions** for each upgrade
+
+Skills (installed with `npx skills add 'thewhatmatters/wmds#v<version>' -s use-wmds -s upgrade-wmds -s report-wmds-gap -a claude-code -y`):
+
+- **use-wmds** — before writing or changing UI
+- **upgrade-wmds** — when bumping `@thewhatmatters/wmds`
+- **report-wmds-gap** — when WMDS is missing something the app needs
+
+Rules:
+
+1. **Use WMDS components and their props.** Do not rebuild a button, input, card, dialog, or menu from raw elements and utilities.
+2. **`className` is for layout only** (margin, grid placement, width between components). Never re-style a WMDS component with color, type, radius, or `!important` overrides.
+3. **Tokens only.** Colors, type, spacing, radius, shadows, and motion come from WMDS tokens and helpers — no raw hex, px font sizes, or hand-written durations.
+4. **Patterns are copied verbatim.** When a pattern matches, copy `docs/patterns/<id>.tsx` whole, keeping its header line that names the pattern and version. Change content and data, not structure or styling.
+5. **Pages start on `grid-page`** and place content with `band` and column spans.
+6. **Gaps go to WMDS, not into the app.** If a component, prop, variant, or token is missing, stop and report it to the WMDS repository (**report-wmds-gap**) instead of adding a one-off in the app.
+7. **Check before you finish:** `npx wmds-check` flags raw controls, `!` overrides on WMDS components, raw color, type, and motion values, and pasted patterns that drifted from the installed version. Add it to CI.
+8. **Upgrading:** `npm install @thewhatmatters/wmds@<version>`, then do every **Consumer actions** step between the old and new version and re-copy the patterns it names (**upgrade-wmds**).
+
+---