@radicool/throughline 0.21.2 → 0.21.4

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 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.21.4 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 init --target=cursor    # → .cursor/rules + .cursor/mcp.json
-npx @radicool/throughline init --target=codex      # → prompts/ + AGENTS.md index + codex-mcp.toml
-npx @radicool/throughline init --target=generic    # → skills/ + AGENTS.md index
+npx @radicool/throughline@0.21.4 init --target=cursor    # → .cursor/rules + .cursor/mcp.json
+npx @radicool/throughline@0.21.4 init --target=codex      # → prompts/ + AGENTS.md index + codex-mcp.toml
+npx @radicool/throughline@0.21.4 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. Setup pins **Haiku** 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 apart from setup's Haiku pin, 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

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

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

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

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@radicool/throughline",
-  "version": "0.21.2",
+  "version": "0.21.4",
   "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/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/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` |
@@ -245,7 +245,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 init --target=cursor|codex|generic
+    npx @radicool/throughline@0.21.4 init --target=cursor|codex|generic
 
 See `scripts/install.mjs` (pure core + CLI + `install.test.mjs`).
 

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/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';