@radicool/throughline 0.21.3 → 0.22.0

package/README.md

@@ -73,9 +73,9 @@ Everything above was created during a single working session and synced directly
 
 | | |
 |---|---|
-| **A supported agent** | Required — [Claude Code](https://docs.claude.com/en/docs/claude-code) (native plugin), or **Cursor**, **Codex**, or any **AGENTS.md**-aware agent via `npx @radicool/throughline@0.21.3 init`. |
+| **A supported agent** | Required — [Claude Code](https://docs.claude.com/en/docs/claude-code) (native plugin), or **Cursor**, **Codex**, or any **AGENTS.md**-aware agent via `npx @radicool/throughline@0.22.0 init`. |
 | **Figma** | Required, **desktop app** (the browser version causes connection errors). **Professional plan or higher recommended** — multi-mode variables (Light/Dark, brand themes) need it. |
-| **Figma access token** | Required — read/write your file. The setup skill walks you through it; your token stays yours and is never shared in chat. |
+| **Figma access token** | Optional — only for the few Figma calls the Desktop Bridge can't make, like reading a published library. Without it, you work through the bridge alone. The setup skill walks you through it; your token stays yours and is never shared in chat. |
 | **GitHub** (or similar) | Optional — only when you're ready to graduate to a real remote repo with PRs and CI. |
 
 ### What it runs on your machine
@@ -114,9 +114,9 @@ Update anytime with `/plugin marketplace update throughline-marketplace`.
 Run the installer in your project — it stamps in the skills, the reference docs, the scripts, and the Figma MCP config for your tool:
 
 ```
-npx @radicool/throughline@0.21.3 init --target=cursor    # → .cursor/rules + .cursor/mcp.json
-npx @radicool/throughline@0.21.3 init --target=codex      # → prompts/ + AGENTS.md index + codex-mcp.toml
-npx @radicool/throughline@0.21.3 init --target=generic    # → skills/ + AGENTS.md index
+npx @radicool/throughline@0.22.0 init --target=cursor    # → .cursor/rules + .cursor/mcp.json
+npx @radicool/throughline@0.22.0 init --target=codex      # → prompts/ + AGENTS.md index + codex-mcp.toml
+npx @radicool/throughline@0.22.0 init --target=generic    # → skills/ + AGENTS.md index
 ```
 
 It's safe to re-run (it merges `AGENTS.md` and `.cursor/mcp.json` non-destructively) and stages everything the skills read into `.throughline/`. Then open the `figma-environment-setup` skill/rule/prompt for your tool to begin. For Codex, add the printed `codex-mcp.toml` block to your Codex config to enable Figma access.
@@ -127,7 +127,7 @@ ThroughLine is more than a pile of skills — it's a small system designed to st
 
 **🛠 Twelve skills — the steps.** Each owns one stage of the journey, from connecting Figma to retrofitting an existing system to standing up CI. They're sequenced, and each knows its prerequisites.
 
-**📐 Ten reference docs — the constitution.** Shared standards every skill obeys: Figma component rules (auto-layout-on-everything, slot contracts, naming-as-contract, a required post-build audit), the brainstorm-before-build protocol, the sync-adapter specs, the manifest schema, coding-level adaptivity, the publishing flow, and the brownfield-retrofit discipline (read-before-assert, the safe migration sequence, the crosswalk contract). This is *why* two different runs produce the same structure — the rules live in one place, not scattered per skill.
+**📐 The reference docs — the constitution.** Shared standards every skill obeys: Figma component rules (auto-layout-on-everything, slot contracts, naming-as-contract, a required post-build audit), the brainstorm-before-build protocol, the sync-adapter specs, the manifest schema, coding-level adaptivity, the publishing flow, and the brownfield-retrofit discipline (read-before-assert, the safe migration sequence, the crosswalk contract). This is *why* two different runs produce the same structure — the rules live in one place, not scattered per skill.
 
 **🧭 An orchestration layer — the memory.** A `design-system.json` manifest in your project records exactly what's set up, with a versioned schema and immutability rules. Every skill reads it, tells you what it's about to do, and offers to run anything missing first. Run **`/design-system-status`** anytime for a plain-language picture of where you stand.
 
@@ -162,7 +162,7 @@ For the technically curious — how the machine actually runs.
 
 **Modes, within Figma's limits.** Light/Dark lives on the semantic collections; brand variants live on the primitive palette. Splitting the two axes across two collections keeps each one under Figma's 4-modes-per-collection cap on the Professional plan while still resolving correctly (`bg/default` → `{gray/50}` → the active brand's gray).
 
-**Model routing.** ThroughLine routes work by *cognition, not guesswork* — the expensive thinking on the best model, the mechanical doing on a cheap one. Setup runs on **Haiku** automatically to keep first-run costs low. Inside a skill, the deciding — a token architecture, a variant matrix, a slot contract — is planned once on the strongest tier, while the long mechanical part — placing Figma nodes, transcribing component code, running SVGR — runs on a cheap tier and self-verifies. You get the best model where it matters and a cheap one where it doesn't, without micromanaging it. The recommended mapping is **Haiku → Sonnet → Opus** for the `fast < balanced < deep` tiers, but nothing is hardcoded — the ladder resolves against whatever models your install actually has, and on hosts without subagents skills degrade cleanly to a single model. You can still steer the session yourself (`/model opus` for the heaviest authoring, back to `/model sonnet` after); nothing forces an expensive model on you.
+**Model routing.** ThroughLine routes work by *cognition, not guesswork* — the expensive thinking on the best model, the mechanical doing on a cheap one. Inside a skill, the deciding — a token architecture, a variant matrix, a slot contract — is planned once on the strongest tier, while the long mechanical part — placing Figma nodes, transcribing component code, running SVGR — runs on a cheap tier and self-verifies. You get the best model where it matters and a cheap one where it doesn't, without micromanaging it. The recommended mapping is **Haiku → Sonnet → Opus** for the `fast < balanced < deep` tiers, but nothing is hardcoded — the ladder resolves against whatever models your install actually has, and on hosts without subagents skills degrade cleanly to a single model. You can still steer the session yourself (`/model opus` for the heaviest authoring, back to `/model sonnet` after); nothing forces an expensive model on you.
 
 ## Who it's for
 
@@ -212,7 +212,7 @@ Future improvements and planned capabilities. Have a request? **[Open an issue](
 - **Deeper Code Connect coverage** — richer Figma-to-code mappings as more plans support it.
 - **Expanded component starters** — a larger foundational kit out of the box.
 - **Richer status & auditing** — more from `/design-system-status`, including drift detection between Figma and code.
-- **Built-in accessibility checks** — the color half is shipped. Eight semantic text-on-surface pairs are checked against WCAG AA's 4.5:1 when tokens are created in Figma, and derived again from the token source when they sync to code — in every mode, so a system that clears in light and fails in dark fails. A failing pair stops the build rather than warning. Components are checked too: on web frameworks, a Figma build stops when a focus state has no visible ring, and in JSX code the adherence gate fails an icon-only button with no accessible name and a status badge that relies on color alone. Still ahead: focus-ring contrast (WCAG's 3:1 for non-text).
+- **Built-in accessibility checks** — the color half is shipped. Eight semantic text-on-surface pairs are checked against WCAG AA's 4.5:1 when tokens are created in Figma, and derived again from the token source when they sync to code — in every mode, so a system that clears in light and fails in dark fails. A failing pair stops the build rather than warning. Components are checked too: on web frameworks, a Figma build stops when a focus state has no visible ring, and in JSX code the adherence gate is built to fail an icon-only button with no accessible name and a status badge that relies on color alone — proven by unit tests. The one real app it has run on had almost nothing for it to check, so it hasn't caught a bug in the wild yet. Still ahead: focus-ring contrast (WCAG's 3:1 for non-text).
 - **Token fan-out to more platforms** — the DTCG token source is platform-neutral, and web targets are in daily use. Every target is **validated per build, not assumed**: `tokens:validate-output` checks generated output against its source, native Swift and Kotlin as well as web CSS, because the stock transforms have been measured emitting wrong-but-compiling values. iOS/Swift is a curated adapter whose Style Dictionary configuration ships as tested code, and Android/Kotlin uses the same configuration through the Tier 2 protocol. JavaScript theme output (MUI, a Tailwind v3 config) isn't checked yet.
 - **Native component code generation** — producing a SwiftUI view or a Compose composable the way Storybook components are produced for React. This does not exist yet; it is a separate, larger effort than token fan-out, and the two were previously described as one roadmap item.
 

package/adapters/codex/prompts/component-builder.md

@@ -8,7 +8,7 @@ translate cleanly to code later.
 
 Needs tokens (`tokens.semanticBuilt` true) — offer to run `token-builder` if
 missing. Needs a live Figma connection (offer `figma-environment-setup` if not).
-Use the mechanism in `figma.mechanism`.
+The plugin writes to Figma through Console MCP. If `figma.mechanism` holds anything other than `console-mcp`, say that value is no longer supported and offer `figma-environment-setup` to reset it.
 
 **Before scripting any `figma_execute`, read
 `.throughline/references/figma-scripting.md`** — the single-bridge-instance
@@ -67,8 +67,9 @@ inconsistent output:
 - **Sizes** (sm, md, lg). Each size is its **own variant row**, not a state — see
   the layout law below.
 - **States** — **include the full relevant set, don't trim it.** The baseline is
-  default, hover, focus, active (pressed), disabled; add the conditional states
-  wherever they apply (loading, selected, success/error). Decide which conditional
+  the set `.throughline/references/state-baseline.md` owes that component
+  (default included); add the conditional states wherever they apply (loading,
+  success/error). Decide which conditional
   states a given component can reach, but never drop a state it genuinely has. See
   "State handling" in `.throughline/references/figma-component-standards.md`
   for the per-component checklist.
@@ -400,9 +401,9 @@ Offer next steps: build the code counterparts and stories
   auto-layout grid where **variants are rows and states are columns**: one row per
   variant (each `type`, and each `size`, since size is a variant) stepping through
   states across the columns, size groups stacked vertically (see the standards doc).
-- Never ship a component with only its `default` state — include the full relevant
-  state set (default/hover/focus/active/disabled plus applicable
-  loading/selected/success/error).
+- Never ship a component with only its `default` state — include every state
+  `.throughline/references/state-baseline.md` owes that component, plus
+  `default`, plus any applicable loading/success/error.
 - Never run the component header and the component area together with no division —
   every doc card segments the header from the component area with a divider line or
   a distinct header surface.

package/adapters/codex/prompts/design-system-audit.md

@@ -22,7 +22,9 @@ across levels.
 
 Read the manifest. This skill needs Figma connected (`figma.connected: true`) for the
 inventory step, and a repo path for the code-surface step (`workspace.localPath`). If
-Figma isn't connected, offer to run `figma-environment-setup` first. The code-surface
+Figma isn't connected, offer to run `figma-environment-setup` first. Before the
+inventory, do a cheap liveness read to confirm the connection is actually live right
+now; if it fails, offer `figma-environment-setup`. The code-surface
 step works on any repo regardless of `workspace.stage`.
 
 ## Step 1 — Size the code surface

package/adapters/codex/prompts/figma-environment-setup.md

@@ -9,8 +9,10 @@ This skill does three foundational jobs, in order:
 3. **Connect Codex to Figma** so later skills can read and write the file,
    then verify the connection works.
 
-It is the required first step. Every other Figma skill does a cheap liveness
-check and, if it fails, points the user back here.
+It is the required first step. Every other skill that calls Figma itself does a
+cheap liveness check and, if it fails, points the user back here. (The orchestrators
+`component-pipeline` and `retrofit-planner` call Figma only through the skills they
+invoke, and `token-crosswalk-builder` works from the manifest and token files.)
 
 ## Who you're talking to
 
@@ -223,28 +225,23 @@ Make clear it changes only how much detail they get, never what they can build.
 This is set now because it colors every later interaction. The Figma phase
 itself doesn't lean on it much, but the code phase (repo, sync, Storybook) does.
 
-## Step 3 — Choose the Figma write mechanism
+## Step 3 — Figma write mechanism
 
-Explain there are two ways to connect Codex to Figma, and recommend the first:
+ThroughLine connects to Figma through the **Figma Console MCP**. It can create
+many variables at once efficiently (which saves time and usage), and it can read
+your variables on any Figma plan, including free and Pro. The setup is light:
+you'll run a small helper plugin inside Figma, and can optionally create one
+access token.
 
-- **Figma Console MCP (recommended).** More capable — it can create many
-  variables at once efficiently (which saves time and usage), and it can read
-  your variables on any Figma plan, including free and Pro. Slightly more setup:
-  you'll create one access token and run a small helper plugin inside Figma.
-- **Official Figma plugin (simpler fallback).** Less setup, but more limited —
-  some bulk operations are slower, and reading variables through it can be
-  restricted on non-Enterprise plans. Fine if the user wants the lightest path.
-
-Let the user choose. Record their choice in `figma.mechanism`
-(`"console-mcp"` or `"official-plugin"`). Default to `console-mcp` if they have
-no preference.
+Record `figma.mechanism` as `"console-mcp"`. There is nothing for the user to
+choose.
 
 The MCP server configuration ships **bundled with this plugin** (in the plugin's
 `.mcp.json`), so the user does not hand-edit any config files. The one thing the
 bundle can't contain is their personal access token — that's a per-user secret,
 handled in the next step.
 
-## Step 4 — Connect to Figma (Console MCP path)
+## Step 4 — Connect to Figma
 
 Walk through these one at a time, confirming each before moving on. Never rush
 the user past a step.
@@ -257,10 +254,16 @@ browser version of Figma causes connection and token errors that are painful to
 debug. If they don't have the desktop app, point them to figma.com/downloads to
 install it first. Desktop app, every time.
 
-### 4b. Create a Figma access token
+### 4b. Create a Figma access token (optional)
+
+A token is like a password that lets Codex talk to Figma on your behalf. It's
+**optional**: the desktop bridge does the reading and writing on its own. The
+token only adds the few calls the bridge can't make, such as reading a published
+library or a file's version history. Offer it, and say plainly that they can skip
+it and add it later in **Configure options**. If they skip, record nothing about
+it, leave the field blank, and go straight to 4c. Nothing later in setup needs it.
 
-A token is like a password that lets Codex talk to Figma on your behalf. Walk
-them through it:
+If they want it, walk them through it:
 
 1. In a browser, go to figma.com and sign in (same account as the desktop app).
 2. Click your account menu, then Settings.
@@ -309,14 +312,6 @@ Codex and Figma are linked for this session."
 If the config was just added (token placed for the first time), the MCP client
 may need a restart to load it. Tell them how, simply, and confirm they're back.
 
-## Step 4 (alt) — Connect to Figma (official plugin path)
-
-If the user chose the official plugin, the flow is lighter: install the official
-Figma plugin for Codex per its setup, ensure the desktop app is open with
-the file, and authenticate through the desktop app (again: desktop, not
-browser). The same secret-handling rule applies — any token goes into config by
-the user, never through the chat.
-
 ## Step 5 — Capture the file key
 
 Ask the user for the URL of the Figma file they want to build the design system
@@ -384,7 +379,7 @@ tokens or pairing here is useless. Diagnose in order:
 
 **B. The server started but the connection failed.** If there's no launch error
 and the server is clearly running, diagnose gently and in order: Is the desktop
-app open with the file? Was the token placed correctly (have them re-check,
+app open with the file? If they added a token, was it placed correctly (have them re-check,
 without showing you the value)? Is the bridge plugin running and paired? Did the
 client need a restart? Walk them back through the relevant sub-step.
 
@@ -400,7 +395,8 @@ neutral placeholder built against nothing.
 
 - Create one trivial throwaway node (e.g. a small frame or text node named
   `__throughline write test`) on any page.
-- Confirm it landed with a quick read or `figma_capture_screenshot`.
+- Confirm it landed with a quick read or `figma_capture_screenshot`. Neither needs
+  a token.
 - **Delete it.** If both the write and the delete succeed, writes are proven.
 
 Leave `figma.coverPageBuilt` = `false` here — that flag is set later, when the
@@ -445,7 +441,9 @@ restore point:
   `figma_get_file_versions`) or have the user name a Figma version so there's a known-good
   point to restore to. The plugin can read versions; it does not auto-create named
   versions, so if none exists, ask the user to add one ("File → Save to version
-  history") and record that you did.
+  history") and record that you did. If the user skipped the access token and
+  the version read fails, say in one sentence that you can't read version history
+  without it, and have them name the version themselves.
 - **Token export** — if the repo already emits tokens, snapshot the current generated
   output (git is the natural baseline once `workspace.stage` is `local-git`+).
 

package/adapters/codex/prompts/storybook-chromatic-builder.md

@@ -16,6 +16,10 @@ This skill needs:
 - Figma components (`components.built`) with their slot contracts, so stories
   reflect the real component APIs.
 
+The Figma-touching steps (Code Connect in Step 5, the doc-card write-back in Step 6)
+also need a live Figma connection — do a cheap liveness read before the first Figma
+call; if it fails, offer `figma-environment-setup`.
+
 Strongly recommend `github` stage so Chromatic's CI integration works; it can be
 set up locally first and wired to CI when the remote exists.
 

package/adapters/codex/prompts/token-builder.md

@@ -35,7 +35,7 @@ now. If it isn't, say so plainly and offer to run the `figma-environment-setup`
 skill first: "Figma isn't connected yet — want me to set that up? It's a
 one-time thing." Don't proceed until Figma is reachable.
 
-Use the write mechanism recorded in `figma.mechanism` (default `console-mcp`).
+The plugin writes to Figma through Console MCP. If `figma.mechanism` holds anything other than `console-mcp`, say that value is no longer supported and offer `figma-environment-setup` to reset it.
 With Console MCP, prefer `figma_execute` to create variables in scripted loops
 rather than one tool call per variable — this is dramatically more
 token-efficient for the potentially hundreds of primitives across modes.

package/adapters/codex/prompts/token-sheet-builder.md

@@ -24,7 +24,7 @@ a sensible companion step — the sheet and the synced code both reflect Figma.)
 
 Needs tokens in Figma (`tokens.semanticBuilt` true) and a live Figma connection.
 If tokens don't exist, offer to run `token-builder`. If Figma isn't connected,
-offer `figma-environment-setup`. Use the mechanism in `figma.mechanism`.
+offer `figma-environment-setup`. The plugin writes to Figma through Console MCP. If `figma.mechanism` holds anything other than `console-mcp`, say that value is no longer supported and offer `figma-environment-setup` to reset it.
 
 **Before scripting any `figma_execute`, read
 `.throughline/references/figma-scripting.md`.** This sheet builds large

package/adapters/codex/prompts/token-sync-layer.md

@@ -66,8 +66,8 @@ it.
 
 ## Step 2 — Extract Figma variables to DTCG JSON
 
-Using the active write mechanism (`figma.mechanism`, default Console MCP —
-prefer its full-design-system extraction, which works on any Figma plan), read
+The plugin talks to Figma through Console MCP. If `figma.mechanism` holds anything other than `console-mcp`, say that value is no longer supported and offer `figma-environment-setup` to reset it. Using Console MCP's
+full-design-system extraction (which works on any Figma plan), read
 **every variable collection** (there are now several per tier, e.g.
 `_Color/Primitive`, `Spacing/Primitive`, `Color/Semantic`, …) and normalize them
 into **DTCG-format JSON** (`$value`, `$type`, with semantic tokens expressed as
@@ -140,7 +140,10 @@ fit in the adapter output.
 
 ## Step 3 — Set up Style Dictionary + adapters
 
-Install and configure Style Dictionary v4 in `packages/tokens/`. For each chosen
+Install Style Dictionary pinned to an exact version with
+`pnpm add -D style-dictionary@4.4.0` (or the project's package manager) in
+`packages/tokens/`; the generated config is verified against 4.4.0, and a newer
+release can rename or add stock transforms. Then configure it. For each chosen
 platform, apply its adapter preset (per `.throughline/references/sync-adapters.md`):
 register the platform, transform group, format, and `outputReferences`
 (true for web → preserves the semantic→primitive cascade; false for native →

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

@@ -12,7 +12,7 @@ translate cleanly to code later.
 
 Needs tokens (`tokens.semanticBuilt` true) — offer to run `token-builder` if
 missing. Needs a live Figma connection (offer `figma-environment-setup` if not).
-Use the mechanism in `figma.mechanism`.
+The plugin writes to Figma through Console MCP. If `figma.mechanism` holds anything other than `console-mcp`, say that value is no longer supported and offer `figma-environment-setup` to reset it.
 
 **Before scripting any `figma_execute`, read
 `.throughline/references/figma-scripting.md`** — the single-bridge-instance
@@ -71,8 +71,9 @@ inconsistent output:
 - **Sizes** (sm, md, lg). Each size is its **own variant row**, not a state — see
   the layout law below.
 - **States** — **include the full relevant set, don't trim it.** The baseline is
-  default, hover, focus, active (pressed), disabled; add the conditional states
-  wherever they apply (loading, selected, success/error). Decide which conditional
+  the set `.throughline/references/state-baseline.md` owes that component
+  (default included); add the conditional states wherever they apply (loading,
+  success/error). Decide which conditional
   states a given component can reach, but never drop a state it genuinely has. See
   "State handling" in `.throughline/references/figma-component-standards.md`
   for the per-component checklist.
@@ -404,9 +405,9 @@ Offer next steps: build the code counterparts and stories
   auto-layout grid where **variants are rows and states are columns**: one row per
   variant (each `type`, and each `size`, since size is a variant) stepping through
   states across the columns, size groups stacked vertically (see the standards doc).
-- Never ship a component with only its `default` state — include the full relevant
-  state set (default/hover/focus/active/disabled plus applicable
-  loading/selected/success/error).
+- Never ship a component with only its `default` state — include every state
+  `.throughline/references/state-baseline.md` owes that component, plus
+  `default`, plus any applicable loading/success/error.
 - Never run the component header and the component area together with no division —
   every doc card segments the header from the component area with a divider line or
   a distinct header surface.

package/adapters/cursor/.cursor/rules/design-system-audit.mdc

@@ -26,7 +26,9 @@ across levels.
 
 Read the manifest. This skill needs Figma connected (`figma.connected: true`) for the
 inventory step, and a repo path for the code-surface step (`workspace.localPath`). If
-Figma isn't connected, offer to run `figma-environment-setup` first. The code-surface
+Figma isn't connected, offer to run `figma-environment-setup` first. Before the
+inventory, do a cheap liveness read to confirm the connection is actually live right
+now; if it fails, offer `figma-environment-setup`. The code-surface
 step works on any repo regardless of `workspace.stage`.
 
 ## Step 1 — Size the code surface

package/adapters/cursor/.cursor/rules/figma-environment-setup.mdc

@@ -13,8 +13,10 @@ This skill does three foundational jobs, in order:
 3. **Connect Cursor to Figma** so later skills can read and write the file,
    then verify the connection works.
 
-It is the required first step. Every other Figma skill does a cheap liveness
-check and, if it fails, points the user back here.
+It is the required first step. Every other skill that calls Figma itself does a
+cheap liveness check and, if it fails, points the user back here. (The orchestrators
+`component-pipeline` and `retrofit-planner` call Figma only through the skills they
+invoke, and `token-crosswalk-builder` works from the manifest and token files.)
 
 ## Who you're talking to
 
@@ -227,28 +229,23 @@ Make clear it changes only how much detail they get, never what they can build.
 This is set now because it colors every later interaction. The Figma phase
 itself doesn't lean on it much, but the code phase (repo, sync, Storybook) does.
 
-## Step 3 — Choose the Figma write mechanism
+## Step 3 — Figma write mechanism
 
-Explain there are two ways to connect Cursor to Figma, and recommend the first:
+ThroughLine connects to Figma through the **Figma Console MCP**. It can create
+many variables at once efficiently (which saves time and usage), and it can read
+your variables on any Figma plan, including free and Pro. The setup is light:
+you'll run a small helper plugin inside Figma, and can optionally create one
+access token.
 
-- **Figma Console MCP (recommended).** More capable — it can create many
-  variables at once efficiently (which saves time and usage), and it can read
-  your variables on any Figma plan, including free and Pro. Slightly more setup:
-  you'll create one access token and run a small helper plugin inside Figma.
-- **Official Figma plugin (simpler fallback).** Less setup, but more limited —
-  some bulk operations are slower, and reading variables through it can be
-  restricted on non-Enterprise plans. Fine if the user wants the lightest path.
-
-Let the user choose. Record their choice in `figma.mechanism`
-(`"console-mcp"` or `"official-plugin"`). Default to `console-mcp` if they have
-no preference.
+Record `figma.mechanism` as `"console-mcp"`. There is nothing for the user to
+choose.
 
 The MCP server configuration ships **bundled with this plugin** (in the plugin's
 `.mcp.json`), so the user does not hand-edit any config files. The one thing the
 bundle can't contain is their personal access token — that's a per-user secret,
 handled in the next step.
 
-## Step 4 — Connect to Figma (Console MCP path)
+## Step 4 — Connect to Figma
 
 Walk through these one at a time, confirming each before moving on. Never rush
 the user past a step.
@@ -261,10 +258,16 @@ browser version of Figma causes connection and token errors that are painful to
 debug. If they don't have the desktop app, point them to figma.com/downloads to
 install it first. Desktop app, every time.
 
-### 4b. Create a Figma access token
+### 4b. Create a Figma access token (optional)
+
+A token is like a password that lets Cursor talk to Figma on your behalf. It's
+**optional**: the desktop bridge does the reading and writing on its own. The
+token only adds the few calls the bridge can't make, such as reading a published
+library or a file's version history. Offer it, and say plainly that they can skip
+it and add it later in **Configure options**. If they skip, record nothing about
+it, leave the field blank, and go straight to 4c. Nothing later in setup needs it.
 
-A token is like a password that lets Cursor talk to Figma on your behalf. Walk
-them through it:
+If they want it, walk them through it:
 
 1. In a browser, go to figma.com and sign in (same account as the desktop app).
 2. Click your account menu, then Settings.
@@ -313,14 +316,6 @@ Cursor and Figma are linked for this session."
 If the config was just added (token placed for the first time), the MCP client
 may need a restart to load it. Tell them how, simply, and confirm they're back.
 
-## Step 4 (alt) — Connect to Figma (official plugin path)
-
-If the user chose the official plugin, the flow is lighter: install the official
-Figma plugin for Cursor per its setup, ensure the desktop app is open with
-the file, and authenticate through the desktop app (again: desktop, not
-browser). The same secret-handling rule applies — any token goes into config by
-the user, never through the chat.
-
 ## Step 5 — Capture the file key
 
 Ask the user for the URL of the Figma file they want to build the design system
@@ -388,7 +383,7 @@ tokens or pairing here is useless. Diagnose in order:
 
 **B. The server started but the connection failed.** If there's no launch error
 and the server is clearly running, diagnose gently and in order: Is the desktop
-app open with the file? Was the token placed correctly (have them re-check,
+app open with the file? If they added a token, was it placed correctly (have them re-check,
 without showing you the value)? Is the bridge plugin running and paired? Did the
 client need a restart? Walk them back through the relevant sub-step.
 
@@ -404,7 +399,8 @@ neutral placeholder built against nothing.
 
 - Create one trivial throwaway node (e.g. a small frame or text node named
   `__throughline write test`) on any page.
-- Confirm it landed with a quick read or `figma_capture_screenshot`.
+- Confirm it landed with a quick read or `figma_capture_screenshot`. Neither needs
+  a token.
 - **Delete it.** If both the write and the delete succeed, writes are proven.
 
 Leave `figma.coverPageBuilt` = `false` here — that flag is set later, when the
@@ -449,7 +445,9 @@ restore point:
   `figma_get_file_versions`) or have the user name a Figma version so there's a known-good
   point to restore to. The plugin can read versions; it does not auto-create named
   versions, so if none exists, ask the user to add one ("File → Save to version
-  history") and record that you did.
+  history") and record that you did. If the user skipped the access token and
+  the version read fails, say in one sentence that you can't read version history
+  without it, and have them name the version themselves.
 - **Token export** — if the repo already emits tokens, snapshot the current generated
   output (git is the natural baseline once `workspace.stage` is `local-git`+).
 

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

@@ -20,6 +20,10 @@ This skill needs:
 - Figma components (`components.built`) with their slot contracts, so stories
   reflect the real component APIs.
 
+The Figma-touching steps (Code Connect in Step 5, the doc-card write-back in Step 6)
+also need a live Figma connection — do a cheap liveness read before the first Figma
+call; if it fails, offer `figma-environment-setup`.
+
 Strongly recommend `github` stage so Chromatic's CI integration works; it can be
 set up locally first and wired to CI when the remote exists.
 

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

@@ -39,7 +39,7 @@ now. If it isn't, say so plainly and offer to run the `figma-environment-setup`
 skill first: "Figma isn't connected yet — want me to set that up? It's a
 one-time thing." Don't proceed until Figma is reachable.
 
-Use the write mechanism recorded in `figma.mechanism` (default `console-mcp`).
+The plugin writes to Figma through Console MCP. If `figma.mechanism` holds anything other than `console-mcp`, say that value is no longer supported and offer `figma-environment-setup` to reset it.
 With Console MCP, prefer `figma_execute` to create variables in scripted loops
 rather than one tool call per variable — this is dramatically more
 token-efficient for the potentially hundreds of primitives across modes.

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

@@ -28,7 +28,7 @@ a sensible companion step — the sheet and the synced code both reflect Figma.)
 
 Needs tokens in Figma (`tokens.semanticBuilt` true) and a live Figma connection.
 If tokens don't exist, offer to run `token-builder`. If Figma isn't connected,
-offer `figma-environment-setup`. Use the mechanism in `figma.mechanism`.
+offer `figma-environment-setup`. The plugin writes to Figma through Console MCP. If `figma.mechanism` holds anything other than `console-mcp`, say that value is no longer supported and offer `figma-environment-setup` to reset it.
 
 **Before scripting any `figma_execute`, read
 `.throughline/references/figma-scripting.md`.** This sheet builds large

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

@@ -70,8 +70,8 @@ it.
 
 ## Step 2 — Extract Figma variables to DTCG JSON
 
-Using the active write mechanism (`figma.mechanism`, default Console MCP —
-prefer its full-design-system extraction, which works on any Figma plan), read
+The plugin talks to Figma through Console MCP. If `figma.mechanism` holds anything other than `console-mcp`, say that value is no longer supported and offer `figma-environment-setup` to reset it. Using Console MCP's
+full-design-system extraction (which works on any Figma plan), read
 **every variable collection** (there are now several per tier, e.g.
 `_Color/Primitive`, `Spacing/Primitive`, `Color/Semantic`, …) and normalize them
 into **DTCG-format JSON** (`$value`, `$type`, with semantic tokens expressed as
@@ -144,7 +144,10 @@ fit in the adapter output.
 
 ## Step 3 — Set up Style Dictionary + adapters
 
-Install and configure Style Dictionary v4 in `packages/tokens/`. For each chosen
+Install Style Dictionary pinned to an exact version with
+`pnpm add -D style-dictionary@4.4.0` (or the project's package manager) in
+`packages/tokens/`; the generated config is verified against 4.4.0, and a newer
+release can rename or add stock transforms. Then configure it. For each chosen
 platform, apply its adapter preset (per `.throughline/references/sync-adapters.md`):
 register the platform, transform group, format, and `outputReferences`
 (true for web → preserves the semantic→primitive cascade; false for native →

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

@@ -8,7 +8,7 @@ translate cleanly to code later.
 
 Needs tokens (`tokens.semanticBuilt` true) — offer to run `token-builder` if
 missing. Needs a live Figma connection (offer `figma-environment-setup` if not).
-Use the mechanism in `figma.mechanism`.
+The plugin writes to Figma through Console MCP. If `figma.mechanism` holds anything other than `console-mcp`, say that value is no longer supported and offer `figma-environment-setup` to reset it.
 
 **Before scripting any `figma_execute`, read
 `.throughline/references/figma-scripting.md`** — the single-bridge-instance
@@ -67,8 +67,9 @@ inconsistent output:
 - **Sizes** (sm, md, lg). Each size is its **own variant row**, not a state — see
   the layout law below.
 - **States** — **include the full relevant set, don't trim it.** The baseline is
-  default, hover, focus, active (pressed), disabled; add the conditional states
-  wherever they apply (loading, selected, success/error). Decide which conditional
+  the set `.throughline/references/state-baseline.md` owes that component
+  (default included); add the conditional states wherever they apply (loading,
+  success/error). Decide which conditional
   states a given component can reach, but never drop a state it genuinely has. See
   "State handling" in `.throughline/references/figma-component-standards.md`
   for the per-component checklist.
@@ -400,9 +401,9 @@ Offer next steps: build the code counterparts and stories
   auto-layout grid where **variants are rows and states are columns**: one row per
   variant (each `type`, and each `size`, since size is a variant) stepping through
   states across the columns, size groups stacked vertically (see the standards doc).
-- Never ship a component with only its `default` state — include the full relevant
-  state set (default/hover/focus/active/disabled plus applicable
-  loading/selected/success/error).
+- Never ship a component with only its `default` state — include every state
+  `.throughline/references/state-baseline.md` owes that component, plus
+  `default`, plus any applicable loading/success/error.
 - Never run the component header and the component area together with no division —
   every doc card segments the header from the component area with a divider line or
   a distinct header surface.

package/adapters/generic/skills/design-system-audit/SKILL.md

@@ -22,7 +22,9 @@ across levels.
 
 Read the manifest. This skill needs Figma connected (`figma.connected: true`) for the
 inventory step, and a repo path for the code-surface step (`workspace.localPath`). If
-Figma isn't connected, offer to run `figma-environment-setup` first. The code-surface
+Figma isn't connected, offer to run `figma-environment-setup` first. Before the
+inventory, do a cheap liveness read to confirm the connection is actually live right
+now; if it fails, offer `figma-environment-setup`. The code-surface
 step works on any repo regardless of `workspace.stage`.
 
 ## Step 1 — Size the code surface

package/adapters/generic/skills/figma-environment-setup/SKILL.md

@@ -9,8 +9,10 @@ This skill does three foundational jobs, in order:
 3. **Connect the agent to Figma** so later skills can read and write the file,
    then verify the connection works.
 
-It is the required first step. Every other Figma skill does a cheap liveness
-check and, if it fails, points the user back here.
+It is the required first step. Every other skill that calls Figma itself does a
+cheap liveness check and, if it fails, points the user back here. (The orchestrators
+`component-pipeline` and `retrofit-planner` call Figma only through the skills they
+invoke, and `token-crosswalk-builder` works from the manifest and token files.)
 
 ## Who you're talking to
 
@@ -223,28 +225,23 @@ Make clear it changes only how much detail they get, never what they can build.
 This is set now because it colors every later interaction. The Figma phase
 itself doesn't lean on it much, but the code phase (repo, sync, Storybook) does.
 
-## Step 3 — Choose the Figma write mechanism
+## Step 3 — Figma write mechanism
 
-Explain there are two ways to connect the agent to Figma, and recommend the first:
+ThroughLine connects to Figma through the **Figma Console MCP**. It can create
+many variables at once efficiently (which saves time and usage), and it can read
+your variables on any Figma plan, including free and Pro. The setup is light:
+you'll run a small helper plugin inside Figma, and can optionally create one
+access token.
 
-- **Figma Console MCP (recommended).** More capable — it can create many
-  variables at once efficiently (which saves time and usage), and it can read
-  your variables on any Figma plan, including free and Pro. Slightly more setup:
-  you'll create one access token and run a small helper plugin inside Figma.
-- **Official Figma plugin (simpler fallback).** Less setup, but more limited —
-  some bulk operations are slower, and reading variables through it can be
-  restricted on non-Enterprise plans. Fine if the user wants the lightest path.
-
-Let the user choose. Record their choice in `figma.mechanism`
-(`"console-mcp"` or `"official-plugin"`). Default to `console-mcp` if they have
-no preference.
+Record `figma.mechanism` as `"console-mcp"`. There is nothing for the user to
+choose.
 
 The MCP server configuration ships **bundled with this plugin** (in the plugin's
 `.mcp.json`), so the user does not hand-edit any config files. The one thing the
 bundle can't contain is their personal access token — that's a per-user secret,
 handled in the next step.
 
-## Step 4 — Connect to Figma (Console MCP path)
+## Step 4 — Connect to Figma
 
 Walk through these one at a time, confirming each before moving on. Never rush
 the user past a step.
@@ -257,10 +254,16 @@ browser version of Figma causes connection and token errors that are painful to
 debug. If they don't have the desktop app, point them to figma.com/downloads to
 install it first. Desktop app, every time.
 
-### 4b. Create a Figma access token
+### 4b. Create a Figma access token (optional)
+
+A token is like a password that lets the agent talk to Figma on your behalf. It's
+**optional**: the desktop bridge does the reading and writing on its own. The
+token only adds the few calls the bridge can't make, such as reading a published
+library or a file's version history. Offer it, and say plainly that they can skip
+it and add it later in **Configure options**. If they skip, record nothing about
+it, leave the field blank, and go straight to 4c. Nothing later in setup needs it.
 
-A token is like a password that lets the agent talk to Figma on your behalf. Walk
-them through it:
+If they want it, walk them through it:
 
 1. In a browser, go to figma.com and sign in (same account as the desktop app).
 2. Click your account menu, then Settings.
@@ -309,14 +312,6 @@ the agent and Figma are linked for this session."
 If the config was just added (token placed for the first time), the MCP client
 may need a restart to load it. Tell them how, simply, and confirm they're back.
 
-## Step 4 (alt) — Connect to Figma (official plugin path)
-
-If the user chose the official plugin, the flow is lighter: install the official
-Figma plugin for your coding agent per its setup, ensure the desktop app is open with
-the file, and authenticate through the desktop app (again: desktop, not
-browser). The same secret-handling rule applies — any token goes into config by
-the user, never through the chat.
-
 ## Step 5 — Capture the file key
 
 Ask the user for the URL of the Figma file they want to build the design system
@@ -384,7 +379,7 @@ tokens or pairing here is useless. Diagnose in order:
 
 **B. The server started but the connection failed.** If there's no launch error
 and the server is clearly running, diagnose gently and in order: Is the desktop
-app open with the file? Was the token placed correctly (have them re-check,
+app open with the file? If they added a token, was it placed correctly (have them re-check,
 without showing you the value)? Is the bridge plugin running and paired? Did the
 client need a restart? Walk them back through the relevant sub-step.
 
@@ -400,7 +395,8 @@ neutral placeholder built against nothing.
 
 - Create one trivial throwaway node (e.g. a small frame or text node named
   `__throughline write test`) on any page.
-- Confirm it landed with a quick read or `figma_capture_screenshot`.
+- Confirm it landed with a quick read or `figma_capture_screenshot`. Neither needs
+  a token.
 - **Delete it.** If both the write and the delete succeed, writes are proven.
 
 Leave `figma.coverPageBuilt` = `false` here — that flag is set later, when the
@@ -445,7 +441,9 @@ restore point:
   `figma_get_file_versions`) or have the user name a Figma version so there's a known-good
   point to restore to. The plugin can read versions; it does not auto-create named
   versions, so if none exists, ask the user to add one ("File → Save to version
-  history") and record that you did.
+  history") and record that you did. If the user skipped the access token and
+  the version read fails, say in one sentence that you can't read version history
+  without it, and have them name the version themselves.
 - **Token export** — if the repo already emits tokens, snapshot the current generated
   output (git is the natural baseline once `workspace.stage` is `local-git`+).
 

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

@@ -16,6 +16,10 @@ This skill needs:
 - Figma components (`components.built`) with their slot contracts, so stories
   reflect the real component APIs.
 
+The Figma-touching steps (Code Connect in Step 5, the doc-card write-back in Step 6)
+also need a live Figma connection — do a cheap liveness read before the first Figma
+call; if it fails, offer `figma-environment-setup`.
+
 Strongly recommend `github` stage so Chromatic's CI integration works; it can be
 set up locally first and wired to CI when the remote exists.
 

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

@@ -35,7 +35,7 @@ now. If it isn't, say so plainly and offer to run the `figma-environment-setup`
 skill first: "Figma isn't connected yet — want me to set that up? It's a
 one-time thing." Don't proceed until Figma is reachable.
 
-Use the write mechanism recorded in `figma.mechanism` (default `console-mcp`).
+The plugin writes to Figma through Console MCP. If `figma.mechanism` holds anything other than `console-mcp`, say that value is no longer supported and offer `figma-environment-setup` to reset it.
 With Console MCP, prefer `figma_execute` to create variables in scripted loops
 rather than one tool call per variable — this is dramatically more
 token-efficient for the potentially hundreds of primitives across modes.

package/adapters/generic/skills/token-sheet-builder/SKILL.md

@@ -24,7 +24,7 @@ a sensible companion step — the sheet and the synced code both reflect Figma.)
 
 Needs tokens in Figma (`tokens.semanticBuilt` true) and a live Figma connection.
 If tokens don't exist, offer to run `token-builder`. If Figma isn't connected,
-offer `figma-environment-setup`. Use the mechanism in `figma.mechanism`.
+offer `figma-environment-setup`. The plugin writes to Figma through Console MCP. If `figma.mechanism` holds anything other than `console-mcp`, say that value is no longer supported and offer `figma-environment-setup` to reset it.
 
 **Before scripting any `figma_execute`, read
 `.throughline/references/figma-scripting.md`.** This sheet builds large

package/adapters/generic/skills/token-sync-layer/SKILL.md

@@ -66,8 +66,8 @@ it.
 
 ## Step 2 — Extract Figma variables to DTCG JSON
 
-Using the active write mechanism (`figma.mechanism`, default Console MCP —
-prefer its full-design-system extraction, which works on any Figma plan), read
+The plugin talks to Figma through Console MCP. If `figma.mechanism` holds anything other than `console-mcp`, say that value is no longer supported and offer `figma-environment-setup` to reset it. Using Console MCP's
+full-design-system extraction (which works on any Figma plan), read
 **every variable collection** (there are now several per tier, e.g.
 `_Color/Primitive`, `Spacing/Primitive`, `Color/Semantic`, …) and normalize them
 into **DTCG-format JSON** (`$value`, `$type`, with semantic tokens expressed as
@@ -140,7 +140,10 @@ fit in the adapter output.
 
 ## Step 3 — Set up Style Dictionary + adapters
 
-Install and configure Style Dictionary v4 in `packages/tokens/`. For each chosen
+Install Style Dictionary pinned to an exact version with
+`pnpm add -D style-dictionary@4.4.0` (or the project's package manager) in
+`packages/tokens/`; the generated config is verified against 4.4.0, and a newer
+release can rename or add stock transforms. Then configure it. For each chosen
 platform, apply its adapter preset (per `.throughline/references/sync-adapters.md`):
 register the platform, transform group, format, and `outputReferences`
 (true for web → preserves the semantic→primitive cascade; false for native →

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@radicool/throughline",
-  "version": "0.21.3",
+  "version": "0.22.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/figma-component-standards.md

@@ -123,19 +123,17 @@ run, and it mirrors how the states/types map to code props.
 
 - **Always include every relevant state for the component — completeness is the
   default, not a judgment call.** A component's `state` axis must enumerate its full
-  applicable interaction surface, not just `default`. The baseline interactive set
-  is **default, hover, focus, active (pressed), disabled**; add the **conditional**
-  states whenever they apply to that component: **loading** (anything that triggers
-  async work — buttons, submit inputs), **selected** (toggles, segmented controls,
-  list/menu items, chips), and **success / error** (validated inputs, form fields,
-  async-result buttons). Decide *which* conditional states apply, but never drop a
-  state that does apply to keep the matrix small.
-  - **Button:** default, hover, focus, active (pressed), disabled — plus loading
-    (and selected / success / error where the button supports them).
-  - **Input / text field:** default, hover, focus, disabled — plus error, success,
-    and (where async) loading.
-  - **Checkbox / radio / toggle / chip:** default, hover, focus, active, disabled —
-    plus selected (and indeterminate where it applies).
+  applicable interaction surface, not just `default`. The states a component owes
+  come from the table in `references/state-baseline.md` (see below); add the
+  **conditional** states whenever they apply to that component: **loading** (anything
+  that triggers async work — buttons, submit inputs), **selected** for components the
+  table does not cover (segmented controls, list/menu items), and **success / error**
+  (validated inputs, form fields, async-result buttons). Decide *which* conditional
+  states apply, but never drop a state that does apply to keep the matrix small.
+  - **Which components owe which states is one table**, shared with the CLI's
+    `state-incomplete` check: `references/state-baseline.md`, generated from
+    `scripts/lib/component-states.mjs`. Add loading, success / error, and
+    indeterminate where they apply; those are not in the table.
 - Keep these on a `state` variant axis where they change appearance meaningfully;
   each becomes a column in the set per "Component set arrangement".
 - Distinguish *component states* (part of the component's definition) from
@@ -557,8 +555,8 @@ For each generated artboard / doc card / icon grid, read the nodes back (via
    a header container whose surface fill differs from the component area (both
    token-bound). A card with no header/component segmentation is a fail.
 8. **States complete** — each component set's `state` axis includes every relevant
-   state for that component (default/hover/focus/active/disabled plus the applicable
-   conditional states — loading/selected/success/error), with variants (incl. each
+   state for that component (every state the table in `references/state-baseline.md`
+   owes it, plus default, plus the applicable loading/success/error), with variants (incl. each
    size) as rows and states as columns. A set shipping only `default` is a fail.
 9. **Focus state matches the library idiom** — the focus state is built as
    `project.uiFramework`'s real pattern (see "State handling"), not a house-style
@@ -581,10 +579,10 @@ For each generated artboard / doc card / icon grid, read the nodes back (via
      error: fix and re-audit like any other item. If the ring is still missing
      when the pass budget below runs out, **stop the build** rather than hand off.
    - **Scope.** It runs only for a component whose name folds (lowercase,
-     punctuation stripped) to a Button, an Input / text field, or a Checkbox /
-     radio / toggle / chip, the same exact-name match as the state check. A Switch
-     or a TextInput isn't in that list, so neither Figma check reads it (the CLI's
-     `state-incomplete` does). It also
+     punctuation stripped) to a name in the table in `references/state-baseline.md`
+     (not its exempt list), the same
+     exact-name match as the state check and the same list the CLI's
+     `state-incomplete` reads. It also
      needs `project.uiFramework` to be exactly `shadcn`, `tailwind`, `mui`,
      `vanilla-css` or `vanilla`, or absent or `null`. Anything else (`ios-swift`,
      a tier-2 library, any other value) is skipped, and the skip is said.

package/references/figma-scripting.md

@@ -68,7 +68,8 @@ wrong document.
 Run this before the first write, and again right before any replace — the
 build-verify-then-replace finalize deletes the existing node, so it is the write
 that destroys work in the wrong file. The `figma-executor` agent runs it as step 1
-of its contract. **When a skill builds inline instead** (a host with no subagent
+of its contract; the `architect` and `reviewer` agents, which read Figma but cannot
+navigate, run the compare and return `BLOCKED` on a mismatch. **When a skill builds inline instead** (a host with no subagent
 dispatch, or a write-back the skill does itself), nothing runs it for you: the
 skill has to.
 

package/references/manifest-schema.md

@@ -162,10 +162,12 @@ bailing or running silently.
   - `syncLayer` — `style-dictionary.config.js` or `*.style-dictionary.js` files present at the project root or within immediate subdirectories
 
 ### `figma`
-- `mechanism` — which write mechanism is active. One of `"console-mcp"`
-  (default, recommended) or `"official-plugin"` (lower-setup fallback). Set by
-  skill 0. The adapter layer in every Figma skill reads this to know which tool
-  names to use.
+- `mechanism` — which write mechanism is active. `"console-mcp"` is the only
+  supported value. Set by skill 0. The adapter layer in every Figma skill reads
+  this to know which tool names to use. A manifest written by an earlier version
+  may hold `"official-plugin"`; that value is unsupported (no agent or bundled
+  MCP server backs it), and re-running `figma-environment-setup` resets it to
+  `"console-mcp"`.
 - `fileKey` — the Figma file key the system writes into (extracted from the
   file URL). Lets skills target the right file without re-asking.
 - `connected` — whether setup completed successfully at least once. Note this is

package/references/state-baseline.md

@@ -0,0 +1,25 @@
+<!-- GENERATED by scripts/build-state-baseline.mjs from scripts/lib/component-states.mjs. Do not edit; run: node scripts/build-state-baseline.mjs -->
+# State baseline
+
+Which interaction states a component owes. This is the one list both checks read:
+`verify:check` (`state-incomplete`) reads it from `scripts/lib/component-states.mjs`,
+and `figma-executor` (its state check and the `focus-indicator` check) reads
+this table. CI fails when the table is stale.
+
+A component name matches a row when it folds (lowercase, punctuation and spaces
+stripped) to exactly one of that row's names. `Text Field` folds to `textfield`.
+Matching is exact on purpose: `IconButton` matches nothing, and a component that
+matches nothing owes no states.
+
+| Archetype | Names | States owed |
+|---|---|---|
+| button | `button` | `hover`, `focus`, `active`, `disabled` |
+| input | `input`, `textfield`, `textinput` | `hover`, `focus`, `disabled` |
+| choice | `checkbox`, `radio`, `toggle`, `switch`, `chip` | `hover`, `focus`, `active`, `selected`, `disabled` |
+
+Every state in the table must be a value on the component's `state` axis. On the
+Figma side the matrix also carries `default` as the resting state; the CLI does not
+count it. `checked` counts as `selected`, and `on` counts as `selected`, since that is what shadcn and Radix call it. Conditional states (`loading`, `error`, `success`) are not in the table:
+whether one applies is a design judgment.
+
+Names that fold to `card`, `modal`, `dialog`, `badge`, `tag` owe none, so neither check asserts states on them.

package/scripts/README.md

@@ -9,7 +9,7 @@ tested here; copied verbatim by `token-crosswalk-builder` into the user's
 | --- | --- | --- |
 | `validate-crosswalk.mjs` | Resolve every `newToken` against the DTCG token source; assert resolved value == `newValue`, N/N. The CI gate. | `tokens:validate` |
 | `build-reverse-index.mjs` | Emit a `codeToken -> newToken` map from the crosswalk to semi-automate SCSS/Tailwind swaps. | `tokens:reverse-index` |
-| `guard-token-removal.mjs` | Grep `.ts/.tsx` (minus generated + tests) for about-to-be-deleted symbols; blocks cleanup until zero references remain. | run during the cleanup phase |
+| `guard-token-removal.mjs` | Grep every source file the shared walker reads — `.scss`, `.css`, `.tsx?`, `.jsx?`, `.html` and the rest of `SOURCE_EXT` (minus generated + tests) for about-to-be-deleted symbols; blocks cleanup until zero references remain. | run during the cleanup phase |
 | `validate-token-output.mjs` | Assert generated token output — Swift, Kotlin, or web CSS custom properties — matches its DTCG source: authored-unit fidelity and no mode collisions everywhere, plus no leaked CSS syntax and no bare unit literals in Swift and Kotlin. Fails when no emitted symbol matches a source token, and reports match rate, unparsed lines, and unemitted tokens on every run. | `tokens:validate-output` |
 | `validate-adherence.mjs` | Assert the code *consuming* a design system still adheres to it: every referenced component exists, every literal variant value is one the system declares, and no colour, spacing, radius or type literal duplicates a token that already holds that value. `unnamed-control` fails a Button or IconButton (or a component whose doc record says `archetype: "button"`) with no accessible name: no text, and no `aria-label`, `aria-labelledby` or `title` on it or anything inside it. `colour-only-status` fails a Badge or Tag (or a record with `archetype: "badge"`) the same way, so its status isn't carried by colour alone. Both read script files only (`.js`, `.jsx`, `.ts`, `.tsx`, `.mjs`, `.cjs`), abstain rather than guess on anything they can't read, print how many elements they checked and abstained on, and can be switched off with `--skip`. Fails when an enabled rule had nothing to check, so a green run always means something was verified. | `adherence:check` |
 | `lib/source-scan.mjs` | Shared source-tree walker (`walk`, `DEFAULT_EXCLUDES`, `SOURCE_EXT`) plus `normalizeName`, the display-name-to-code-identifier fold. Every gate that scans a consumer's repo reads it from here rather than carrying its own copy. | copied alongside `guard-token-removal.mjs`, and in the documentation set for `validate-adherence.mjs` and `verify-check.mjs` |
@@ -29,6 +29,7 @@ tested here; copied verbatim by `token-crosswalk-builder` into the user's
 | `lib/component-states.mjs` | The archetype table and resolver behind `state-incomplete` — which baseline interaction states each kind of component owes, and when to abstain. `validate-adherence.mjs` also uses it to find Badges. | copied alongside `verify-check.mjs` and `validate-adherence.mjs` |
 | `lib/contrast.mjs` | The WCAG contrast maths and the semantic colour pairs behind `color-contrast` — which text role must clear which surface, in every mode, and where the rule deliberately abstains. | copied alongside `verify-check.mjs` |
 | `build-doc-card-builder.mjs` | Generate `references/doc-card-builder.md` from the planner + the Figma renderer template (`lib/doc-card-render.figma.js`). `--check` gates CI. | plugin-internal (not installed) |
+| `build-state-baseline.mjs` | Generate `references/state-baseline.md`, the table of which components owe which interaction states, from `lib/component-states.mjs`. The Figma executor reads the table; `verify:check` reads the module. `--check` gates CI. | plugin-internal (not installed) |
 | `build-native-adapter-config.mjs` | Generate `references/native-adapter-config.md` by slicing `lib/sd-native.mjs` on its `@doc-section` markers and interleaving each fragment under its prose. Fails when module code falls outside every section, so the doc cannot silently ship incomplete. `--check` gates CI. | plugin-internal (not installed) |
 
 **Documentation scripts — install as a set.** Copying these files without
@@ -245,7 +246,7 @@ the committed `adapters/<target>/` tree plus the runtime payload
 (`references/` + `scripts/`, minus `scripts/adapters/`) into `.throughline/`,
 rewriting `${CLAUDE_PLUGIN_ROOT}` → `.throughline`:
 
-    npx @radicool/throughline@0.21.3 init --target=cursor|codex|generic
+    npx @radicool/throughline@0.22.0 init --target=cursor|codex|generic
 
 See `scripts/install.mjs` (pure core + CLI + `install.test.mjs`).
 

package/scripts/build-state-baseline.mjs

@@ -0,0 +1,69 @@
+// Generates references/state-baseline.md from scripts/lib/component-states.mjs.
+// The table is the one list of which components owe which interaction states:
+// `verify:check` reads the module, and `figma-executor` (which cannot import
+// JavaScript) reads this rendering. Mirrors build-native-adapter-config.mjs:
+// run bare to write, --check to gate CI. Zero dependencies.
+import { readFileSync, writeFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { ARCHETYPES, BASELINE_STATES, NAME_SYNONYMS, STATE_SYNONYMS } from './lib/component-states.mjs';
+
+const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+export const OUT = join(REPO_ROOT, 'references', 'state-baseline.md');
+
+export function render(states = BASELINE_STATES, synonyms = NAME_SYNONYMS, archetypes = ARCHETYPES, stateSynonyms = STATE_SYNONYMS) {
+  const aliases = Object.keys(stateSynonyms).map((s) => `\`${s}\` counts as \`${stateSynonyms[s]}\``).join(', and ');
+  const owing = archetypes.filter((a) => (states[a] ?? []).length > 0);
+  const rows = owing.map((a) => {
+    const names = Object.keys(synonyms).filter((n) => synonyms[n] === a);
+    return `| ${a} | ${names.map((n) => `\`${n}\``).join(', ')} | ${states[a].map((s) => `\`${s}\``).join(', ')} |`;
+  });
+  const exempt = archetypes.filter((a) => !owing.includes(a) && a !== 'other');
+  const exemptNames = exempt.flatMap((a) => Object.keys(synonyms).filter((n) => synonyms[n] === a));
+  return `<!-- GENERATED by scripts/build-state-baseline.mjs from scripts/lib/component-states.mjs. Do not edit; run: node scripts/build-state-baseline.mjs -->
+# State baseline
+
+Which interaction states a component owes. This is the one list both checks read:
+\`verify:check\` (\`state-incomplete\`) reads it from \`scripts/lib/component-states.mjs\`,
+and \`figma-executor\` (its state check and the \`focus-indicator\` check) reads
+this table. CI fails when the table is stale.
+
+A component name matches a row when it folds (lowercase, punctuation and spaces
+stripped) to exactly one of that row's names. \`Text Field\` folds to \`textfield\`.
+Matching is exact on purpose: \`IconButton\` matches nothing, and a component that
+matches nothing owes no states.
+
+| Archetype | Names | States owed |
+|---|---|---|
+${rows.join('\n')}
+
+Every state in the table must be a value on the component's \`state\` axis. On the
+Figma side the matrix also carries \`default\` as the resting state; the CLI does not
+count it. ${aliases}, since that is what shadcn and Radix call it. Conditional states (\`loading\`, \`error\`, \`success\`) are not in the table:
+whether one applies is a design judgment.
+
+Names that fold to ${exemptNames.map((n) => `\`${n}\``).join(', ')} owe none, so neither check asserts states on them.
+`;
+}
+
+function main() {
+  const check = process.argv.includes('--check');
+  const rendered = render();
+  if (!check) {
+    writeFileSync(OUT, rendered);
+    console.log(`wrote ${OUT}`);
+    return;
+  }
+  const current = readFileSync(OUT, 'utf8');
+  if (current === rendered) {
+    console.log('references/state-baseline.md is up to date');
+    return;
+  }
+  console.error(
+    'references/state-baseline.md is stale.\n' +
+      'Run: node scripts/build-state-baseline.mjs',
+  );
+  process.exit(1);
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) main();

package/scripts/guard-token-removal.mjs

@@ -1,4 +1,4 @@
-// Repo-wide token-removal guard: grep .ts/.tsx (minus generated + tests) for
+// Repo-wide token-removal guard: grep source files (minus generated + tests) for
 // references to about-to-be-deleted symbols. Zero dependencies.
 //
 // Cleanup must not proceed until this returns zero references — deleted Tailwind
@@ -33,9 +33,9 @@ export function scanFile(path, symbols) {
 
 export function guard(root, symbols, excludes = DEFAULT_EXCLUDES) {
   const findings = [];
-  // .ts/.tsx is this guard's own contract, so the filter stays here rather
-  // than moving into the shared walker's default.
-  for (const file of walk(root, { excludes, fileFilter: /\.tsx?$/ })) {
+  // A token can be referenced from a stylesheet or markup as easily as from
+  // TypeScript, so this reads every file type the shared walker defaults to.
+  for (const file of walk(root, { excludes })) {
     for (const hit of scanFile(file, symbols)) {
       findings.push({ file: relative(root, file), ...hit });
     }

package/scripts/lib/component-states.mjs

@@ -1,13 +1,18 @@
 // The archetype baseline for `state-incomplete` (`docs/specs/2026-09-12-verification-proof-bundle.md`,
-// step 3). Source of truth for the prose is `references/figma-component-standards.md:126-138`.
+// step 3). The prose in `references/figma-component-standards.md` (State handling) points at
+// `references/state-baseline.md`, which is generated from this file.
 //
 // `default` is deliberately excluded from every baseline below: documenting the
 // resting state is not documentation, and the Figma matrix requirement for it is
 // the executor's, not this table's. Conditional states (`loading`, `error`,
-// `success`, `selected`) are deliberately excluded too — whether one applies to a
-// given component is a design judgment, not something a baseline can assert.
+// `success`) are deliberately excluded too — whether one applies to a given
+// component is a design judgment, not something a baseline can assert. `selected`
+// is not conditional for a choice control: a checkbox, radio, toggle, switch or
+// chip that cannot be selected is not one.
 //
-// MAINTENANCE: a change to the prose baseline must change this table.
+// This table is the single source for both checks. `scripts/build-state-baseline.mjs`
+// renders it into `references/state-baseline.md`, which the Figma executor reads;
+// CI fails when that file is stale. MAINTENANCE: change this table, then run it.
 
 import { normalizeName } from './source-scan.mjs';
 
@@ -16,7 +21,7 @@ export const ARCHETYPES = ['button', 'input', 'choice', 'card', 'modal', 'badge'
 export const BASELINE_STATES = {
   button: ['hover', 'focus', 'active', 'disabled'],
   input: ['hover', 'focus', 'disabled'],
-  choice: ['hover', 'focus', 'active', 'disabled'],
+  choice: ['hover', 'focus', 'active', 'selected', 'disabled'],
   card: [],
   modal: [],
   badge: [],
@@ -40,6 +45,14 @@ export const NAME_SYNONYMS = {
   tag: 'badge',
 };
 
+// Other names a recorded state goes by. shadcn and Radix call a checked checkbox
+// `checked` and a pressed-in toggle `on`; both are `selected` here. `pressed` is
+// not one: the standards use it for `active`.
+export const STATE_SYNONYMS = {
+  checked: 'selected',
+  on: 'selected',
+};
+
 export function resolveArchetype(record) {
   if (ARCHETYPES.includes(record.archetype)) return record.archetype;
   const bySynonym = NAME_SYNONYMS[normalizeName(record.name)];
@@ -51,6 +64,11 @@ export function missingStates(record) {
   if (archetype === null) return [];
   const baseline = BASELINE_STATES[archetype];
   if (baseline.length === 0) return [];
-  const recordedKeys = new Set(Object.keys(record.states ?? {}).map(normalizeName));
+  const recordedKeys = new Set(
+    Object.keys(record.states ?? {}).map((key) => {
+      const name = normalizeName(key);
+      return STATE_SYNONYMS[name] ?? name;
+    }),
+  );
   return baseline.filter((state) => !recordedKeys.has(normalizeName(state)));
 }

package/scripts/lib/source-scan.mjs

@@ -5,9 +5,9 @@
 // extensions it yielded. The duplication was the shape #57 was filed for: two
 // definitions of one rule, agreeing today, with nothing keeping them in step.
 //
-// The file filter is the caller's, not a built-in: a colour scan wants
-// stylesheets and a symbol guard does not, and neither should have to fork the
-// walker to say so.
+// The file filter is the caller's, not a built-in: a caller that
+// wants stylesheets and HTML takes them, and one that wants only .ts/.tsx can
+// narrow it, without forking the walker.
 import { readdirSync, statSync } from 'node:fs';
 import { join } from 'node:path';