@thewhatmatters/wmds 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,53 @@
+# Changelog
+
+Every release of `@thewhatmatters/wmds` is listed here, newest first.
+
+- **Versions follow semver.** While the major version is `0`, a minor bump (`0.3.0`) can break an app and a patch bump (`0.2.1`) does not. Apps depend on `^0.2.0`, which accepts patches only.
+- **Every release has a Consumer actions section**: the exact steps an app takes when it moves to that version. It says **None** when there are none. Agents upgrading an app read every Consumer actions section between the old and new version, oldest first.
+- **Pasted patterns:** when a release changes a **Pattern — …** story's Show code, it is named under Consumer actions so apps re-copy it.
+- **How to add an entry** (contributors): add your change to the top entry. If that version is already on npm (`npm view @thewhatmatters/wmds versions`), start a new entry above it and bump `version` in `package.json` to match. `npm run check:changelog` enforces the format.
+
+## 0.2.0
+
+First release on npm. Earlier builds were installed from git commits and all reported `0.1.0`.
+
+### Consumer actions
+
+1. **Move from the git pin to npm, under the new name.** The npm package is `@thewhatmatters/wmds`; git installs were named `@whatmatters/wmds`, and that npm scope belongs to another account. Uninstall `@whatmatters/wmds`, replace `@whatmatters/wmds` with `@thewhatmatters/wmds` in every import, CSS `@import`, and config file, then `npm install @thewhatmatters/wmds@^0.2.0`. The exact commands are in **CONSUMING.md → Install → Moving from a git pin**. Commit `package.json` and `package-lock.json` together.
+2. **Delete `scripts/copy-wmds-fonts.mjs`** and the `package.json` script that runs it (usually `postinstall`). The fonts now ship in `dist/files` and both style entries reference them.
+3. **Remove `@fontsource-variable/geist` and `@fontsource-variable/geist-mono`** from the app's dependencies, unless the app imports them for something other than WMDS.
+4. **Serve the Rive runtime from the app** (only if the app renders **RiveHand**, for example the marketing hero): copy `node_modules/@rive-app/canvas/rive.wasm` to `public/rive/rive.wasm`. Copy it again whenever `@rive-app/*` changes version. Until it is there, the runtime falls back to its CDN build and logs a warning.
+5. **Copy the Rive art from the package** (same apps): `node_modules/@thewhatmatters/wmds/public/rive/interactive-icon-set.riv` to `public/rive/interactive-icon-set.riv`. Keep the CC BY 4.0 credit from `public/rive/CREDITS.md`.
+6. **Install `lucide-react`** if the app does not already have it. It is a peer dependency because 24 shipped modules import it.
+7. **Point the app's agents at the shipped docs:** paste the block from `node_modules/@thewhatmatters/wmds/docs/consumer-agents.md` into the app's `AGENTS.md` (or `CLAUDE.md`).
+8. **Install the agent skills** (optional, recommended): `npx skills add 'thewhatmatters/wmds#v0.2.0' -s use-wmds -s upgrade-wmds -s report-wmds-gap -a claude-code -y`, then commit `.claude/skills/` and `skills-lock.json`.
+9. **Re-copy pasted patterns.** Every Pattern's Show code now compiles in a strict Next 16 app: it exports its component, takes app data and callbacks as typed props, has no placeholders or unused code, and imports only real exports. Replace each pasted copy with `node_modules/@thewhatmatters/wmds/docs/patterns/<id>.tsx` and re-apply only content, data, and handlers. Most affected:
+   - **Sites/WhatMatters/Prompt chat → Pattern — landing to chat** (the site's `components/ask-what-matters.tsx`): typed throughout, dead constants removed, step 3 validates with `isIntakeAboutValid`.
+   - **Sites/WhatMatters/Intake → Pattern — start a project**: apostrophes escaped in JSX text.
+   - **Sites/PitchKit/** — all 15 patterns: exported data types (`PitchKitCreatorIdentity`, `PitchKitPastBrand`, `PitchKitPost`, `PitchKitPageData`, …) and typed props.
+   - **Guides/Overlay flows → Pattern — notification preferences**, **Components/Panel → Pattern — end detail rail**, **Components/NavList → Pattern — side nav (settings)**, **Components/SiteNav → Pattern — compact (scrolled)**, **Components/PageHeader → Pattern — toolbar header**: were outlines with placeholders; now full mirrors of the canvas.
+10. **FooterReveal: pass the footer content.** **FooterReveal.Ruled** and **FooterReveal.Brand** no longer ship content defaults (the ruled footer defaulted to a real email address). `FooterReveal.Ruled` now requires `wordmark` and renders `links`, `email`, `mark`, `copyright`, and `credit` only when passed; `FooterReveal.Brand` requires `headline`, `ctaLabel`, and `wordmark`, and renders `socialLinks` only when passed. TypeScript flags any call that relied on the defaults; pass the values the footer showed before. `footerRevealRuledDefaultCopy`, `footerRevealRuledDefaultLinks`, and `footerRevealDefaultSocialLinks` are removed. Re-copy **Components/FooterReveal → Pattern — ruled grid footer** and **Pattern — marketing hero ruled grid**.
+11. **Drop Button `!` overrides.** Replace `className="!w-auto !gap-1.5"` on a `layout="row"` Button with `width="hug"`, and `className="… !justify-start !border-border"` on an outline Button with `emphasis="quiet" align="start"` (keep `w-full` as layout). Re-copy **Sites/WhatMatters/Prompt chat → Pattern — landing to chat**.
+12. **Marketing homepage composer.** Replace the hand-rolled pinned prompt with **Components/PromptBar → Pattern — marketing composer**, and pass the ask page's `q` search param to **AskWhatMatters** as `initialPrompt` (re-copy **Pattern — landing to chat**).
+13. **RFP submitted:** the pattern's `RfpSubmitted` now takes `onSubmit(draft): Promise<void>` instead of a simulated delay. Re-copy **Sites/WhatMatters/RFP submitted → Pattern — RFP submitted** and pass your request.
+14. **Add `npx wmds-check` to CI** (optional, recommended). Start with errors only; add `--max-warnings 0` once the warnings are cleared.
+15. **Update Storybook links** in app docs and code comments. Paths changed: **Examples/…** and **Patterns/…** are now **Sites/WhatMatters/…**, **Sites/PitchKit/…**, or **Guides/…**, and components moved from `Components/{Category}/{Name}` to `Components/{Name}` (families: `Components/Button/…`, `Components/Card/…`, `Components/Checkbox/…`, `Components/Radio/…`). Pattern names and their Show code did not change.
+
+### Changed
+
+- **One module per source file.** An app that imports only `Button` bundles 148 KB minified (48 KB gzip), down from 806 KB. GSAP loads only with **TextSequence**, Rive only with **RiveHand**.
+- **Fonts ship in the package** (`dist/files`), and `./theme.css` is self-contained: every partial it imports is in `dist`.
+- **RiveHand** loads the Rive runtime from `/rive/rive.wasm` (`riveHandWasmSrc`) instead of a public CDN.
+- **`lucide-react`** is a peer dependency.
+- **Storybook** is organized as Getting started → Guides → Foundations → Components → Sites (ADR-0026, amended). Components are A–Z with a categorized **Components → Overview**.
+- **Agent docs ship in the package** under `docs/`: `exports.json` (every export with category, summary, Storybook page, and patterns), `components.md` (component and token contracts), `component-contracts.md`, and `patterns/<id>.tsx` — every Pattern's Show code with a header naming the pattern and version.
+- **Newly exported:** `ButtonIcon`, `BadgeIcon`, `buttonSizeForCluster`, `iconButtonSizeForCluster`, `clusterComponentSizeMap`, `clusterTiers`, and `ClusterTier`. Show code and the docs already told apps to use them.
+- **Show code is checked in a consumer app.** CI pastes every pattern into `fixtures/next-consumer` (Next 16, React 19, strict TypeScript, `eslint-config-next`) and requires zero `tsc` errors and zero eslint warnings.
+- **CalEmbed** shows a visitor-facing empty state (`emptyTitle`, `emptyDescription`) when no calendar is mounted, instead of developer theming notes.
+- **Button** gains `width` (`fill` | `hug`, row layout), `align` (`center` | `start`, pills), and `emphasis` (`strong` | `quiet`, outline role). New patterns: **Pattern — row (hug)**, **Pattern — suggestion pills**.
+- **PromptBar** mounts on the marketing homepage: **Pattern — marketing composer** pins it to the bottom of the viewport and hands off to the ask page.
+- **Motion choreography tokens** `--motion-stagger`, `--motion-beat`, `--motion-blur-reveal`, with `motionStaggerSeconds()`, `motionBeatSeconds()`, `motionBlurReveal()`, and the newly exported `readMotionDurationSeconds()`. Show code no longer hard-codes blur or timing values.
+- **RiveHand** passes `stateMachine` (not the deprecated `stateMachines`) and silences only Rive's `state-machine-inputs` deprecation until the art exposes a view-model boolean.
+- **`wmds-check`** consumer audit (`npx wmds-check`): raw controls, `!` overrides on WMDS components, raw color / type / motion values, and pasted patterns that drift from the installed version. See **CONSUMING.md → Consumer check**.
+- **Agent skills** in `skills/`: `use-wmds`, `upgrade-wmds`, `report-wmds-gap`, installable with the `skills` CLI. The package exports `./docs/*` and `./CHANGELOG.md` so scripts can `require("@thewhatmatters/wmds/docs/exports.json")`.
+- The package is published to npm under the MIT license. `public/rive/interactive-icon-set.riv` and its credits ship in the package.

package/CONSUMING.md

@@ -0,0 +1,352 @@
+# Using WMDS in other apps
+
+## Philosophy — pattern-first
+
+WMDS is **not** utility-class-first. You do **not** build product UI by composing `bg-primary`, `text-sm`, and ad-hoc borders across the app.
+
+**Do this:**
+
+```tsx
+import { Button, Badge, Chip, ChipFilterGroup, IconButton, Input, Status } from "@thewhatmatters/wmds";
+import "@thewhatmatters/wmds/styles.css";
+
+<Button status={status}>Submit</Button>
+<Button role="secondary" count={3}>Inbox</Button>
+<Button role="primary" icon={<Plus strokeWidth={2} />}>New item</Button>
+<Button role="ghost" layout="row" type="button" onClick={…}>
+  <span>Due date</span>
+  <span>Sep 12</span>
+</Button>
+<IconButton icon={<Settings strokeWidth={2} />} aria-label="Open settings" title="Settings" />
+<Badge variant="success">Online</Badge>
+<span className="inline-flex items-center gap-1.5">
+  <Status variant="dot" tone="success" besideLabel />
+  Online
+</span>
+```
+
+Find a component A–Z under **Components/** (or by category on **Components → Overview**), read **Guides/** for cross-component choices, and use **Sites/** for approved pages and flows (**Sites/WhatMatters/…**, **Sites/PitchKit/…**) — copy the named **Pattern** story JSX and state wiring; do not re-style with utilities. Sites and Guides pages are not exported from the package.
+
+**Show code is the product contract.** Pattern story **Show code** (`storyCopySource`) is the drop-in implementation for consuming apps. It must stay a literal mirror of the live canvas — same layout, chrome, spacing, and typography. Copy Show code; do not choose between the Storybook iframe and an older freeze, and do not reconstruct the page from Storybook-only example modules (`*Example.tsx`, `*Styles.ts`). When the canvas changes, Show code is updated to match; apps re-copy the new freeze.
+
+Page-level Example canvases include a Storybook-only grid inspector while designs are being tuned. Show code freezes the approved `--grid-max` / `--grid-column-gap` values and omits **ExampleGridControls** and other development chrome, so the copied result contains only `@thewhatmatters/wmds` exports and product layout.
+
+**Not this:**
+
+```tsx
+// Avoid — re-inventing WMDS patterns
+<button className="rounded-full bg-primary px-5 …">Submit</button>
+<Button startSlot={<img … />} badge="New" variant="success" />
+```
+
+Use Tailwind in your app for **page layout** and spacing **between** WMDS components. For a consistent page spine, copy **`grid-page` + `band`** (below) — do not invent a Pitchkit layout atom. Use **`className` on a component** for layout tweaks (width, margin) — not for new variants or colors.
+
+New visuals require a WMDS component or Example pattern — see **`docs/adr/0004-pattern-first-not-utility-first.md`**.
+
+For a list or rail that overflows its parent, apply **`scroll-fade-y`** or **`scroll-fade-x`** to the scrolling element. Keep the parent surface and border on a wrapper so the mask only dissolves content:
+
+```tsx
+<div className="overflow-hidden rounded-lg border border-border bg-card">
+  <ul className="scroll-fade-y max-h-64 overflow-y-auto">…</ul>
+</div>
+```
+
+The fade tracks the scroll boundary without JavaScript. See **Foundations → Scroll fade** for one-edge, RTL, and size controls.
+
+## Requirements
+
+- **React** 18 or 19
+- **Tailwind v4** recommended — import WMDS styles or theme
+- **Motion** — `npm install motion` when using animated components
+- **Lucide** — `npm install lucide-react`. Peer dependency: components import their own icons, and apps pass icons into component props
+- **visx** — `npm install @visx/visx` when using **Chart** (peer dep; WMDS composes `@visx/*` primitives — see **ADR-0012**)
+- **Rive** — `npm install @rive-app/react-canvas` when using **RiveHand** or **Pattern — marketing hero**. WMDS lists it as a dependency and does not bundle the runtime. Copy `public/rive/interactive-icon-set.riv` into the app at `public/rive/interactive-icon-set.riv` so it is served at `/rive/interactive-icon-set.riv`. Copy `node_modules/@rive-app/canvas/rive.wasm` to `public/rive/rive.wasm` so the runtime loads from the app at `/rive/rive.wasm` (`riveHandWasmSrc`). Copy it again when the Rive package version changes. When the file is missing the runtime falls back to its CDN build and logs a warning. Paste the pattern into a Next.js App Router file that starts with `"use client"`. The Show code already includes that directive. Hand art is CC BY 4.0, Silvia Sguotti and Gabriele Montinaro. See **ADR-0034**.
+- **GSAP** — `npm install gsap @gsap/react` when using **TextSequence**. WMDS lists both as dependencies and does not bundle the runtime. Only **TextSequence** imports them. Every other component stays on `motion`. See **ADR-0037**.
+
+## Install
+
+### From npm (default)
+
+```bash
+npm install @thewhatmatters/wmds@^0.2.0
+```
+
+Install the peers the components you use need (see **Requirements**): `react`, `react-dom`, `motion`, `lucide-react`, and `@visx/visx` for **Chart**.
+
+**Upgrade** with one command, then read **`CHANGELOG.md` → Consumer actions** for every version you crossed:
+
+```bash
+npm install @thewhatmatters/wmds@latest
+```
+
+Versions follow semver. While the major version is `0`, a minor bump (`0.3.0`) can break the app, so `^0.2.0` accepts patches only and a minor upgrade is always a deliberate `npm install @thewhatmatters/wmds@^0.3.0`. The changelog ships in the package: `node_modules/@thewhatmatters/wmds/CHANGELOG.md`.
+
+### Moving from a git pin
+
+The npm package is **`@thewhatmatters/wmds`**. Git installs were named `@whatmatters/wmds`; that npm scope belongs to another account. Apps that pinned a commit (`"@whatmatters/wmds": "github:thewhatmatters/wmds#<sha>"`) switch with:
+
+```bash
+npm uninstall @whatmatters/wmds
+git grep -l '@whatmatters/wmds' | xargs perl -pi -e 's#\@whatmatters/wmds#\@thewhatmatters/wmds#g'
+npm install @thewhatmatters/wmds@^0.2.0
+```
+
+The second line renames every import, CSS `@import`, and config reference in tracked files.
+
+Then follow **0.2.0 → Consumer actions** in `CHANGELOG.md` and commit `package.json` and `package-lock.json` together.
+
+Git installs keep working while apps move — the `prepare` script builds `dist` on install. To change a git pin, run `npm install github:thewhatmatters/wmds#<sha>`. Do not edit the hash in `package.json` by hand: the lockfile keeps the old commit's integrity and `npm install` skips the update.
+
+### Local checkout (same-day iteration)
+
+To try an unreleased WMDS change in an app before it is published, install a tarball built from the checkout. It is exactly what npm would publish, and the app keeps its own single copy of React:
+
+```bash
+# in the WMDS checkout, after each change
+npm install            # first time only
+npm pack               # builds dist, writes thewhatmatters-wmds-<version>.tgz
+
+# in the app
+npm install ../wmds/thewhatmatters-wmds-0.2.0.tgz
+```
+
+Repeat both steps after each WMDS change. When done, return to the published version so the `file:` entry is not committed:
+
+```bash
+npm install @thewhatmatters/wmds@^0.2.0
+```
+
+**Faster loop (symlink).** `npm install ../wmds` links the checkout instead, and the app sees each `npm run build` without reinstalling. The linked package resolves `react` from the checkout's own `node_modules`, which gives the app two copies of React (invalid hook call). Only use it when the bundler dedupes React — Vite: `resolve: { dedupe: ["react", "react-dom"] }`. In Next.js prefer the tarball; if you do link, the checkout must sit inside `turbopack.root`.
+
+## Agent skills and docs
+
+The package ships docs for coding agents in `node_modules/@thewhatmatters/wmds/docs/` (start at `docs/README.md`). Paste the block from `docs/consumer-agents.md` into the app's `AGENTS.md` or `CLAUDE.md`.
+
+Three agent skills live in this repository under `skills/`. Install them with the [`skills` CLI](https://github.com/vercel-labs/skills), pinned to the release tag that matches the installed package:
+
+```bash
+npx skills add 'thewhatmatters/wmds#v0.2.0' -s use-wmds -s upgrade-wmds -s report-wmds-gap -a claude-code -y
+```
+
+| Skill | When the agent uses it |
+|-------|------------------------|
+| `use-wmds` | Before writing or changing UI: find the component or pattern, props not utilities, `className` for layout only, tokens only, copy Show code verbatim with its version header |
+| `upgrade-wmds` | When bumping `@thewhatmatters/wmds`: install, apply every Consumer actions step, re-sync pasted patterns, refresh the skills, run checks |
+| `report-wmds-gap` | When WMDS is missing something: what to file, where, and how to open a WMDS pull request that follows `AGENTS.md` |
+
+The command copies the skills into `.claude/skills/` and records them in `skills-lock.json`; commit both. Add more `-a` agents (for example `-a codex`) to install for them too. The **upgrade-wmds** skill re-runs the command with the new tag.
+
+## Consumer check
+
+The package ships `wmds-check`, an audit to run in the app's CI:
+
+```bash
+npx wmds-check                     # scans src, app, components, pages
+npx wmds-check app components --max-warnings 0
+```
+
+| Rule | Level | Flags |
+|------|-------|-------|
+| `raw-control` | error | `<button>`, `<input>`, `<select>`, `<textarea>` where a WMDS component exists |
+| `important-override` | error | `!` utilities in `className` on a component imported from `@thewhatmatters/wmds` |
+| `raw-color` | error | hex, `rgb()`, `hsl()`, `oklch()` values in `className` or `style` |
+| `raw-type` | warning | `text-sm`-style sizes or `text-[…]` — use `type-*` utilities |
+| `raw-motion` | warning | `duration-[…]`, `ease-[…]`, `delay-[…]`, numeric Motion durations |
+| `pattern-drift` | warning | a pasted pattern differs from `docs/patterns/<id>.tsx` in the installed version |
+| `pattern-stale` | warning | a pasted pattern's header names an older version |
+| `pattern-removed` | error | a pasted pattern's id no longer ships |
+
+It is a line-based heuristic, not a parser. Silence a deliberate exception on the line or the line above with `// wmds-check-ignore <rule> <reason>`, and report the gap to WMDS. `--json` prints machine-readable output.
+
+## Wire up styles
+
+```tsx
+import "@thewhatmatters/wmds/styles.css";
+```
+
+Or theme only (if you configure Tailwind yourself):
+
+```css
+@import "@thewhatmatters/wmds/theme.css";
+```
+
+That entry brings the tokens, the fonts, the collapse utilities, and an `@source` for the package's built modules, so the app's Tailwind generates the utilities the components use.
+
+**Fonts ship in the package.** Geist Sans and Geist Mono are in `dist/files`, and both style entries reference them. Do not install `@fontsource-variable/*` or copy font files into `node_modules`.
+
+**Imports are per module.** The package builds one module per source file, so an app loads GSAP only when it imports **TextSequence** and Rive only when it imports **RiveHand**.
+
+## Dark mode
+
+```tsx
+<html data-theme={dark ? "dark" : undefined}>
+```
+
+Toggle on any ancestor — same token names, values from `colors.css`.
+
+## Grid spine (page layout)
+
+WMDS ships a Müller-Brockmann **app** grid (`--profile=app`): column-line + 8px baseline, relaxed rows. Tokens live in **`src/theme/grid.css`** and are included in `@thewhatmatters/wmds/styles.css` (and `theme.css` → `grid.css`).
+
+**`--spacing` stays 4px.** Even multiples = 8px baseline. Do not re-scale spacing in the app.
+
+### Tokens (already on `:root` after the style import)
+
+| Token | Meaning |
+|-------|---------|
+| `--grid-cols` | 4 / 8 (`md`) / 12 (`lg`) |
+| `--grid-gutter` / `--grid-margin` | 16px mobile, 24px from `md` |
+| `--grid-column-gap` | Uniform inter-column gap override; defaults to `--grid-gutter` |
+| `--grid-baseline` | 8px (`calc(var(--spacing) * 2)`) |
+| `--leading-base` | 24px — also `leading-base` |
+| `--grid-max` | 80rem |
+
+Override on a wrap if a screen needs a different max width (`style={{ "--grid-max": "100%" }}`) or column gap (`style={{ "--grid-column-gap": "16px" }}`). Responsive Tailwind arbitrary properties are also valid page layout: `[--grid-column-gap:12px] md:[--grid-column-gap:20px]`. Do not fork a second `--grid-*` set in Pitchkit.
+
+### Band classes
+
+```tsx
+import { GridOverlay } from "@thewhatmatters/wmds";
+
+<div className="grid-page">
+  <GridOverlay />
+  <div className="band">
+    <section className="col-span-full lg:col-span-6">…</section>
+    <aside className="col-span-full lg:col-span-6">…</aside>
+  </div>
+</div>
+```
+
+- **`grid-page`** — wrap + column tracks. Mount **GridOverlay** as a child of this box so it inherits that page's `--grid-max`, margin, and gutter. Column guides and margin lines then cover the rest of the document, including sections that sit before the page, on those same tracks. An empty page (no bands, only the overlay) still paints those guides over the hero. Baseline stays in the page box. No extra class on the preceding section.
+- **`band`** — subgrid of those tracks (`@supports` fallback repeats `--grid-cols`).
+- Place by **column line** (`col-span-*` / `col-start-*`). This is layout, not a new atom.
+
+CSS-only (no React overlay): add `class="grid-on"` on `<html>` and an empty `<div class="grid-guides"><div class="grid-guides-cols"></div><div class="grid-guides-baseline"></div>…</div>` inside `grid-page`. That paints inside the page box. Prefer `GridOverlay` when React is present — it is what spreads the column guides over preceding sections.
+
+### Overlay (`g`)
+
+`GridOverlay` composes the **`tailwindcss-react-grid-overlay` contract** (press **g**, React, columns) but stays a child of `grid-page` so the tracks cannot drift from that page. A viewport-sized overlay ignores `--grid-max` and is the misaligned one. WMDS does not depend on the npm package.
+
+- Press **g** (ignored in inputs). Optional `visible` / `visibleByDefault` / `onVisibleChange`.
+- Mount in Storybook and local demos. Do **not** lock Pitchkit chrome to the overlay.
+- Storybook: **Foundations → Grid**.
+
+Pattern-first: apps **copy this wrap** from WMDS. No Pitchkit `Grid` / `Page` molecule.
+
+## Components
+
+Import from the package — configure via **props**, not utility strings:
+
+```tsx
+import {
+  Button,
+  IconButton,
+  Badge,
+  Card,
+  Chip,
+  ChipFilterGroup,
+  Input,
+  Search,
+  Status,
+  Accordion,
+  TaskRows,
+  buttonRoles,
+  getNextButtonStatus,
+  type ButtonRole,
+  type ButtonStatus,
+} from "@thewhatmatters/wmds";
+```
+
+| Component | Key props | Storybook |
+|-----------|-----------|-----------|
+| `Button` | `role` (`primary` \| `secondary` \| `ghost` \| `destructive` \| `inverse` \| `outline`), `layout` (`pill` \| `row` \| `nav`), `size`, `status`, `icon`, `endIcon`, `mono`, `count` | Components/Button/Button — copy a **Pattern** story (`row` for flat detail lines; **Pattern — secondary action** for the gallery intro — `role="secondary"`, label Start a project, no className) |
+| `IconButton` | `icon`, `aria-label`, `role`, `size`, `fab`, `loading`, `title` | Components/Button/IconButton — copy a **Pattern** story |
+| `Chip` | `size`, `value`, `selected`, `onRemove`, `icon`, `count`, `readOnly` | Components/Chip — use `ChipFilterGroup` for multi-select filters |
+| `Input` | `label`, `description`, `status`, `message`, `loading`, `endBadge`, `icon`, `size` | Components/Input — pill shell; Required via `endBadge={<Badge>…</Badge>}` |
+| `Search` | `size`, `placeholder`, `onSubmit` | Components/Search — inline input + button row |
+| `PromptBar` | `value`, `onValueChange`, `onSend`, `placeholder` (default Ask anything…) | Components/PromptBar — **Pattern — prompt bar**. Wide pill, inline field (one line empty, up to 3 lines, then scroll), inset **IconButton** send. Muted until there is text, then `--color-brand` (`#011272`). Enter sends. Page pattern: **Sites/WhatMatters/Prompt chat → Pattern — landing to chat** (motion into a thread that keeps growing on a narrowed page grid, `--grid-max: 40rem`: the page shell is `h-[100svh]` and the thread scrolls inside that column when it is taller than the viewport, 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, follow-ups and **PromptBar** share that column and the bar stays pinned; a follow-up appends in the same thread; a collapsed Thought-for timer (expandable while thinking) as a fleeting supporting muted status that leaves when the reply starts, then a word stream with one **TextLink** and hover-revealed **IconButton** actions; chat reuses **SiteNav**; the brand mark returns home). Voice and attachments are not part of this version. |
+| `Card` | `variant`, `shape`, `padding` | Components/Card/Card — `Card.Header` (`start` | `end`), **`Card.Body` slot** (no default fill), `Card.Footer` |
+| `Accordion` | `variant`, `Accordion.Item` `leading` / `label` / `trailing` / `open` | Components/Accordion — FAQ, settings sections |
+| `TaskRows` | `variant`, `status`, `meta`, `detailsLayout`, `TaskRows.Detail` | Components/TaskRows — **Pattern — status rows**, **capsules**, **action details** (`Detail variant="button"`), **tag chips** (`Chip readOnly size="sm"`), detail lines (`Detail` + `onPress` → `Button layout="row"`) |
+| `Badge` | `variant`, `size`, `emphasis`, `count`, `icon`, `avatar`, `iconOnly` | Components/Badge — copy a **Pattern** story. `avatar={{ src, alt }}` is a leading round **Avatar** sized to the badge (`badgeAvatarSize`: sm → 20px, md → 24px) and is mutually exclusive with `icon`. Pass `alt=""` when the label already speaks the word. |
+| `Status` | `variant`, `tone`, `label`, `besideLabel`, `pulsing`, `active`, `step` | Components/Status — `variant="ring"` or `variant="dot"` |
+| `FooterReveal` | `FooterReveal.Content`, `FooterReveal.Footer`, `FooterReveal.Brand` (`headline`, `ctaLabel`, `onCtaClick`, optional `ctaHref`, `wordmark`, `socialLinks`), `footerRevealFieldClasses` | Components/FooterReveal — **Pattern — marketing page** and **Pattern — marketing hero**. Cover sits on the page background; the brand field sticks underneath and sharpens from 12px of blur. Field is `bg-brand` / `text-on-brand` (`#011272`). The wordmark is `--color-brand-soft`, spans the footer width, and is cropped at the bottom edge. CTA is **Button** `role="inverse"` `type="button"` (`onCtaClick` opens the project modal). Pass `ctaHref` only to render a link. Reduced motion stays sharp, including the server render (the SSR snapshot is sharp, so a Next page does not hydrate a leftover blur). The root does not clip, so **GridOverlay** guides still cover the hero. The marketing hero's guide `grid-page` uses `!py-0` so the expanded gallery tile meets the footer with no page-background strip. |
+| `HeroIntro` | `lead`, `children`, `step` (`large` default \| `display`), `className` (layout only) | Components/HeroIntro — **Pattern — two-line intro**. Also composed by **Components/HeroTileStack → Pattern — marketing hero**. `lead` is the first sentence. Children always start on the next line. Both steps are `type-display-2` at normal weight (`!font-normal`) and `text-balance`, the same font-size as **ScrollHorizontal.Intro**. Keep “Austin, Texas” together with a non-breaking space. `lead` wraps, including from `md`. `large` (default) is columns 4–9 from `lg`. `display` is full width of the page grid — **Pattern — marketing hero text sequence** and **FooterReveal → Pattern — marketing hero with sequenced gallery**. The shell is `grid-page` with the page block pad removed. Do not insert a line break in the copy. |
+| `TextSequence` | `children`, `stagger`, `delay`, `trigger` (`mount` \| `inView`), `idle` (default off), `lines` (default on), `emphasis` (`alternate` \| `none`), `TextSequence.Shape` `variant` + `tone` (`brand` \| `brand-soft` \| `accent` \| `info-muted`), `className` (layout only) | Components/TextSequence — **Default**, **Shapes**, **Reduced motion**. **HeroTileStack → Pattern — marketing hero text sequence** sequences the intro only. **ScrollHorizontal.Intro** runs the gallery statement through **TextSequence** inside the `h2` (`emphasis="none"`, `trigger="inView"`). **FooterReveal → Pattern — marketing hero with sequenced gallery** shows both. Words slide up behind a mask; shapes pop between neighbors. Marks are about 1.15em tall (pills about 2.2em wide) with a 14px floor, centered on the line so the leading does not jump. Softer tones use a two-stop gradient between those tokens. `idle` spins asterisks and stretches pills. `prefers-reduced-motion` stays at rest (same as the server render). Shapes are `aria-hidden`. The plain sentence is the accessible name once split. Parent owns the type step. `npm install gsap @gsap/react`. See **ADR-0037**. |
+| `HeroTileStack` | `tiles`, `tileSize`, `strength`, `velocityFactor`, `maxVertical`, `spring` | Components/HeroTileStack — **Pattern — marketing hero**. Square tiles, `--hero-tile-size`, max `tileSize` (400px), tighter pile below `md`. Scatter distances scale with the painted tile. Place **SiteNav** above the hero; the hero section is `min-h-[calc(100svh-var(--site-nav-height))]`, `shrink-0`, and `justify-center-safe`. It centers when the copy fits. When the copy is taller, the section grows and the content starts below the nav with the section's top padding. **HeroIntro** is the `h1` (`lead` + children) on centered `type-display-2` at normal weight and display-2 leading, the same size and line-height as the gallery statement. The first sentence wraps, including from `md`; the rest always starts on the next line. The sequenced hero h1 is only “An Austin, TX studio specializing in brand and product design.” (“Austin,” and “TX” stay together). A rock **RiveHand** sits `inline` immediately after “TX”, inside that nowrap phrase (drawn hand about 1.15em, centered, `aria-hidden`). That heading has no second sentence and no circle or pill. The gallery statement places the point hand after “is a first impression”. It 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`, 6 of 12 columns, centered), full width of that page grid below `lg`. The tile fan is the last element. Pointer over the fan springs tiles left and right away from it; a quick move adds a small vertical nudge that settles when the pointer slows; leave springs them back. Default `strength` (`120`) stays near the stack — raise it for a wider scatter. `velocityFactor` (`0.02`) and `maxVertical` (`24`) tune that nudge. Reduced motion stays on the resting fan. Coarse pointers get one gentle tap scatter, then a spring back. |
+| `ScrollHorizontal` | `items` (`id`, `label`, optional `color`), `heading` (`sr-only` while pinned, visible when motion is reduced; omitted when `intro` is set), `intro` (`ScrollHorizontal.Intro`: `eyebrow`, `statement`, optional `action` — `{ label, onClick }` for a modal button or `{ label, href }` for Button `render={<a href />}`), `expandLast` (default false), `expanded`, `className` (layout only, root) | Components/ScrollHorizontal — **Pattern — project gallery**. Also under the hero in **HeroTileStack** and **FooterReveal** **Pattern — marketing hero** (`expandLast`). Each card is a solid token-color placeholder; `label` is the accessible name (`sr-only`). `heading` names the section and stays `sr-only` on the pinned window. `intro` (**Pattern — gallery intro**, and the marketing-hero-with-gallery-intro stories) is the first panel: **Badge** label pill (neutral, the category pill), `type-display-2` statement through **TextSequence** (normal weight, once when the panel scrolls into view), **Button** `role="secondary"` labeled Start a project (no className, no icon). Pass `action={{ label: "Start a project", onClick }}` to open the project modal, or `href` when the action navigates. **FooterReveal → Pattern — marketing hero ruled grid** is the full page: sequenced hero, this intro, `expandLast`, and **FooterReveal.Ruled**. The statement is “Every screen is a first impression and we make yours the one they remember.” with an asterisk after screen, a point **RiveHand** after impression, and a diamond after yours. The eyebrow names the section. The `h2` keeps the plain sentence. At rest the panel's left edge is the page-grid content start; scroll carries it off with the tiles. Tiles follow to the right. Reduced motion stacks the intro above the row. `expandLast` still parks the last card on center before the grow. `300svh` track (`shrink-0` so a flex parent keeps that height), sticky `h-svh` window, translate from the first card centered to the last. `expandLast` uses a `400svh` track: same horizontal distance, then the last tile grows (`clip-path`) to fill the window edge to edge with radius 0 and scrolls away. `expanded` is the slot on that tile. 400×500 / `gap-8` from `sm`; 280×350 / `gap-4` below `sm`; `rounded-xl`. Reduced motion is a native horizontal scroller (`py-12`), including `MotionConfig` `reducedMotion="always"`; with `expandLast` the last tile follows as a static `h-svh` section. The section ends on that tile. **FooterReveal → Pattern — marketing hero** sets `!py-0` on the guide `grid-page` so the tile meets the footer with no page-background strip. |
+| `RiveHand` | `hand` (`point` \| `rock`), `size`, `active`, `idle` (default true), `entrance` (`slide-up` \| `grow` \| `none`, default `none`), `className`, `aria-hidden` | Components/HeroTileStack — **Pattern — marketing hero**. `point` is artboard `31_Cigarette` (cigarette removed). `rock` is `29_Rock`. `handFill` is `--color-surface` (fallback `--color-background-surface`; white in light mode). `outline` is `--color-brand` (`#011272` in both themes; hardcoded fallback `#011272`). `inline` sizes the canvas past the artboard padding so the drawn hand is about 1.15em, the drawn hand is centered on the line, and the line box does not grow. Inside a TextSequence the 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 immediately after “TX”, inside the same nowrap phrase. The gallery statement places the point hand after “is a first impression”. `entrance="none"`. `idle` holds `Boolean 1` 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. Reduced motion draws one static frame once that box has size, then pauses. The sequence pop and idle timers stay off. SSR and hydration render that resting pose; the entrance starts after mount only when motion is allowed. `npm install @rive-app/react-canvas`. Serve `public/rive/interactive-icon-set.riv` at `/rive/interactive-icon-set.riv` and `rive.wasm` at `/rive/rive.wasm`. The pattern file starts with `"use client"`. CC BY 4.0, Silvia Sguotti and Gabriele Montinaro. |
+| `ConfettiProvider` | `useConfettiOnMount()`, `useConfetti().fire()`, `origin`, `confettiDefaultColors` | Components/Confetti — playground. **Sites/WhatMatters/RFP submitted → Pattern — RFP submitted**. Fire on the confirmation surface after the async action resolves, not on the submit click. `fire()` does nothing under reduced motion. |
+
+Copy flow patterns from **Sites/** in Storybook when they ship. See **`src/package.manifest.ts`** for the export contract.
+
+### Cluster scale in detail rails
+
+Inside expanded **TaskRows** (and other dense rows), use the **sm / xs** cluster tier so controls sit below row titles — not beside them at default sizes:
+
+| Detail content | Compose |
+|----------------|---------|
+| External app / map actions | `TaskRows.Detail variant="button"` → **Button** `size="xs"` |
+| Tags / attributes | `Chip readOnly size="sm"` in `detailsLayout="chips"` |
+| Label / meta line with tap action | `TaskRows.Detail` + `onPress` → **Button** `layout="row"` `role="ghost"` |
+
+Card headers and filter rails use **sm / md / lg** cluster pairing — see **Foundations → Cluster** and **ADR-0011**.
+
+## Icons
+
+**Lucide only** until further notice. Pass icons into component props — do not embed icon styling utilities in app code.
+
+```tsx
+import { Plus } from "lucide-react";
+
+<Button icon={<Plus strokeWidth={2} />}>New item</Button>
+```
+
+Browse [lucide.dev/icons](https://lucide.dev/icons/).
+
+## Customization
+
+### Brand override (`--color-primary`)
+
+The **only** per-app color hook is the primary brand color. The WhatMatters default palette stays in **`src/theme/colors.css`**; an app overrides it by redefining the allowlisted tokens on `:root` (light) and `[data-theme="dark"]` (dark) in a stylesheet imported **after** `@thewhatmatters/wmds/styles.css`.
+
+**Allowlist**
+
+| Token | Required | Notes |
+|-------|----------|-------|
+| `--color-primary` | Yes | One light value on `:root`, one dark value on `[data-theme="dark"]`. |
+| `--color-on-primary` | No | Ink on primary fills. Default `#fafafa` / `#fafaf8`; set it when your brand primary is light enough to fail contrast against near-white. |
+
+Everything else is derived, so you set two values and every primary control follows:
+
+- `--color-primary-hover` / `--color-primary-active` — `color-mix` of `--color-primary` (light darkens toward black; dark lifts toward white on hover).
+- `--color-focus-ring` — `--color-primary` at 45% alpha (light); lifted toward white then 40% alpha (dark) so the ring stays visible on dark surfaces.
+
+**Snippet — `brand.css`, imported after `styles.css`**
+
+```tsx
+// app entry
+import "@thewhatmatters/wmds/styles.css";
+import "./brand.css"; // must come after styles.css
+```
+
+```css
+/* brand.css — keep unlayered so it wins the cascade against WMDS defaults */
+:root {
+  --color-primary: #7a2e8e;
+  /* --color-on-primary: #ffffff;  optional */
+}
+
+[data-theme="dark"] {
+  --color-primary: #c48ad4;
+  /* --color-on-primary: #171717;  optional */
+}
+```
+
+Rules:
+
+- Import order matters — the override must load after `styles.css` (or after `@import "@thewhatmatters/wmds/theme.css"` if you configure Tailwind yourself). Do not wrap it in a `@layer`; WMDS defaults are unlayered author styles and a layered override would lose.
+- Set both the light and the dark value. Leaving `[data-theme="dark"]` unset falls back to the WhatMatters dark primary, not to your light value.
+- Check contrast for `--color-on-primary` on your primary and for `--color-primary` on `--color-body` in both themes.
+
+**Not overridable per app:** brand navy (`--color-brand` `#011272`, `--color-on-brand`, `--color-brand-outline`, `--color-brand-soft`, `--color-on-brand-hover`), accent (`--color-accent*`, `--color-on-accent`), status (`--color-error*`, `--color-success*`, `--color-warning*`, `--color-info*`), chart series, typography (`--font-*`, `--line-height-*`, `type-*`), and grid (`--grid-*`, `--spacing`). Those roles are the shared WMDS contract — change them in `src/theme/`, rebuild, and bump the package. Do **not** fork component visuals with per-app utility overrides — extend WMDS via new variants/patterns in the design system repo.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 WhatMatters LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,65 @@
+# WMDS — WhatMatters Design System
+
+Tailwind v4 theme + **pattern-first** Storybook catalog. **Storybook is canonical** — prescribed components and Sites patterns, not utility-class soup.
+
+## Stack
+
+| Piece | Role |
+|-------|------|
+| **`src/theme/colors.css`** | Astryx-aligned semantic roles (light `:root` + `[data-theme="dark"]`) — see **ADR-0007** |
+| **`src/theme/theme.css`** | Tailwind `@theme` bridge — import once in apps |
+| **`src/theme/fonts.css`** | Geist Sans + Geist Mono |
+| **`src/theme/stateColors.css`** | Hover/active states (`color-mix` from base roles) |
+| **`src/theme/typography.css`** | Astryx geometric scale + `type-*` semantic utilities — see **ADR-0009** |
+| **`src/theme/grid.css`** | App-profile `--grid-*` + `grid-page` / `band` — see **ADR-0010**, **DESIGN.md → Grid** |
+| **`src/theme/motion.css`** | Astryx-aligned duration/easing tiers — see **ADR-0008** |
+| **`src/lib/motion.ts`** | Motion adapter — CSS vars → Tailwind + Motion |
+| **Storybook** | Token catalog + component specs (start at **Introduction**) |
+
+## Dark mode
+
+```html
+<html data-theme="dark">
+```
+
+Same utility names (`bg-body`, `text-fg`, …) — values swap in `colors.css`. Legacy `bg-bg` aliases `body`.
+
+## Commands
+
+```bash
+npm install
+npm run storybook   # http://localhost:6006 — read Introduction first
+npm run build       # dist/ — modules, types, styles.css, theme partials, fonts — then checks the manifest
+npm run lint        # oxlint
+npm run typecheck   # tsc -b — src, stories, and tests
+npm run test:unit
+npm run test:interactions     # every story in Chromium, accessibility included
+npm run validate:composition  # molecules/organisms must compose atoms (CI)
+```
+
+**Agents:** read **`AGENTS.md`** and **`.cursor/rules/`** before authoring components — Storybook patterns are the contract; `npm run validate:composition` enforces atomic composition. **AGENTS.md → Guardrails** lists the rules CI enforces, and **`docs/audits/`** records why.
+
+## Status
+
+**Shipped (exported from `@thewhatmatters/wmds`):**
+
+| Tier | Components |
+|------|------------|
+| Atoms | `Avatar`, `Badge`, `Button`, `Checkbox`, `IconButton`, `Input`, `Kbd`, `Radio`, `RiveHand`, `Skeleton`, `Status`, `Switch`, `TextArea`, `TextLink`, `Tooltip` |
+| Molecules | `Accordion`, `CalEmbed`, `Card`, `ChatQa`, `CheckboxGroup`, `Chip`, `DisplayControls`, `Dropdown`, `Field`, `FloatingActionButton`, `HeroIntro`, `IntakeForm`, `NavList`, `PageHeader`, `PillGroup`, `PromptBar`, `RadioGroup`, `Search`, `Select`, `SelectableCard`, `SegmentedControl`, `Stat`, `StepProgress`, `TaskRows`, `TextSequence` |
+| Organisms | `Chart`, `Confetti`, `Dialog`, `FooterReveal`, `HeroTileStack`, `IntakeConfirmation`, `IntakeModal`, `MoreMenu`, `Panel`, `ScrollHorizontal`, `Sheet`, `SiteNav`, `Tab`, `Toast` |
+| Planned, not built | `Carousel`, `Pagination`, `Table` |
+
+The list is `src/package.manifest.ts`. `npm run build` fails when it and `src/index.ts` disagree.
+
+**Storybook-only:** **Sites/** (pages and flows per product — WhatMatters, PitchKit) and **Guides/** (cross-component guidance) — page-level compositions for copy-paste; not package exports.
+
+**Motion:** CSS tokens for simple transitions; [`motion/react`](https://motion.dev/docs/react) for gestures, layout, and enter/exit. Helpers in **`src/lib/motion.ts`** (reads Theme CSS vars).
+
+**Architecture:** Theme → lib → Atoms → Molecules → Organisms → Sites / Guides. **Pattern-first** for consumers ([ADR-0004](docs/adr/0004-pattern-first-not-utility-first.md)). **Mobile-first** on all tiers ([ADR-0003](docs/adr/0003-responsive-mobile-first.md)). See ADR-0001, ADR-0002.
+
+## Paper
+
+Paper may stay installed for mockups — it does **not** own tokens. Design follows Storybook.
+
+See **`CONSUMING.md`** for using WMDS in other apps.