@radicool/throughline 0.13.0 → 0.15.0

package/adapters/generic/skills/retrofit-planner/SKILL.md

@@ -1,6 +1,7 @@
 # Retrofit planner (orchestrator)
 
-Sequences a brownfield retrofit through the safe 7-phase order, gating each phase on a
+Sequences a brownfield retrofit through the safe seven-phase order (with `docs` inserted
+as a gated Phase 6.5), gating each phase on a
 human confirmation. Like `component-pipeline`, this skill holds **zero domain logic of
 its own** — it is a sequencer that invokes the real skills and the phase work, and only
 updates the manifest fields it owns (`retrofit.*`, `completedSkills`). All the
@@ -102,6 +103,25 @@ triad as you go — `check-types`, `build-storybook` + Chromatic, **and run the
 + spot-check 5–7 routes (the build alone is blind to story-unreachable SCSS). **Gate:**
 confirm the triad passes before continuing.
 
+### Phase 6.5 — `docs` (adopt existing documentation, then fill gaps)
+
+Set `retrofit.phase = "docs"`. Bring the documentation layer onto the system's
+components **adopt-first**, so no existing human-written doc is lost:
+
+1. **Adopt.** For each component, run the doc-authoring ingest (Step 4.5 of
+   `component-builder`): read existing code JSDoc/MDX/README and Figma
+   `description`, seed the canonical `.doc.json` marked `provenance: imported`, and
+   stamp fingerprints. This first pass **claims** existing content — it is not a
+   re-render and must not overwrite it.
+2. **Fill gaps.** Run the remaining generation layers (infer → enrich → specialize
+   → interview) only for blocks the adoption did not populate; the user approves.
+3. **Project + gate.** Render the code surfaces (Step 5.5 of
+   `storybook-chromatic-builder`), run `docs:digest`, and run `docs:check` — it
+   should pass (surfaces just rendered) with Figma surfaces `edit-unverified`.
+
+Confirm with the user before writing, consistent with every other phase. On a large
+system, size the batch from `audit.docSurface` and adopt in reviewable chunks.
+
 ### Phase 7 — `cleanup`
 
 Remove the old token outputs **only after** the repo-wide token-removal guard returns

package/adapters/generic/skills/storybook-chromatic-builder/SKILL.md

@@ -27,6 +27,17 @@ system). Wire it to consume `packages/tokens` output so stories render with the
 real design tokens (import the generated CSS/theme). Checkpoint: confirm
 Storybook runs and shows the token-themed canvas.
 
+Install the documentation scripts alongside the token scripts: copy the five
+files and register the three npm scripts listed under **Documentation scripts —
+install as a set** in `.throughline/scripts/README.md`. That table is
+the single source of truth for what a consuming repo gets; do not restate the
+list here.
+
+These are the documentation analog of `tokens:validate`; see
+`.throughline/scripts/README.md`. This copy is setup, not a forever-fork:
+`/document-component` re-checks these files' freshness on every run and refreshes
+them from the plugin when it has moved on.
+
 **pnpm build-script allowlist (first-run gotcha).** On pnpm workspaces, the
 `@storybook/react-vite` install pulls `esbuild`, whose postinstall is blocked by
 pnpm's default `onlyBuiltDependencies` policy — Storybook then fails to start with a
@@ -149,6 +160,43 @@ Configure Chromatic to snapshot everything (do **not** set `onlyChanged`), and
 verify a token-only PR re-snapshots all stories — they should flip orange against
 the green baseline.
 
+### Usage & cost guardrails
+
+The full-snapshot default above is the right call for catching regressions, and it
+is also the **maximum-usage** choice: every story, every run. Chromatic bills per
+snapshot, so name this cost shape to the user when you set Chromatic up, and put the
+guardrails in *before* the first big token PR, not after the bill.
+
+What Chromatic actually offers (re-verify the live numbers at
+`chromatic.com/pricing` — they drift):
+
+- **Free plan (~5,000 snapshots/month):** testing **auto-pauses** when the ceiling
+  is hit. No surprise bill, but visual-regression coverage silently *stops* until
+  the monthly reset or an upgrade. For a full-suite design system that ceiling
+  arrives fast — treat a *paused* build as a red flag, not a passing one.
+- **Paid plans: no hard spending cap.** Overage snapshots auto-bill at month-end.
+  The only native guardrail is **usage alerts** — an email when consumption crosses
+  a threshold you set (e.g. 90%).
+
+The math, so the user sizes the plan honestly: **snapshots ≈ stories × modes ×
+builds.** One `/sync-figma-tokens` PR re-snapshots the *entire* suite × every mode
+in a single build — e.g. 40 components × 2 modes = 80 snapshots per build, and a
+handful of token PRs plus daily `main` builds clears a free tier in a week.
+
+So the guardrails, all of them user-controlled (Chromatic will not cap you):
+
+1. **Set usage alerts** at ~80% on a paid plan so the bill cannot sneak up. On the
+   free plan, make sure the user knows testing *pauses* at the ceiling.
+2. **Scope the CI trigger.** Run Chromatic on **pull requests and `main` only** —
+   never on every branch push — path-filter out docs-only changes, and keep it to
+   one Chromatic build per commit (no duplicate runs).
+3. **Size the plan to the math** before the first token PR. A large story count is
+   also the *only* reason to revisit TurboSnap (see above), and even then treat
+   every token change as a full run.
+
+Do not silently pick a plan or leave the trigger wide open. Name the tradeoff and
+let the user choose with the numbers in front of them.
+
 ## Step 5 — Code Connect (plan-gated, skip gracefully)
 
 Code Connect ties Figma components to their code counterparts so Figma's dev
@@ -170,6 +218,32 @@ mode shows the real code. It's plan-gated (Figma Organization/Enterprise).
   run after the user publishes. This does **not** block the code side: implement
   each slot prop from the recorded slot contract regardless of the Figma dropdown.
 
+## Step 5.5 — Render documentation to code
+
+For each component that has a canonical record
+(`design-system/docs/components/<Name>.doc.json`), render the code-side surfaces
+from it (read `.throughline/references/component-doc-schema.md` for the
+projection contract):
+
+- **Storybook autodocs (MDX).** Generate `<Name>.mdx` next to the component (e.g.
+  `packages/ui/src/<Name>/<Name>.mdx`) rendering summary, description,
+  when-to-use/not, do's/don'ts, accessibility, and a variant/state table. Put the
+  record's fingerprint in MDX frontmatter as `docFingerprint: <fp>`.
+- **JSDoc.** Add a doc comment to the code component from `summary` + `description`
+  and per-prop descriptions from `variants`/`states` meanings, so `argTypes`
+  descriptions surface in the Storybook controls table.
+- **AI digest.** Run `docs:digest` to (re)generate `design-system/docs/index.json`
+  + `design-system/docs/llms.txt` from all records.
+
+**Update the manifest:** add the `storybookMdx` surface to
+`components.meta[<Name>].doc.surfaces` as `{ src: <fp>, render: <hash of the MDX
+file>, file: "<repo-relative MDX path>" }`.
+
+**Wire the gate.** Ensure `docs:check` is part of the repo's verification (a CI
+step and/or a Turbo task). It compares every surface against its record and exits
+non-zero on drift; Figma surfaces report `edit-unverified` (checked live in a Figma
+session). Run `docs:check` once here and confirm it passes before handing off.
+
 ## Step 6 — Finalize component status (Figma write-back)
 
 A component built and storied here is now **done** — but its Figma doc card was
@@ -193,10 +267,15 @@ the `figma_execute` scripting gotchas — `getNodeByIdAsync` and an explicit
 
 - Set `components.meta[name].status` = `"stable"` and refresh
   `components.meta[name].updatedAt` to today.
+- When promoting status (e.g. draft → stable), also set `status` + `updatedAt` in
+  the component's `.doc.json`, recompute its fingerprint, re-run `docs:digest`, and
+  re-render the affected surfaces so `docs:check` stays green.
 - If Figma is connected (per `figma.mechanism`), open the component's doc card and
   update the `Status Label` text to `stable`, re-bind the `Status` chip fill to
-  the **success** semantic color variable (mode-aware, not a hardcoded hex), and
-  set `Last Updated` to today's date — then screenshot to confirm the chip
+  the **success** semantic color variable (mode-aware, not a hardcoded hex), then
+  re-run the canonical doc-card builder against the same card to refresh the
+  header date from the `record.updatedAt` already set above (it locates the date
+  node under either header shape) — then screenshot to confirm the chip
   recolored and the date changed.
 - If Figma isn't connected, still update the manifest and tell the user the card
   will reconcile next Figma session (or offer to reconnect and fix it now).
@@ -257,6 +336,9 @@ that may not exist.
 - Never rely on TurboSnap (`onlyChanged: true`) for a token-driven design system
   — its incremental model keeps missing global token changes. Default to full
   snapshots (every story, every run); revisit only at large story counts.
+- Never leave Chromatic's cost shape unspoken or the CI trigger wide open — there
+  is no hard spend cap on paid plans, so set usage alerts, run it on PRs + `main`
+  only, and size the plan to stories × modes × builds before the first token PR.
 - Never use the sequential model for story-gen — parallelize via subagents.
 - Never capture the Chromatic baseline *after* a code retrofit — baseline before, so
   intended drift-fixes are distinguishable from regressions.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@radicool/throughline",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "description": "Build a complete design system end to end — author in Figma, sync tokens to code, generate Storybook. Usable from Claude Code, Cursor, Codex, or any AGENTS.md agent.",
   "type": "module",
   "bin": {

package/references/component-doc-archetypes.md

@@ -0,0 +1,90 @@
+# Component documentation archetypes
+
+The best-practice knowledge layer for the documentation generation pipeline
+(`component-builder` Step: *Author the documentation record*). When authoring a
+component's `.doc.json`, match the component to the nearest **archetype** below and
+seed its `dos`, `donts`, `accessibility`, `whenToUse`, and `whenNotToUse` from that
+entry, then specialize to the target framework and confirm with the user. Stamp
+`provenance` as `best-practice` (or `w3c-apg` for the accessibility block) for
+anything sourced here.
+
+These are **seeds, not gospel** — the user's approval and the actual built
+component override them. Sources: W3C ARIA Authoring Practices Guide (roles +
+keyboard), Material 3, Shopify Polaris (content/usage), IBM Carbon (usage).
+
+Seeds are clause-style shorthand; the authoring pipeline expands them into full sentences per references/doc-writing-standard.md before they enter a record.
+
+## Button
+
+- **whenToUse:** trigger an action or event (submit, confirm, open a dialog).
+- **whenNotToUse:** navigation between pages/URLs (use a Link).
+- **dos:** lead the label with a verb; keep one primary (highest-emphasis) button
+  per view; keep labels short (≤ ~3 words).
+- **donts:** don't use a button for navigation (use a Link); don't stack multiple
+  primary buttons (keep one per view); don't disable without telling the user why.
+- **accessibility (w3c-apg):** role `button`; Enter and Space activate; an
+  icon-only button needs an `aria-label`; disabled buttons are not focusable.
+
+## Input / text field
+
+- **whenToUse:** collect a single line of free-form text.
+- **whenNotToUse:** choosing from a fixed set (use Select/Radio); long multi-line
+  text (use Textarea).
+- **dos:** always pair with a visible label; show format hints as helper text;
+  reserve space for error text to avoid layout shift.
+- **donts:** don't use placeholder text as the only label (pair with a visible
+  label); don't validate on every keystroke before first blur.
+- **accessibility (w3c-apg):** every input has a programmatically associated
+  `<label>`; error state sets `aria-invalid` and links the message via
+  `aria-describedby`.
+
+## Checkbox / radio / toggle
+
+- **whenToUse:** checkbox/toggle for independent on/off; radio for one-of-many.
+- **whenNotToUse:** a single either/or action that takes effect immediately with no
+  save (prefer a toggle) vs. a form choice (prefer radio/checkbox).
+- **dos:** label the control, not just the group; make the label clickable.
+- **donts:** don't use a radio group for multi-select (use checkboxes); don't use
+  a toggle for choices needing a separate Save (use radio/checkbox).
+- **accessibility (w3c-apg):** roles `checkbox` / `radio` / `switch`; Space
+  toggles; radio groups navigate with arrow keys; state exposed via
+  `aria-checked`.
+
+## Card
+
+- **whenToUse:** group related content and actions about a single subject.
+- **whenNotToUse:** primary page layout scaffolding (use a layout/grid component); a
+  bare list of text (use a List).
+- **dos:** make the primary action obvious; keep one main call-to-action per card.
+- **donts:** don't nest cards more than one level; don't make the whole card AND an
+  inner button separately clickable in conflicting ways.
+- **accessibility:** if the whole card is a link/button, it needs an accessible
+  name; don't bury interactive controls that keyboard users can't reach in order.
+
+## Modal / dialog
+
+- **whenToUse:** interrupt for a focused task or a decision that blocks the flow.
+- **whenNotToUse:** non-critical messages (use an inline banner or toast).
+- **dos:** trap focus while open; return focus to the trigger on close; provide an
+  explicit close affordance.
+- **donts:** don't stack modals; don't put long scrolling forms in a small modal.
+- **accessibility (w3c-apg):** role `dialog` with `aria-modal="true"`; labelled by
+  its title (`aria-labelledby`); Escape closes; focus is trapped within.
+
+## Badge / chip / tag
+
+- **whenToUse:** short status, count, or category label (badge); a removable/
+  selectable item (chip).
+- **whenNotToUse:** interactive primary actions (use a Button).
+- **dos:** keep text to a word or two; match badge color to its semantic meaning
+  (success, warning, error).
+- **donts:** don't rely on color alone to convey status (include text or an icon).
+- **accessibility:** a removable chip's remove control needs an accessible name
+  (e.g. "Remove <label>"); status conveyed with text, not color only (WCAG 1.4.1).
+
+## Fallback (unlisted archetype)
+
+For a component without an entry above: derive `dos`/`donts` from its role and
+built structure, source the `accessibility` block from the matching W3C APG
+pattern, and mark everything for user confirmation. Add a new archetype section
+here once the component's guidance stabilizes.

package/references/component-doc-schema.md

@@ -0,0 +1,154 @@
+# Component documentation record
+
+The canonical, folder-resident source of truth for a component's usage
+documentation. One JSON file per component at
+`design-system/docs/components/<ComponentName>.doc.json`. Every other
+documentation surface (Figma component description, the doc card, Storybook
+autodocs/MDX, the AI digest) is a **projection** rendered from this file — never
+authored independently.
+
+It lives in the working folder from the moment a component is built (exactly like
+`design-system.json`), so it exists during the Figma-only *folder* stage, before
+any repo. The path stays `design-system/docs/` across folder→repo; files never
+move.
+
+## Why JSON (not YAML)
+
+The plugin's scripts are zero-dependency and there is no YAML parser available, so
+the record is JSON to keep `docs:check` and `docs:digest` able to parse it
+deterministically. JSON is equally machine-legible for AI consumers.
+
+## Schema
+
+```json
+{
+  "name": "Button",
+  "summary": "Triggers an action or event.",
+  "description": "A clickable control that initiates an action…",
+  "whenToUse": ["Submitting a form", "Confirming a decision"],
+  "whenNotToUse": ["Navigating to a new page — use a Link"],
+  "variants": {
+    "type": { "primary": "Highest-emphasis action…", "secondary": "…", "ghost": "…" },
+    "size": { "sm": "…", "md": "…", "lg": "…" }
+  },
+  "states": { "hover": "…", "focus": "…", "disabled": "…", "loading": "…" },
+  "dos": ["Lead with a verb", "One primary button per view"],
+  "donts": ["Don't use for navigation", "Don't stack >2 primaries"],
+  "accessibility": {
+    "role": "button",
+    "keyboard": ["Enter / Space activates"],
+    "notes": ["Icon-only buttons need an aria-label"]
+  },
+  "tokensUsed": ["color.bg.primary", "spacing.sm", "radius.md"],
+  "status": "stable",
+  "updatedAt": "2026-07-14",
+  "provenance": {
+    "description": "ai-inferred",
+    "dos": "best-practice+user",
+    "accessibility": "w3c-apg"
+  }
+}
+```
+
+### Fields (v1 core)
+
+- **Required:** `name`, `summary`, `description`.
+- **Optional content:** `whenToUse`, `whenNotToUse`, `variants`, `states`, `dos`,
+  `donts`, `accessibility`, `tokensUsed`.
+- **Lifecycle:** `status` (`draft`|`beta`|`stable`|`deprecated`), `updatedAt` (ISO date).
+- **`provenance`** — per-block author source, one of `imported`, `ai-inferred`,
+  `best-practice`, `w3c-apg`, `framework`, `user`, or a `+`-joined combination
+  (e.g. `best-practice+user`). Regeneration **re-infers** a block whose
+  provenance includes `ai-inferred`, `framework`, `best-practice`, or `w3c-apg`,
+  and **never overwrites** one whose provenance includes `user` or `imported`.
+  Every value is assigned to exactly one of those two tiers: generated content is
+  re-inferred, human input (`user`) and pre-existing external content
+  (`imported`) are protected. Protection takes precedence: a combination that
+  contains both — `best-practice+user`, say — is protected. A block is
+  re-inferred only when it carries no `user` or `imported` marker at all. A
+  protected block may still be rewritten when the user approves the rewrite at
+  the record-approval gate; the result is stamped `imported+user`, which is
+  protected from then on and never re-proposed.
+
+Deferred to a later version (do not emit in v1): `anatomy`, `content` (writing
+guidelines), `examples`.
+
+## Fingerprint algorithm
+
+`fingerprint = sha256(stableStringify(record_without_provenance)).slice(0, 16)`
+
+- `provenance` is **excluded** — it is authoring metadata, not projected content.
+- `stableStringify` sorts object keys recursively so formatting/key-order never
+  affects the hash.
+- The 16-hex-char result is the stamp recorded per surface and per canonical file.
+
+Implemented once in `scripts/lib/doc-record.mjs` (`canonicalFingerprint`) and
+reused by `docs:check`, `docs:digest`, and — for the Figma surfaces — by the
+Figma-connected skill computing the identical hash over the description content.
+
+## Projection mapping
+
+| Block(s) | Figma component description | Doc card | Storybook autodocs (MDX) + JSDoc | AI digest |
+|---|---|---|---|---|
+| summary, description | ✔ | ✔ | ✔ | ✔ |
+| whenToUse / whenNotToUse | ✔ | ✔ | ✔ | ✔ |
+| variants, states (meanings) | — | ✔ legend | ✔ argTypes | ✔ |
+| dos / donts | ✔ | ✔ | ✔ | ✔ |
+| accessibility | ✔ | ✔ | ✔ | ✔ |
+| tokensUsed | — | — | ✔ | ✔ |
+
+Each surface carries a fingerprint stamp of the record it was rendered from:
+- **Figma component description** — a trailing marker line `<!-- tl:doc <fp> -->`.
+- **Doc card** — a named metadata node `Doc Fingerprint` holding `<fp>`.
+- **Storybook MDX** — a frontmatter field `docFingerprint: <fp>`.
+
+## Manifest pointer (`components.meta[name].doc`)
+
+The manifest stores pointers + per-surface fingerprints, never content:
+
+```json
+{
+  "doc": {
+    "path": "design-system/docs/components/Button.doc.json",
+    "fingerprint": "<canonical fingerprint at last render>",
+    "surfaces": {
+      "figmaDescription": { "src": "<fp>", "render": "<hash of description text>" },
+      "docCard":          { "src": "<fp>", "render": "<hash of card content>", "renderer": "4" },
+      "storybookMdx":     { "src": "<fp>", "render": "<hash of mdx file>", "file": "packages/ui/src/Button/Button.mdx" }
+    }
+  }
+}
+```
+
+- `src` — the canonical fingerprint the surface was rendered from (detects **stale**).
+- `render` — a hash of the surface's rendered content at render time (detects
+  **edited**, for surfaces the tooling can re-read).
+- `file` — repo-relative path for code surfaces so `docs:check` can re-read them.
+- `renderer` — (docCard only) the layout version of the builder that last
+  rendered the card: `DOC_CARD_RENDERER_VERSION` in `scripts/lib/doc-card-plan.mjs`,
+  currently `"4"`. Additive and optional — absence means the card predates the
+  versioned builder. Stamped from the builder's returned summary, never by
+  re-reading the card.
+
+## Drift + reconciliation contract
+
+`docs:check` classifies each surface:
+- **canonical-changed** — the `.doc.json` fingerprint ≠ `doc.fingerprint`.
+- **stale** — `surface.src` ≠ current canonical fingerprint.
+- **edited** — a re-readable surface's current content hash ≠ `surface.render`.
+- **layout-upgrade-available** — informational, never failing, docCard only:
+  `surfaces.docCard.renderer` is missing or lower than the current
+  `DOC_CARD_RENDERER_VERSION`. The card's content is not in drift — its layout
+  predates the current builder. Re-render on next touch (no unprompted Figma
+  writes; untouched brownfield cards must not generate a standing warning wall).
+- **missing-surface** — a repo surface that declares a `file` which is now gone.
+  Failing, and distinct from `edit-unverified`: the surface *was* re-readable and
+  its rendered output has been deleted, not merely unreadable this run.
+- **edit-unverified** — a surface the CLI can't read (Figma); checked live by the
+  Figma-connected skill instead.
+
+Reconciliation is **per item, reviewable**: for each drift the user chooses
+**re-render** (canonical wins) or **pull-back** (fold the surface edit into the
+record), landed as a PR. **Brownfield first run is an adoption**, not a re-render:
+existing surface content is claimed into the record as `provenance: imported` and
+fingerprints are stamped, rather than treated as `edited` drift.