@radicool/throughline 0.23.0 → 0.25.0

package/README.md

@@ -73,7 +73,7 @@ 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.23.0 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.25.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** | 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. |
@@ -107,6 +107,8 @@ Then start with:
 
 This is the reliable entry point — it runs environment setup first, ahead of anything else. (You can also just say *"let's set up my design system"*, but if you have other plugins installed that grab "let's build…" style phrases, the slash command guarantees ThroughLine takes the wheel.)
 
+Already have screens or components in Figma? `/throughline:check-figma` checks them against the system without touching the file: it flags a component someone detached, and a colour, gap, padding or radius that's hardcoded when a token already has that value. It also runs the state, focus-ring and focus-contrast checks over the components already in your library.
+
 Update anytime with `/plugin marketplace update throughline-marketplace`.
 
 #### Cursor, Codex, or a generic AGENTS.md agent
@@ -114,9 +116,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.23.0 init --target=cursor    # → .cursor/rules + .cursor/mcp.json
-npx @radicool/throughline@0.23.0 init --target=codex      # → prompts/ + AGENTS.md index + codex-mcp.toml
-npx @radicool/throughline@0.23.0 init --target=generic    # → skills/ + AGENTS.md index
+npx @radicool/throughline@0.25.0 init --target=cursor    # → .cursor/rules + .cursor/mcp.json
+npx @radicool/throughline@0.25.0 init --target=codex      # → prompts/ + AGENTS.md index + codex-mcp.toml
+npx @radicool/throughline@0.25.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.
@@ -212,7 +214,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 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).
+- **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. A Figma build also stops when a focus ring falls below WCAG's 3:1 against a surface the architect names for it, in any mode. 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.
 - **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/AGENTS.md

@@ -19,6 +19,7 @@ ThroughLine builds a design system end to end. Load the matching prompt for the
 
 ## ThroughLine commands
 
+- `check-figma` — Check what's already in Figma against the design system, read-only — screens for detached components and raw values a token has, and existing component sets for their states, focus ring and focus contrast. → load `prompts/check-figma.md`.
 - `design-system-status` — Show a plain-language summary of the current design system state — what's set up, what's not, and sensible next steps — read from design-system.json. → load `prompts/design-system-status.md`.
 - `document-component` — Author, refresh, or reconcile the usage documentation for one existing component — draft its canonical doc record from four sources, project it to Figma, the doc card, and code, and resolve any drift via a reviewable per-item choice. → load `prompts/document-component.md`.
 - `new-component` — Build a single new component end to end — in Figma, then sync any new tokens, then build its code component and stories — with a confirmation between each stage. → load `prompts/new-component.md`.

package/adapters/codex/prompts/check-figma.md

@@ -0,0 +1,41 @@
+Check the Figma file against the design system without changing it. Use the
+settings already in `design-system.json` (`figma.fileKey`, `project.uiFramework`,
+`components.built`) rather than re-asking them. Scale explanation to
+`user.codingLevel`.
+
+1. **Know the file.** Read `figma.fileKey` from `design-system.json`. If it's
+   absent, stop and ask which file to check.
+2. **Confirm the active file.** Run the preflight in
+   `.throughline/references/figma-scripting.md` ("confirm the *active*
+   file is your target") against that fileKey, and pin it with `figma_navigate`
+   (`lock: true`) for the run. Unpin when done.
+3. **Screens.** Unless the user named them, ask which page holds the screens, and
+   optionally which screens on it. Run the snippet in
+   `.throughline/references/figma-adherence.md` verbatim, with
+   `const TARGET = { page, screens, fileKey }` (the fileKey from step 1, for the
+   links) and `const SKIP = []` filled. The script is the rule; don't re-derive its
+   checks.
+4. **Existing component sets.** Ask which page holds the component sets, so only
+   that page is loaded. Ask which colour variables are the page surfaces the
+   components sit on, offering the file's likeliest default page surface (read the
+   names with `figma_get_variables`), or let the user skip focus contrast. For each
+   name in `components.built`, run
+   `.throughline/references/figma-checks.md` with `MODE = 'existing'` and
+   `EXPECT = { name, page, uiFramework, surfaces }` (`uiFramework` from
+   `project.uiFramework`). A name with no set on that page is reported as missing,
+   not as a failure of the others. When `focus-indicator` fails on a wrapped control
+   (an Input with a label, a Checkbox whose box is an inner frame), look at one focus
+   variant's layers before reporting it: if the ring is on an inner layer, run that
+   set again with `controlLayer` naming that layer, and say in the report that you
+   did.
+5. **Report.** The screen gate gives one pass or fail for the page: list its
+   failures grouped by screen (the path's second segment), each with its detail and
+   link, then the advisories, the counts and any skipped rules. Then pass or fail
+   per component set, with whether focus contrast ran and against which surfaces. Say plainly what the
+   gate can't see: a frame drawn from scratch to look like a component, variables
+   that live only in a published library, and focus states drawn as an INSIDE
+   stroke.
+
+Never edit the file to make a check pass, and never edit a token. A failure is
+a finding for the user; fixing it is a separate, deliberate step.
+

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

@@ -177,8 +177,12 @@ deterministic naming):
   way the executor does: `'spec'` mode before the first write and `'built'` mode
   in the self-verify loop, with `EXPECT` built from your own matrix. You are the
   architect here, so you name `controlLayer` yourself for a wrapped control (an
-  Input with a label or helper text). A `fail` on the `focus-indicator` check
-  stops the build, as it would for the executor.
+  Input with a label or helper text), and `surfaces` yourself: the colour-variable
+  names of the page surfaces the component sits on. A `fail` on the
+  `focus-indicator` check stops the build, as it would for the executor. A `fail`
+  on `focus-contrast` stops it too, naming its detail. A ring below 3:1 is fixed by
+  a token value, so don't change a variable or swap the ring to another one to make
+  it pass; a surface the file doesn't have is a wrong name in `surfaces`.
 
 Checkpoint after each component: show all variants, confirm before the next.
 
@@ -366,8 +370,8 @@ any component built with the toggle + manual-swap fallback is listed in
 component-builder --subject <Name> --entry <tmp>.json`. Build `<tmp>.json` with
 `at` (an ISO timestamp you supply), `changed` (what was built), the attested checks `structural-read-back`,
 `state-baseline` and `figma-name` from what the `figma-executor` returned (or
-what your inline read-back found), `focus-indicator` when that check ran and
-passed (not when it was skipped),
+what your inline read-back found), `focus-indicator` and `focus-contrast`
+each when that check ran and passed (not when it was skipped),
 `review` when a reviewer ran, `screenshot` when one was captured, and
 `advancedBecause`. The entry shape is
 `.throughline/references/proof-bundle.md` — don't restate it here. Write

package/adapters/cursor/.cursor/commands/check-figma.md

@@ -0,0 +1,41 @@
+Check the Figma file against the design system without changing it. Use the
+settings already in `design-system.json` (`figma.fileKey`, `project.uiFramework`,
+`components.built`) rather than re-asking them. Scale explanation to
+`user.codingLevel`.
+
+1. **Know the file.** Read `figma.fileKey` from `design-system.json`. If it's
+   absent, stop and ask which file to check.
+2. **Confirm the active file.** Run the preflight in
+   `.throughline/references/figma-scripting.md` ("confirm the *active*
+   file is your target") against that fileKey, and pin it with `figma_navigate`
+   (`lock: true`) for the run. Unpin when done.
+3. **Screens.** Unless the user named them, ask which page holds the screens, and
+   optionally which screens on it. Run the snippet in
+   `.throughline/references/figma-adherence.md` verbatim, with
+   `const TARGET = { page, screens, fileKey }` (the fileKey from step 1, for the
+   links) and `const SKIP = []` filled. The script is the rule; don't re-derive its
+   checks.
+4. **Existing component sets.** Ask which page holds the component sets, so only
+   that page is loaded. Ask which colour variables are the page surfaces the
+   components sit on, offering the file's likeliest default page surface (read the
+   names with `figma_get_variables`), or let the user skip focus contrast. For each
+   name in `components.built`, run
+   `.throughline/references/figma-checks.md` with `MODE = 'existing'` and
+   `EXPECT = { name, page, uiFramework, surfaces }` (`uiFramework` from
+   `project.uiFramework`). A name with no set on that page is reported as missing,
+   not as a failure of the others. When `focus-indicator` fails on a wrapped control
+   (an Input with a label, a Checkbox whose box is an inner frame), look at one focus
+   variant's layers before reporting it: if the ring is on an inner layer, run that
+   set again with `controlLayer` naming that layer, and say in the report that you
+   did.
+5. **Report.** The screen gate gives one pass or fail for the page: list its
+   failures grouped by screen (the path's second segment), each with its detail and
+   link, then the advisories, the counts and any skipped rules. Then pass or fail
+   per component set, with whether focus contrast ran and against which surfaces. Say plainly what the
+   gate can't see: a frame drawn from scratch to look like a component, variables
+   that live only in a published library, and focus states drawn as an INSIDE
+   stroke.
+
+Never edit the file to make a check pass, and never edit a token. A failure is
+a finding for the user; fixing it is a separate, deliberate step.
+

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

@@ -181,8 +181,12 @@ deterministic naming):
   way the executor does: `'spec'` mode before the first write and `'built'` mode
   in the self-verify loop, with `EXPECT` built from your own matrix. You are the
   architect here, so you name `controlLayer` yourself for a wrapped control (an
-  Input with a label or helper text). A `fail` on the `focus-indicator` check
-  stops the build, as it would for the executor.
+  Input with a label or helper text), and `surfaces` yourself: the colour-variable
+  names of the page surfaces the component sits on. A `fail` on the
+  `focus-indicator` check stops the build, as it would for the executor. A `fail`
+  on `focus-contrast` stops it too, naming its detail. A ring below 3:1 is fixed by
+  a token value, so don't change a variable or swap the ring to another one to make
+  it pass; a surface the file doesn't have is a wrong name in `surfaces`.
 
 Checkpoint after each component: show all variants, confirm before the next.
 
@@ -370,8 +374,8 @@ any component built with the toggle + manual-swap fallback is listed in
 component-builder --subject <Name> --entry <tmp>.json`. Build `<tmp>.json` with
 `at` (an ISO timestamp you supply), `changed` (what was built), the attested checks `structural-read-back`,
 `state-baseline` and `figma-name` from what the `figma-executor` returned (or
-what your inline read-back found), `focus-indicator` when that check ran and
-passed (not when it was skipped),
+what your inline read-back found), `focus-indicator` and `focus-contrast`
+each when that check ran and passed (not when it was skipped),
 `review` when a reviewer ran, `screenshot` when one was captured, and
 `advancedBecause`. The entry shape is
 `.throughline/references/proof-bundle.md` — don't restate it here. Write

package/adapters/generic/AGENTS.md

@@ -19,6 +19,7 @@ ThroughLine builds a design system end to end. Read the matching skill file for
 
 ## ThroughLine commands
 
+- `check-figma` — Check what's already in Figma against the design system, read-only — screens for detached components and raw values a token has, and existing component sets for their states, focus ring and focus contrast. → read `commands/check-figma.md`.
 - `design-system-status` — Show a plain-language summary of the current design system state — what's set up, what's not, and sensible next steps — read from design-system.json. → read `commands/design-system-status.md`.
 - `document-component` — Author, refresh, or reconcile the usage documentation for one existing component — draft its canonical doc record from four sources, project it to Figma, the doc card, and code, and resolve any drift via a reviewable per-item choice. → read `commands/document-component.md`.
 - `new-component` — Build a single new component end to end — in Figma, then sync any new tokens, then build its code component and stories — with a confirmation between each stage. → read `commands/new-component.md`.

package/adapters/generic/commands/check-figma.md

@@ -0,0 +1,41 @@
+Check the Figma file against the design system without changing it. Use the
+settings already in `design-system.json` (`figma.fileKey`, `project.uiFramework`,
+`components.built`) rather than re-asking them. Scale explanation to
+`user.codingLevel`.
+
+1. **Know the file.** Read `figma.fileKey` from `design-system.json`. If it's
+   absent, stop and ask which file to check.
+2. **Confirm the active file.** Run the preflight in
+   `.throughline/references/figma-scripting.md` ("confirm the *active*
+   file is your target") against that fileKey, and pin it with `figma_navigate`
+   (`lock: true`) for the run. Unpin when done.
+3. **Screens.** Unless the user named them, ask which page holds the screens, and
+   optionally which screens on it. Run the snippet in
+   `.throughline/references/figma-adherence.md` verbatim, with
+   `const TARGET = { page, screens, fileKey }` (the fileKey from step 1, for the
+   links) and `const SKIP = []` filled. The script is the rule; don't re-derive its
+   checks.
+4. **Existing component sets.** Ask which page holds the component sets, so only
+   that page is loaded. Ask which colour variables are the page surfaces the
+   components sit on, offering the file's likeliest default page surface (read the
+   names with `figma_get_variables`), or let the user skip focus contrast. For each
+   name in `components.built`, run
+   `.throughline/references/figma-checks.md` with `MODE = 'existing'` and
+   `EXPECT = { name, page, uiFramework, surfaces }` (`uiFramework` from
+   `project.uiFramework`). A name with no set on that page is reported as missing,
+   not as a failure of the others. When `focus-indicator` fails on a wrapped control
+   (an Input with a label, a Checkbox whose box is an inner frame), look at one focus
+   variant's layers before reporting it: if the ring is on an inner layer, run that
+   set again with `controlLayer` naming that layer, and say in the report that you
+   did.
+5. **Report.** The screen gate gives one pass or fail for the page: list its
+   failures grouped by screen (the path's second segment), each with its detail and
+   link, then the advisories, the counts and any skipped rules. Then pass or fail
+   per component set, with whether focus contrast ran and against which surfaces. Say plainly what the
+   gate can't see: a frame drawn from scratch to look like a component, variables
+   that live only in a published library, and focus states drawn as an INSIDE
+   stroke.
+
+Never edit the file to make a check pass, and never edit a token. A failure is
+a finding for the user; fixing it is a separate, deliberate step.
+

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

@@ -177,8 +177,12 @@ deterministic naming):
   way the executor does: `'spec'` mode before the first write and `'built'` mode
   in the self-verify loop, with `EXPECT` built from your own matrix. You are the
   architect here, so you name `controlLayer` yourself for a wrapped control (an
-  Input with a label or helper text). A `fail` on the `focus-indicator` check
-  stops the build, as it would for the executor.
+  Input with a label or helper text), and `surfaces` yourself: the colour-variable
+  names of the page surfaces the component sits on. A `fail` on the
+  `focus-indicator` check stops the build, as it would for the executor. A `fail`
+  on `focus-contrast` stops it too, naming its detail. A ring below 3:1 is fixed by
+  a token value, so don't change a variable or swap the ring to another one to make
+  it pass; a surface the file doesn't have is a wrong name in `surfaces`.
 
 Checkpoint after each component: show all variants, confirm before the next.
 
@@ -366,8 +370,8 @@ any component built with the toggle + manual-swap fallback is listed in
 component-builder --subject <Name> --entry <tmp>.json`. Build `<tmp>.json` with
 `at` (an ISO timestamp you supply), `changed` (what was built), the attested checks `structural-read-back`,
 `state-baseline` and `figma-name` from what the `figma-executor` returned (or
-what your inline read-back found), `focus-indicator` when that check ran and
-passed (not when it was skipped),
+what your inline read-back found), `focus-indicator` and `focus-contrast`
+each when that check ran and passed (not when it was skipped),
 `review` when a reviewer ran, `screenshot` when one was captured, and
 `advancedBecause`. The entry shape is
 `.throughline/references/proof-bundle.md` — don't restate it here. Write

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@radicool/throughline",
-  "version": "0.23.0",
+  "version": "0.25.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": {