@radicool/throughline 0.14.0 → 0.16.0

package/adapters/cursor/.cursor/rules/icon-system-builder.mdc

@@ -1,5 +1,5 @@
 ---
-description: "Build an icon system in Figma — a dedicated \"Icons\" page populated with the user's chosen icon library (Lucide, Material, or custom SVGs) as well-named, scalable components — using the fastest, most-automated mechanism per library (for Lucide, batch-fetching the curated subset's official SVGs from the source repo and componentizing them hands-off; for Material, the official community file or importer plugin) rather than hand-generating icons or making the user copy components by hand. Use this when the user wants to set up icons, add an icon library, import Lucide or Material icons, create icon components, or build an icon set in Figma. Also trigger when the user mentions iconography, an icon page, or needs icons for their components. Make sure to use this whenever someone needs a managed set of icon components in their Figma design system."
+description: "Build an icon system in Figma — a dedicated \"Icons\" page of well-named, scalable icon components from Lucide, Tabler, Phosphor, Material, or custom SVGs. Use this when the user wants to set up icons, add an icon library, import Lucide or Material icons, create icon components, or build an icon set in Figma. Also trigger when the user mentions iconography, an icon page, or needs icons for their components."
 alwaysApply: false
 ---
 # Icon system builder

package/adapters/cursor/.cursor/rules/repository-builder.mdc

@@ -1,5 +1,5 @@
 ---
-description: "Graduate the local design-system folder into a real monorepo — a pnpm + Turborepo workspace with packages for tokens and UI components and room for apps — and walk the user from a plain folder to local git to a GitHub remote with PRs and CI. Use this when the user wants to set up a repo, create a GitHub repository, add version control, turn their folder into a real project, or prepare to sync tokens to code. Also trigger when the user mentions monorepo, Turborepo, pnpm workspace, GitHub, version control, or when the token-sync or Storybook skills report that a repo isn't set up yet. Make sure to use this skill when someone is moving from the Figma/design phase into the code phase, even if they just say \"I want to turn this into code\" — it's the bridge between the two halves."
+description: "Graduate the local design-system folder into a real monorepo — a pnpm + Turborepo workspace with packages for tokens and UI components — and walk the user from a plain folder to local git to a GitHub remote with PRs and CI. Use this when the user wants to set up a repo, create a GitHub repository, add version control, turn their folder into a real project, or say \"I want to turn this into code\". Also trigger when the user mentions monorepo, Turborepo, pnpm workspace, GitHub, version control, or when the token-sync or Storybook skills report that a repo isn't set up yet."
 alwaysApply: false
 ---
 # Repository builder

package/adapters/cursor/.cursor/rules/retrofit-planner.mdc

@@ -1,5 +1,5 @@
 ---
-description: "Orchestrate a full brownfield design-system retrofit end to end — audit, refine variables in place, rebind components, sync, capture a Chromatic baseline, retrofit the code with dual output, adopt existing documentation then fill gaps, then remove the old tokens only after a zero-reference grep — with a human confirmation gate between every phase. Use this when the user wants to run a complete retrofit, migrate a mature codebase and populated Figma file onto tokens, resume an in-progress retrofit, or be walked through the safe retrofit sequence. Also trigger after design-system-audit has sized the system, or when figma-environment-setup detects an in-progress retrofit. Make sure to use this whenever someone wants the guided, gated, multi-session brownfield retrofit rather than running the individual skills by hand."
+description: "Orchestrate a full brownfield design-system retrofit end to end — audit, refine, rebind, sync, baseline, code, docs, cleanup — with a human confirmation gate between every phase. Use this when the user wants to run a complete retrofit, migrate a mature codebase and populated Figma file onto tokens, resume an in-progress retrofit, or be walked through the safe retrofit sequence. Also trigger after design-system-audit has sized the system, or when figma-environment-setup detects an in-progress retrofit."
 alwaysApply: false
 ---
 # Retrofit planner (orchestrator)

package/adapters/cursor/.cursor/rules/storybook-chromatic-builder.mdc

@@ -1,5 +1,5 @@
 ---
-description: "Stand up Storybook in the monorepo, build code components matching the Figma design system (consuming the synced tokens and implementing the captured slot contracts), generate stories for every component, set up Chromatic for visual regression testing, and wire Code Connect when the user's Figma plan supports it. Use this when the user wants to set up Storybook, build component stories, add visual regression testing, set up Chromatic, connect Figma components to code, or build the code side of their design system. Also trigger after components and token sync exist, when moving the component library into code. Make sure to use this whenever someone wants their Figma components realized as documented, tested code."
+description: "Stand up Storybook in the monorepo, build code components matching the Figma design system, generate stories for every component, set up Chromatic for visual regression testing, and wire Code Connect when the user's Figma plan supports it. Use this when the user wants to set up Storybook, build component stories, add visual regression testing, set up Chromatic, connect Figma components to code, or build the code side of their design system. Also trigger after components and token sync exist, when moving the component library into code."
 alwaysApply: false
 ---
 # Storybook + Chromatic builder
@@ -31,15 +31,16 @@ 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 from the
-plugin's `scripts/` — `build-docs-digest.mjs`, `docs-check.mjs`, and
-`lib/doc-record.mjs` — into the repo and register npm scripts):
-
-- `"docs:digest": "node scripts/build-docs-digest.mjs"`
-- `"docs:check": "node scripts/docs-check.mjs"`
+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`.
+`.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
@@ -163,6 +164,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
@@ -238,8 +276,10 @@ the `figma_execute` scripting gotchas — `getNodeByIdAsync` and an explicit
   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).
@@ -300,6 +340,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/adapters/cursor/.cursor/rules/token-builder.mdc

@@ -1,5 +1,5 @@
 ---
-description: "Build a two-tier (primitive + semantic) design token system as Figma variables — color ramps, spacing, type scale, radius, shadows — with light/dark or brand modes. IMPORTANT: this uses ONE COLLECTION PER CATEGORY PER TIER, never one giant Primitives collection + one giant Semantic collection. Each category (color, spacing, type, radius, border) gets its own primitive collection and its own semantic collection so that mode axes (Light/Dark, Desktop/Mobile) belong only to the categories that need them. Use this when the user wants to create design tokens, design variables, a color system, a type scale, a spacing system, or 'build my tokens' in Figma. Also trigger when the user mentions primitives and semantic tokens, variable collections, design system foundations, or modes/themes in Figma."
+description: "Build a two-tier (primitive + semantic) design token system as Figma variables — color ramps, spacing, type scale, radius, shadows — with light/dark or brand modes, using one collection per category per tier. Use this when the user wants to create design tokens, design variables, a color system, a type scale, a spacing system, or 'build my tokens' in Figma. Also trigger when the user mentions primitives and semantic tokens, variable collections, design system foundations, or modes/themes in Figma."
 alwaysApply: false
 ---
 # Token builder

package/adapters/cursor/.cursor/rules/token-crosswalk-builder.mdc

@@ -1,5 +1,5 @@
 ---
-description: "Build the brownfield token crosswalk — a persistent three-way map between each new token, the old Figma variable, and the old code identifier(s) — as crosswalk.json, then install the vetted validator/reverse-index scripts into the monorepo and wire the tokens:validate CI gate. Use this when retrofitting a design system onto a mature codebase, when the user wants to map old tokens to new ones, build a crosswalk, set up tokens:validate, or generate a reverse index for SCSS/Tailwind swaps. Also trigger when retrofit-planner reaches the crosswalk stage, or after design-system-audit has sized the retrofit. Make sure to use this whenever someone needs the machine-readable backbone that drives a brownfield code retrofit and its validation gate."
+description: "Build the brownfield token crosswalk — a persistent three-way map between each new token, the old Figma variable, and the old code identifier(s) — then wire the tokens:validate CI gate. Use this when retrofitting a design system onto a mature codebase, when the user wants to map old tokens to new ones, build a crosswalk, set up tokens:validate, or generate a reverse index for SCSS/Tailwind swaps. Also trigger when retrofit-planner reaches the crosswalk stage, or after design-system-audit has sized the retrofit."
 alwaysApply: false
 ---
 # Token crosswalk builder
@@ -69,6 +69,8 @@ Copy these from `.throughline/scripts/` into the user's repo **verbatim**
 (they are zero-dependency and version with the user's repo so their CI can run them):
 
 - `lib/crosswalk.mjs` → `packages/tokens/scripts/lib/crosswalk.mjs`
+- `lib/dtcg.mjs` → `packages/tokens/scripts/lib/dtcg.mjs` (required by
+  `validate-crosswalk.mjs` — copying the validator without it breaks the gate at import)
 - `validate-crosswalk.mjs` → `packages/tokens/scripts/validate-crosswalk.mjs`
 - `build-reverse-index.mjs` → `packages/tokens/scripts/build-reverse-index.mjs`
 - `guard-token-removal.mjs` → `packages/tokens/scripts/guard-token-removal.mjs`

package/adapters/cursor/.cursor/rules/token-sheet-builder.mdc

@@ -1,5 +1,5 @@
 ---
-description: "Build a beautiful, on-brand \"Foundations\" page in Figma that visually documents every variable collection and style — color ramps with swatches, the type scale, spacing, radius, shadows/elevations — with swatches live-bound to the actual variables where Figma allows. Use this when the user wants a visual stylesheet, a token reference page, a Foundations page, to document or showcase their design system, or to \"see all my tokens\" laid out. Also trigger after token-builder completes, when the user wants a visual artifact of their tokens. Make sure to use this when someone wants their tokens presented visually rather than just existing as variables."
+description: "Build an on-brand \"Foundations\" page in Figma that visually documents every variable collection and style — color ramps with swatches, the type scale, spacing, radius, shadows/elevations. Use this when the user wants a visual stylesheet, a token reference page, a Foundations page, to document or showcase their design system, or to \"see all my tokens\" laid out. Also trigger after token-builder completes, when the user wants a visual artifact of their tokens."
 alwaysApply: false
 ---
 # Token sheet builder

package/adapters/cursor/.cursor/rules/token-sync-layer.mdc

@@ -1,5 +1,5 @@
 ---
-description: "Sync Figma design variables into code-ready token files by extracting them to DTCG-format JSON, running them through Style Dictionary, and emitting framework-specific outputs via per-platform adapters (shadcn/Tailwind, MUI, vanilla CSS, iOS Swift, Android Kotlin, or custom). Sets up the reusable \"sync figma tokens\" command that re-runs the pipeline to catch updates and opens a PR for review. Use this when the user wants to turn Figma tokens into code, sync design tokens, generate tokens.css or a Tailwind config or tokens.swift, set up a token pipeline, or run \"sync figma tokens\". Also trigger when the user mentions Style Dictionary, design token export, or keeping code in sync with Figma. Make sure to use this whenever someone wants their Figma variables reflected in actual code files."
+description: "Sync Figma design variables into code-ready token files via DTCG JSON and Style Dictionary, emitting framework-specific outputs (shadcn/Tailwind, MUI, vanilla CSS, iOS Swift, Android Kotlin, or custom), and set up the reusable \"sync figma tokens\" command. Use this when the user wants to turn Figma tokens into code, sync design tokens, generate tokens.css or a Tailwind config or tokens.swift, set up a token pipeline, or run \"sync figma tokens\". Also trigger when the user mentions Style Dictionary, design token export, or keeping code in sync with Figma."
 alwaysApply: false
 ---
 # Token sync layer
@@ -48,8 +48,8 @@ Ask which platform(s) the user is building for. Read
 - **Curated (Tier 1):** `shadcn`, `tailwind`, `mui`, `vanilla-css`, `ios-swift`.
   Vetted presets — high confidence.
 - **Generated (Tier 2):** any other framework (Ant Design, Chakra, HeroUI,
-  Android/Kotlin, Flutter, etc.). The skill generates an adapter and verifies it
-  against a real component before trusting it.
+  Android/Kotlin, Flutter, etc.). The skill generates an adapter and
+  verifies it against a real component before trusting it.
 
 **Always tell the user which tier they're on.** If they name a curated one, say
 it'll be solid. If they name anything else, be honest: "That's not one I have a
@@ -143,11 +143,53 @@ register the platform, transform group, format, and `outputReferences`
 flattens). Web adapters emit `:root`/`.dark` (or `[data-theme]`); the shadcn
 adapter also emits a Tailwind preset.
 
+**Native targets import the shipped configuration; they do not transcribe it.**
+Copy `.throughline/scripts/lib/sd-native.mjs` into
+`packages/tokens/scripts/lib/` (see Step 4) and call it. The stock `ios-swift`
+and `compose` transform groups emit every `px`-authored dimension at ×16 its
+value — valid, compiling, silently wrong — and mishandle `color-mix()` and
+dual-node DTCG the same way. Never build a native platform from a stock
+`transformGroup`.
+
+```js
+import StyleDictionary from 'style-dictionary';
+import { registerNativeTransforms, nativePlatform, nativeSources }
+  from './scripts/lib/sd-native.mjs';
+
+registerNativeTransforms(StyleDictionary);
+
+for (const mode of MODES) {                     // e.g. ['light', 'dark']
+  const sd = new StyleDictionary({
+    source: nativeSources(sourcesFor(mode)),    // guards against a mode collapse
+    preprocessors: ['dtcg/resolve-dual-node'],
+    platforms: {
+      ios: nativePlatform({ platform: 'ios-swift', buildPath: `ios/${mode}/` }),
+      // android also requires packageName:
+      // android: nativePlatform({ platform: 'android-kotlin',
+      //   buildPath: `android/${mode}/`, packageName: 'com.example.tokens' }),
+    },
+  });
+  await sd.buildAllPlatforms();
+}
+```
+
+**One build per mode combination, and never a glob.** Style Dictionary dedupes
+by dot-path, so a single build over the whole token directory collapses light
+and dark into whichever file sorted last, silently dropping a mode. Passing each
+mode's sources through `nativeSources` turns that into a thrown error naming the
+colliding paths. The `dtcg/resolve-dual-node` preprocessor throws too, on its
+own collision: a dual node's hoisted child renamed to a camel-joined name that
+an existing sibling or an earlier hoist in the same pass already has. Then run
+`tokens:validate-output` against each generated file with that same source
+list. See `.throughline/references/native-adapter-config.md`.
+
 **Execution model — subagent dispatch with model routing.** Generating each
 platform's output is independent and verifiable. If your host supports subagent
 dispatch, dispatch **one `code-executor` per adapter** — each produces its
-platform's files and verifies them (the config builds, the expected files
-appear, references resolve for web / flatten for native) — then a **`reviewer`**
+platform's files and verifies them (for web: the config builds, the expected
+files appear, references resolve; for native: `tokens:validate-output` passes —
+"the config builds" is not verification, it is the condition under which all
+four known native failure modes ship silently) — then a **`reviewer`**
 to check each before combining. Choose each subagent's model from its role tier
 per `.throughline/references/agent-routing.md` (`code-executor` → fast,
 `reviewer` → balanced), and only dispatch once each adapter's spec is complete
@@ -163,6 +205,24 @@ as **build artifacts** — regenerated every sync, never hand-edited. Wire
 `packages/tokens/package.json` to export them so the UI package, Storybook, and
 any future app consume them.
 
+**Install the native token toolkit — all four files, as a set.** Copy
+`.throughline/scripts/validate-token-output.mjs` into
+`packages/tokens/scripts/`, and
+`.throughline/scripts/lib/dtcg.mjs`,
+`.throughline/scripts/lib/native-literal.mjs`, and
+`.throughline/scripts/lib/sd-native.mjs` into
+`packages/tokens/scripts/lib/`. `sd-native.mjs` and the validator both import
+`dtcg.mjs` and `native-literal.mjs`, so copying any of them without the others
+breaks at import. Then register the gate so it stays live on every future sync:
+
+```json
+"tokens:validate-output": "node scripts/validate-token-output.mjs --min-match 1"
+```
+
+Invoke it once per native output file, passing the same `--source` list that
+file's build used. `--min-match 1` is what makes it a gate: the flag defaults to
+`0.5`, so without it a 60% match rate exits `0`.
+
 ## Step 4.5 — Icon code sync (install check + custom SVGR)
 
 Icons reach code differently from tokens, so handle them here if the system has

package/adapters/generic/AGENTS.md

@@ -4,18 +4,18 @@ ThroughLine builds a design system end to end. Read the matching skill file for
 
 ## ThroughLine skills
 
-- `component-builder` — Build a foundational set of Figma components — buttons, inputs, cards, badges, chips, modals, and more — as properly structured components with variant matrices (types, sizes, states) and icon/component/content slots, bound to the design system's tokens and styles. → read `skills/component-builder/SKILL.md`.
+- `component-builder` — Build Figma components — buttons, inputs, cards, badges, chips, modals, and more — with variant matrices (types, sizes, states) and icon/component/content slots bound to the design system's tokens and styles. → read `skills/component-builder/SKILL.md`.
 - `component-pipeline` — Take a single new component from Figma to fully-built-and-storied code, end to end — build it in Figma, sync any new tokens it introduced, then build its code component and stories. → read `skills/component-pipeline/SKILL.md`.
-- `design-system-audit` — Measure a pre-existing design system before retrofitting it onto tokens — size the code-side color surface and inventory the existing Figma file with verified per-class reads, then compute how semantic the system already is so the retrofit is right-sized. → read `skills/design-system-audit/SKILL.md`.
+- `design-system-audit` — Measure a pre-existing design system before retrofitting it onto tokens, so the retrofit is right-sized. → read `skills/design-system-audit/SKILL.md`.
 - `figma-environment-setup` — Set up the local working folder and connect the agent to Figma so the design-system skills can read and write variables, styles, and components. → read `skills/figma-environment-setup/SKILL.md`.
-- `icon-system-builder` — Build an icon system in Figma — a dedicated "Icons" page populated with the user's chosen icon library (Lucide, Material, or custom SVGs) as well-named, scalable components — using the fastest, most-automated mechanism per library (for Lucide, batch-fetching the curated subset's official SVGs from the source repo and componentizing them hands-off; for Material, the official community file or importer plugin) rather than hand-generating icons or making the user copy components by hand. → read `skills/icon-system-builder/SKILL.md`.
-- `repository-builder` — Graduate the local design-system folder into a real monorepo — a pnpm + Turborepo workspace with packages for tokens and UI components and room for apps — and walk the user from a plain folder to local git to a GitHub remote with PRs and CI. → read `skills/repository-builder/SKILL.md`.
-- `retrofit-planner` — Orchestrate a full brownfield design-system retrofit end to end — audit, refine variables in place, rebind components, sync, capture a Chromatic baseline, retrofit the code with dual output, adopt existing documentation then fill gaps, then remove the old tokens only after a zero-reference grep — with a human confirmation gate between every phase. → read `skills/retrofit-planner/SKILL.md`.
-- `storybook-chromatic-builder` — Stand up Storybook in the monorepo, build code components matching the Figma design system (consuming the synced tokens and implementing the captured slot contracts), generate stories for every component, set up Chromatic for visual regression testing, and wire Code Connect when the user's Figma plan supports it. → read `skills/storybook-chromatic-builder/SKILL.md`.
-- `token-builder` — Build a two-tier (primitive + semantic) design token system as Figma variables — color ramps, spacing, type scale, radius, shadows — with light/dark or brand modes. → read `skills/token-builder/SKILL.md`.
-- `token-crosswalk-builder` — Build the brownfield token crosswalk — a persistent three-way map between each new token, the old Figma variable, and the old code identifier(s) — as crosswalk.json, then install the vetted validator/reverse-index scripts into the monorepo and wire the tokens:validate CI gate. → read `skills/token-crosswalk-builder/SKILL.md`.
-- `token-sheet-builder` — Build a beautiful, on-brand "Foundations" page in Figma that visually documents every variable collection and style — color ramps with swatches, the type scale, spacing, radius, shadows/elevations — with swatches live-bound to the actual variables where Figma allows. → read `skills/token-sheet-builder/SKILL.md`.
-- `token-sync-layer` — Sync Figma design variables into code-ready token files by extracting them to DTCG-format JSON, running them through Style Dictionary, and emitting framework-specific outputs via per-platform adapters (shadcn/Tailwind, MUI, vanilla CSS, iOS Swift, Android Kotlin, or custom). → read `skills/token-sync-layer/SKILL.md`.
+- `icon-system-builder` — Build an icon system in Figma — a dedicated "Icons" page of well-named, scalable icon components from Lucide, Tabler, Phosphor, Material, or custom SVGs. → read `skills/icon-system-builder/SKILL.md`.
+- `repository-builder` — Graduate the local design-system folder into a real monorepo — a pnpm + Turborepo workspace with packages for tokens and UI components — and walk the user from a plain folder to local git to a GitHub remote with PRs and CI. → read `skills/repository-builder/SKILL.md`.
+- `retrofit-planner` — Orchestrate a full brownfield design-system retrofit end to end — audit, refine, rebind, sync, baseline, code, docs, cleanup — with a human confirmation gate between every phase. → read `skills/retrofit-planner/SKILL.md`.
+- `storybook-chromatic-builder` — Stand up Storybook in the monorepo, build code components matching the Figma design system, generate stories for every component, set up Chromatic for visual regression testing, and wire Code Connect when the user's Figma plan supports it. → read `skills/storybook-chromatic-builder/SKILL.md`.
+- `token-builder` — Build a two-tier (primitive + semantic) design token system as Figma variables — color ramps, spacing, type scale, radius, shadows — with light/dark or brand modes, using one collection per category per tier. → read `skills/token-builder/SKILL.md`.
+- `token-crosswalk-builder` — Build the brownfield token crosswalk — a persistent three-way map between each new token, the old Figma variable, and the old code identifier(s) — then wire the tokens:validate CI gate. → read `skills/token-crosswalk-builder/SKILL.md`.
+- `token-sheet-builder` — Build an on-brand "Foundations" page in Figma that visually documents every variable collection and style — color ramps with swatches, the type scale, spacing, radius, shadows/elevations. → read `skills/token-sheet-builder/SKILL.md`.
+- `token-sync-layer` — Sync Figma design variables into code-ready token files via DTCG JSON and Style Dictionary, emitting framework-specific outputs (shadcn/Tailwind, MUI, vanilla CSS, iOS Swift, Android Kotlin, or custom), and set up the reusable "sync figma tokens" command. → read `skills/token-sync-layer/SKILL.md`.
 
 ## ThroughLine commands
 

package/adapters/generic/commands/document-component.md

@@ -8,17 +8,49 @@ Ask which component to document (e.g. "Button"), then:
    the `component-builder` skill's *Author the documentation record* step —
    ingest any existing docs first (brownfield), then infer → enrich (from
    `.throughline/references/component-doc-archetypes.md`) → specialize →
-   interview. The user approves the drafted record; `imported`/`user` blocks are
-   never overwritten.
+   interview. Authored prose follows
+   `.throughline/references/doc-writing-standard.md`. Set `updatedAt` to
+   today's date (ISO, `YYYY-MM-DD`) whenever the record is written or rewritten —
+   it is a projected field and the doc card's header renders it. Once the record is
+   written, run `node .throughline/scripts/docs-lint.mjs
+   design-system/docs/components/<Name>.doc.json` and fix its warnings. Do not
+   raise a separate confirmation for a warning on an `imported`/`user` block:
+   draft the rewrite and carry it into the approval gate below, shown as
+   before/after and labelled with the block's provenance, so one approval covers
+   the whole record. The user approves the drafted record before anything is
+   projected (Figma description, doc card, manifest). Blocks the user did not
+   clear keep their existing text; blocks the user did clear are stamped
+   `imported+user` so a later run neither re-asks nor rewrites them.
 2. **Project it.** Write `design-system/docs/components/<Name>.doc.json`, set the
-   Figma component `description`, enrich the doc card, and (if the repo/code side
-   exists) render MDX/JSDoc and run `docs:digest` per the
-   `storybook-chromatic-builder` render step.
-3. **Reconcile drift.** Run `docs:check`. For each drifted surface, offer a per-item
-   choice — **re-render** (canonical wins) or **pull-back** (fold the surface edit
-   into the record) — and land the result as a reviewable change. On a brownfield
-   component's first pass, adopt existing content (`provenance: imported`) rather
-   than overwriting it.
+   Figma component `description`, rebuild the doc card's `Usage` band with the
+   canonical builder (`.throughline/references/doc-card-builder.md` —
+   verify its returned summary and stamp `surfaces.docCard.{src,render,renderer}`
+   from it), and (if the repo/code side exists) render MDX/JSDoc and run
+   `docs:digest` per the `storybook-chromatic-builder` render step.
+3. **Reconcile drift.** Before trusting `docs:check`, confirm the repo's copy of
+   the doc scripts is current: compare `DOC_CARD_RENDERER_VERSION` in the repo's
+   `scripts/lib/doc-card-plan.mjs` against the same constant in
+   `.throughline/scripts/lib/doc-card-plan.mjs`. If the repo file is
+   missing, or its version is lower, `docs:check` is reading stale rules and its
+   "no drift" is meaningless — say so plainly, and offer to refresh the repo's
+   doc scripts from the plugin copy. Refresh the whole set and re-check the npm
+   registrations, both per **Documentation scripts — install as a set** in
+   `.throughline/scripts/README.md` — a refreshed file whose script was
+   never registered is the same failure in a new place. Run `docs:check` (with the
+   refreshed scripts, if any). For each drifted surface, offer a per-item
+   choice — **re-render** (canonical wins) or **pull-back**
+   (fold the surface edit into the record) — and land the result as a reviewable
+   change. On a brownfield component's first pass, adopt existing content
+   (`provenance: imported`) rather than overwriting it.
+   `docs:check` may also report `layout-upgrade-available` (informational, never
+   failing): the card's layout predates the current builder. Offer to re-render
+   the `Usage` band now — rebuild happens on this touch, never unprompted.
+4. **Close the flow.** Hand back in the four-beat guide voice from
+   `.throughline/references/guide-voice.md`: the outcome, what you set
+   aside and why, one recommended next step, and at most one light alternative.
+   Read existing state to name what is actually outstanding rather than guessing —
+   a component at `status: "draft"` with no code surface in `meta[name].doc.surfaces`
+   means the code side is deferred. Do not close with a grid of co-equal options.
 
 See `.throughline/references/component-doc-schema.md` for the record schema,
 fingerprint contract, and projection mapping. If a component was never built in

package/adapters/generic/skills/component-builder/SKILL.md

@@ -236,7 +236,9 @@ Read `.throughline/references/component-doc-schema.md` for the exact JSON
 schema, the fingerprint algorithm, and the projection contract.
 
 **Run the generation pipeline (each layer only fills what it legitimately knows;
-stamp `provenance` per block):**
+stamp `provenance` per block):** all authored prose follows
+`.throughline/references/doc-writing-standard.md` — its plain
+reference register, not this skill's guide voice.
 
 0. **Ingest existing docs — brownfield only, runs first.** If docs already exist
    for this component (code JSDoc/MDX/README, or a populated Figma component
@@ -255,32 +257,74 @@ stamp `provenance` per block):**
    accessibility idiom to the target framework (the same field you read for variant
    vocabulary). Provenance `framework`.
 4. **Interview for the non-inferable.** Ask the user for brand/product-specific
-   do's & don'ts and intent. Provenance `user`. **Show the whole drafted record and
-   get explicit approval before writing anything** — layers 1–4 only fill blocks the
-   ingest step did not, and an `imported`/`user` block is never overwritten.
+   do's & don'ts and intent. Provenance `user`. Write the draft to
+   `design-system/docs/components/<Name>.doc.json`, run
+   `node .throughline/scripts/docs-lint.mjs design-system/docs/components/<Name>.doc.json`,
+   and fix the warnings it raises. Do not raise a separate confirmation for
+   a warning on an `imported`/`user` block: draft the rewrite and carry it
+   into the approval gate below, shown as before/after and labelled with the
+   block's provenance. **Show the whole drafted record and get explicit
+   approval before projecting it anywhere** (Figma description, doc card,
+   manifest) — one approval covers the whole record. Blocks the user did not
+   clear keep their existing text; blocks the user did clear are stamped
+   `imported+user` so a later run neither re-asks nor rewrites them.
 
 **Write the record and project it:**
 
 - Write `design-system/docs/components/<Name>.doc.json` (JSON; required fields
   `name`, `summary`, `description`).
 - **Figma component description.** Set the component's native `description` field
-  (via `figma_set_description`) to a compact markdown rendering — summary,
-  when-to-use/not, do's/don'ts, and the a11y summary — and append a fingerprint
-  marker line `<!-- tl:doc <fp> -->` (this is the surface Dev Mode and Code Connect
-  read).
-- **Doc card body.** Extend the existing doc card (name/short-desc/status/date, per
-  `.throughline/references/figma-component-standards.md`) with a usage body:
-  when-to-use, do's/don'ts, an a11y line, and a variant/state legend — all
-  token-bound (no hardcoded hex/px). Add a metadata text node named
-  `Doc Fingerprint` holding `<fp>`.
+  (via `figma_set_description`) from this exact template — this is the surface
+  Dev Mode and Code Connect read, and it must be reproducible byte-for-byte by
+  any agent from the same record:
+
+  ```
+  <summary>
+
+  **When to use**
+  - <whenToUse[n]>
+
+  **When not to use**
+  - <whenNotToUse[n]>
+
+  **Do**
+  - <dos[n]>
+
+  **Don't**
+  - <donts[n]>
+
+  **Accessibility**
+  - <accessibility.keyboard[n]>
+  - <accessibility.notes[n]>
+
+  <!-- tl:doc <fp> -->
+  ```
+
+  Rules: every line is a record string **verbatim** — no re-wording, no added
+  connectives, no sentences that appear nowhere in the record. A block whose
+  source array is empty is omitted along with its bold label. The **Accessibility**
+  label is omitted only when both `accessibility.keyboard` and `accessibility.notes`
+  are empty; when one is empty its bullets are simply absent and the label stays.
+  Sections are separated by exactly one blank line, and the fingerprint marker is
+  always last.
+- **Doc card body.** Render the card's `Usage` band with the canonical builder
+  snippet in `.throughline/references/doc-card-builder.md` (via
+  `figma_execute` with an explicit `timeout`, one card per call): fill the
+  RECORD/CANONICAL_FP slots, resolve the nine required semantic variables and
+  the `Body/Default` text style per that file's call contract, run it, and
+  verify the returned summary (`rowsRendered`, `blocksCreated`, `cardWidth`) —
+  not a screenshot. The builder creates the `Doc Fingerprint` node itself and
+  is the only thing that may build the usage body — never hand-assemble it.
 - Compute `<fp>` as the canonical fingerprint defined in the schema reference
   (sha256 of the projected record without `provenance`, first 16 hex chars).
 
 **Update the manifest (fields this skill owns):** set
 `components.meta[<Name>].doc` to `{ path, fingerprint: <fp>, surfaces: {
 figmaDescription: { src: <fp>, render: <hash of the description text> }, docCard: {
-src: <fp>, render: <hash of the card body content> } } }`. The code surfaces
-(`storybookMdx`) are added later by `storybook-chromatic-builder`.
+src: <fp>, render: <summary.renderHash>, renderer: <summary.rendererVersion> } } }`
+— the docCard entry is stamped from the builder's returned summary, never by
+re-reading the card. The code surfaces (`storybookMdx`) are added later by
+`storybook-chromatic-builder`.
 
 Run the standard doc-card visual-validation + post-build audit
 (`.throughline/references/figma-component-standards.md`) after enriching

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

@@ -27,15 +27,16 @@ 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 from the
-plugin's `scripts/` — `build-docs-digest.mjs`, `docs-check.mjs`, and
-`lib/doc-record.mjs` — into the repo and register npm scripts):
-
-- `"docs:digest": "node scripts/build-docs-digest.mjs"`
-- `"docs:check": "node scripts/docs-check.mjs"`
+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`.
+`.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
@@ -159,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
@@ -234,8 +272,10 @@ the `figma_execute` scripting gotchas — `getNodeByIdAsync` and an explicit
   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).
@@ -296,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/adapters/generic/skills/token-crosswalk-builder/SKILL.md

@@ -65,6 +65,8 @@ Copy these from `.throughline/scripts/` into the user's repo **verbatim**
 (they are zero-dependency and version with the user's repo so their CI can run them):
 
 - `lib/crosswalk.mjs` → `packages/tokens/scripts/lib/crosswalk.mjs`
+- `lib/dtcg.mjs` → `packages/tokens/scripts/lib/dtcg.mjs` (required by
+  `validate-crosswalk.mjs` — copying the validator without it breaks the gate at import)
 - `validate-crosswalk.mjs` → `packages/tokens/scripts/validate-crosswalk.mjs`
 - `build-reverse-index.mjs` → `packages/tokens/scripts/build-reverse-index.mjs`
 - `guard-token-removal.mjs` → `packages/tokens/scripts/guard-token-removal.mjs`