@radicool/throughline 0.26.0 → 0.27.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.26.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.27.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. |
@@ -111,6 +111,8 @@ Already have screens or components in Figma? `/throughline:check-figma` checks t
 
 Need a new screen? `/throughline:compose-figma` builds it in Figma from your own components and tokens, every value bound. If the screen needs something your system doesn't have, it says so instead of drawing a lookalike, and it runs the same check before handing the screen over.
 
+Want it in code instead? `/throughline:compose-code` writes the screen as one React file in your app, using only your components and your tokens. It checks the plan before writing a line, reports any component you don't have rather than building one, and gates the file before handing it over.
+
 Update anytime with `/plugin marketplace update throughline-marketplace`.
 
 #### Cursor, Codex, or a generic AGENTS.md agent
@@ -118,9 +120,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.26.0 init --target=cursor    # → .cursor/rules + .cursor/mcp.json
-npx @radicool/throughline@0.26.0 init --target=codex      # → prompts/ + AGENTS.md index + codex-mcp.toml
-npx @radicool/throughline@0.26.0 init --target=generic    # → skills/ + AGENTS.md index
+npx @radicool/throughline@0.27.0 init --target=cursor    # → .cursor/rules + .cursor/mcp.json
+npx @radicool/throughline@0.27.0 init --target=codex      # → prompts/ + AGENTS.md index + codex-mcp.toml
+npx @radicool/throughline@0.27.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.

package/adapters/codex/AGENTS.md

@@ -20,6 +20,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`.
+- `compose-code` — Compose a screen in code from the design system's own components and tokens — plan checked before writing, every value a token, gated before it's handed over. → load `prompts/compose-code.md`.
 - `compose-figma` — Compose a screen in Figma from the design system's own components, variables and text styles — every value bound, nothing invented, gated before it's handed over. → load `prompts/compose-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`.

package/adapters/codex/prompts/compose-code.md

@@ -0,0 +1,78 @@
+Compose the screen the user asked for as one React file in their app, from what
+the design system already has. Use the settings already in `design-system.json`
+rather than re-asking them. Scale explanation to `user.codingLevel`.
+
+1. **Know the framework.** Read `project.uiFramework` from `design-system.json`.
+   Composing in code covers `shadcn` and `tailwind`. For anything else, stop and
+   say composing in code doesn't cover that framework yet.
+2. **Find the gate settings.** Search the repo's `package.json` files (not under
+   `node_modules`) for an `adherence:check` script. If one exists, take its
+   `--system`, `--package` and every `--tokens`, each resolved against the
+   directory of the `package.json` that holds it. Otherwise ask the user for the
+   package specifier the app imports the system from and the token source files,
+   and use the repo root as `--system`. Pass every token file: a system whose
+   values span modes has one per mode.
+3. **Know the target.** Unless the user named it, ask for the screen's name and
+   the file path to write it to, inside the app. Write `.tsx`, or `.jsx` when the
+   app has no TypeScript.
+4. **Read what exists.** Run
+   `node .throughline/scripts/compose-code.mjs inventory --system <dir> --package <spec>`.
+   Its components, with their variant axes, values, states, `whenToUse` and
+   `whenNotToUse`, are the only components the screen may use. Read a listed
+   component's own source for its prop names and exported sub-parts
+   (`CardHeader`); the inventory records neither. Find it by resolving the
+   package specifier: a workspace package in a monorepo, or the app's
+   `node_modules` otherwise. Token variable names come from
+   the system's generated CSS (the file its styles import), and the utilities
+   from its Tailwind preset; read both.
+5. **Plan.** Write the plan as JSON to a scratch file:
+   `{ "screen", "file", "components": [{ "name", "variants": { "<axis>": "<value>" } }] }`,
+   one entry per component the screen uses, with the variant values it sets. A
+   sub-part (`CardHeader`) comes with its owner (`Card`) and needs no entry. When
+   the request needs a component the inventory doesn't have, say so before
+   writing and ask: leave it out, use a named existing component instead, or stop.
+   The `nearest` names are matched on spelling; suggest the alternative that fits
+   by `whenToUse` instead when one does. Never build a lookalike. An icon, or
+   anything else the system's package doesn't export, is a gap in the same way:
+   the screen imports only from the package and React.
+6. **Check the plan.** Run the script with `check --system <dir> --package <spec> --plan <plan file>`
+   from the repo root. If it returns errors, nothing has been written: fix the
+   plan (a `missing-component` error goes back to the user as in step 5) and check
+   again. A `name-taken` error means the file at that path wasn't composed for
+   this screen: ask for another path, or for the user to move that file. A
+   re-run replaces an earlier composed file only when the screen name matches
+   its marker exactly, so reuse the name as written. Write
+   the variant values in the casing the returned plan uses.
+7. **Write.** Put the marker `// Composed by throughline: <screen>.` on the first
+   line, or on the second after a `'use client'` directive. Import components only
+   from the package specifier. Plain elements carry layout only (flex, grid, gap,
+   padding, sizing); visible text uses semantic elements (`h1`, `p`, `label`);
+   everything the user operates is a system component from the plan (a link may
+   be a plain `<a>`). Write colour, spacing, sizing, type size and font weight
+   only as token variables
+   (`gap-[var(--space-gap-md)]`, `style={{ padding: 'var(--space-4)' }}`) or the
+   utilities the system's preset generates from tokens (`bg-primary`,
+   `rounded-md`). Never a raw value, and never Tailwind's default scale
+   (`gap-4`, `text-lg`, `font-semibold`). Percentages, viewport units,
+   fractions (`w-1/2`) and keywords (`w-full`) are layout and fine. The gate
+   reads class names anywhere in the file, so visible copy that spells one
+   (`text-sm`) fails too; reword the copy rather than the rule. The gate can't
+   see a lookalike built from plain elements (a `div` with `role="switch"`), so
+   that one is yours to refuse. A size no token holds (a 400px card) can't be bound:
+   use a fraction or a keyword and say so in the report. Handlers are stubs; data and state are the app's.
+8. **Gate.** Run the script with
+   `gate --system <dir> --package <spec> --plan <plan file> --file <screen file>`,
+   with `--tokens <file>` repeated once per token file.
+   On a failure, fix the file and run it again, up to three attempts in all. If
+   the third still fails, stop: the file stays where it is, marked, and the
+   report lists every failure and says a re-run replaces it. Never change the
+   plan or skip a rule to make it pass.
+9. **Report.** The file's path, whether it replaced an earlier composed one, the
+   gate's counts, every gap (each component asked for that doesn't exist, with the
+   nearest names the script offered, and what was left out because of it), and
+   how to mount the screen where the app picks its screens (its router or entry).
+   Don't edit it.
+
+Never edit a component, a token or the app's routing. If the screen can't be
+built from what the system has, the gap is the finding.
+

package/adapters/cursor/.cursor/commands/compose-code.md

@@ -0,0 +1,78 @@
+Compose the screen the user asked for as one React file in their app, from what
+the design system already has. Use the settings already in `design-system.json`
+rather than re-asking them. Scale explanation to `user.codingLevel`.
+
+1. **Know the framework.** Read `project.uiFramework` from `design-system.json`.
+   Composing in code covers `shadcn` and `tailwind`. For anything else, stop and
+   say composing in code doesn't cover that framework yet.
+2. **Find the gate settings.** Search the repo's `package.json` files (not under
+   `node_modules`) for an `adherence:check` script. If one exists, take its
+   `--system`, `--package` and every `--tokens`, each resolved against the
+   directory of the `package.json` that holds it. Otherwise ask the user for the
+   package specifier the app imports the system from and the token source files,
+   and use the repo root as `--system`. Pass every token file: a system whose
+   values span modes has one per mode.
+3. **Know the target.** Unless the user named it, ask for the screen's name and
+   the file path to write it to, inside the app. Write `.tsx`, or `.jsx` when the
+   app has no TypeScript.
+4. **Read what exists.** Run
+   `node .throughline/scripts/compose-code.mjs inventory --system <dir> --package <spec>`.
+   Its components, with their variant axes, values, states, `whenToUse` and
+   `whenNotToUse`, are the only components the screen may use. Read a listed
+   component's own source for its prop names and exported sub-parts
+   (`CardHeader`); the inventory records neither. Find it by resolving the
+   package specifier: a workspace package in a monorepo, or the app's
+   `node_modules` otherwise. Token variable names come from
+   the system's generated CSS (the file its styles import), and the utilities
+   from its Tailwind preset; read both.
+5. **Plan.** Write the plan as JSON to a scratch file:
+   `{ "screen", "file", "components": [{ "name", "variants": { "<axis>": "<value>" } }] }`,
+   one entry per component the screen uses, with the variant values it sets. A
+   sub-part (`CardHeader`) comes with its owner (`Card`) and needs no entry. When
+   the request needs a component the inventory doesn't have, say so before
+   writing and ask: leave it out, use a named existing component instead, or stop.
+   The `nearest` names are matched on spelling; suggest the alternative that fits
+   by `whenToUse` instead when one does. Never build a lookalike. An icon, or
+   anything else the system's package doesn't export, is a gap in the same way:
+   the screen imports only from the package and React.
+6. **Check the plan.** Run the script with `check --system <dir> --package <spec> --plan <plan file>`
+   from the repo root. If it returns errors, nothing has been written: fix the
+   plan (a `missing-component` error goes back to the user as in step 5) and check
+   again. A `name-taken` error means the file at that path wasn't composed for
+   this screen: ask for another path, or for the user to move that file. A
+   re-run replaces an earlier composed file only when the screen name matches
+   its marker exactly, so reuse the name as written. Write
+   the variant values in the casing the returned plan uses.
+7. **Write.** Put the marker `// Composed by throughline: <screen>.` on the first
+   line, or on the second after a `'use client'` directive. Import components only
+   from the package specifier. Plain elements carry layout only (flex, grid, gap,
+   padding, sizing); visible text uses semantic elements (`h1`, `p`, `label`);
+   everything the user operates is a system component from the plan (a link may
+   be a plain `<a>`). Write colour, spacing, sizing, type size and font weight
+   only as token variables
+   (`gap-[var(--space-gap-md)]`, `style={{ padding: 'var(--space-4)' }}`) or the
+   utilities the system's preset generates from tokens (`bg-primary`,
+   `rounded-md`). Never a raw value, and never Tailwind's default scale
+   (`gap-4`, `text-lg`, `font-semibold`). Percentages, viewport units,
+   fractions (`w-1/2`) and keywords (`w-full`) are layout and fine. The gate
+   reads class names anywhere in the file, so visible copy that spells one
+   (`text-sm`) fails too; reword the copy rather than the rule. The gate can't
+   see a lookalike built from plain elements (a `div` with `role="switch"`), so
+   that one is yours to refuse. A size no token holds (a 400px card) can't be bound:
+   use a fraction or a keyword and say so in the report. Handlers are stubs; data and state are the app's.
+8. **Gate.** Run the script with
+   `gate --system <dir> --package <spec> --plan <plan file> --file <screen file>`,
+   with `--tokens <file>` repeated once per token file.
+   On a failure, fix the file and run it again, up to three attempts in all. If
+   the third still fails, stop: the file stays where it is, marked, and the
+   report lists every failure and says a re-run replaces it. Never change the
+   plan or skip a rule to make it pass.
+9. **Report.** The file's path, whether it replaced an earlier composed one, the
+   gate's counts, every gap (each component asked for that doesn't exist, with the
+   nearest names the script offered, and what was left out because of it), and
+   how to mount the screen where the app picks its screens (its router or entry).
+   Don't edit it.
+
+Never edit a component, a token or the app's routing. If the screen can't be
+built from what the system has, the gap is the finding.
+

package/adapters/generic/AGENTS.md

@@ -20,6 +20,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`.
+- `compose-code` — Compose a screen in code from the design system's own components and tokens — plan checked before writing, every value a token, gated before it's handed over. → read `commands/compose-code.md`.
 - `compose-figma` — Compose a screen in Figma from the design system's own components, variables and text styles — every value bound, nothing invented, gated before it's handed over. → read `commands/compose-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`.

package/adapters/generic/commands/compose-code.md

@@ -0,0 +1,78 @@
+Compose the screen the user asked for as one React file in their app, from what
+the design system already has. Use the settings already in `design-system.json`
+rather than re-asking them. Scale explanation to `user.codingLevel`.
+
+1. **Know the framework.** Read `project.uiFramework` from `design-system.json`.
+   Composing in code covers `shadcn` and `tailwind`. For anything else, stop and
+   say composing in code doesn't cover that framework yet.
+2. **Find the gate settings.** Search the repo's `package.json` files (not under
+   `node_modules`) for an `adherence:check` script. If one exists, take its
+   `--system`, `--package` and every `--tokens`, each resolved against the
+   directory of the `package.json` that holds it. Otherwise ask the user for the
+   package specifier the app imports the system from and the token source files,
+   and use the repo root as `--system`. Pass every token file: a system whose
+   values span modes has one per mode.
+3. **Know the target.** Unless the user named it, ask for the screen's name and
+   the file path to write it to, inside the app. Write `.tsx`, or `.jsx` when the
+   app has no TypeScript.
+4. **Read what exists.** Run
+   `node .throughline/scripts/compose-code.mjs inventory --system <dir> --package <spec>`.
+   Its components, with their variant axes, values, states, `whenToUse` and
+   `whenNotToUse`, are the only components the screen may use. Read a listed
+   component's own source for its prop names and exported sub-parts
+   (`CardHeader`); the inventory records neither. Find it by resolving the
+   package specifier: a workspace package in a monorepo, or the app's
+   `node_modules` otherwise. Token variable names come from
+   the system's generated CSS (the file its styles import), and the utilities
+   from its Tailwind preset; read both.
+5. **Plan.** Write the plan as JSON to a scratch file:
+   `{ "screen", "file", "components": [{ "name", "variants": { "<axis>": "<value>" } }] }`,
+   one entry per component the screen uses, with the variant values it sets. A
+   sub-part (`CardHeader`) comes with its owner (`Card`) and needs no entry. When
+   the request needs a component the inventory doesn't have, say so before
+   writing and ask: leave it out, use a named existing component instead, or stop.
+   The `nearest` names are matched on spelling; suggest the alternative that fits
+   by `whenToUse` instead when one does. Never build a lookalike. An icon, or
+   anything else the system's package doesn't export, is a gap in the same way:
+   the screen imports only from the package and React.
+6. **Check the plan.** Run the script with `check --system <dir> --package <spec> --plan <plan file>`
+   from the repo root. If it returns errors, nothing has been written: fix the
+   plan (a `missing-component` error goes back to the user as in step 5) and check
+   again. A `name-taken` error means the file at that path wasn't composed for
+   this screen: ask for another path, or for the user to move that file. A
+   re-run replaces an earlier composed file only when the screen name matches
+   its marker exactly, so reuse the name as written. Write
+   the variant values in the casing the returned plan uses.
+7. **Write.** Put the marker `// Composed by throughline: <screen>.` on the first
+   line, or on the second after a `'use client'` directive. Import components only
+   from the package specifier. Plain elements carry layout only (flex, grid, gap,
+   padding, sizing); visible text uses semantic elements (`h1`, `p`, `label`);
+   everything the user operates is a system component from the plan (a link may
+   be a plain `<a>`). Write colour, spacing, sizing, type size and font weight
+   only as token variables
+   (`gap-[var(--space-gap-md)]`, `style={{ padding: 'var(--space-4)' }}`) or the
+   utilities the system's preset generates from tokens (`bg-primary`,
+   `rounded-md`). Never a raw value, and never Tailwind's default scale
+   (`gap-4`, `text-lg`, `font-semibold`). Percentages, viewport units,
+   fractions (`w-1/2`) and keywords (`w-full`) are layout and fine. The gate
+   reads class names anywhere in the file, so visible copy that spells one
+   (`text-sm`) fails too; reword the copy rather than the rule. The gate can't
+   see a lookalike built from plain elements (a `div` with `role="switch"`), so
+   that one is yours to refuse. A size no token holds (a 400px card) can't be bound:
+   use a fraction or a keyword and say so in the report. Handlers are stubs; data and state are the app's.
+8. **Gate.** Run the script with
+   `gate --system <dir> --package <spec> --plan <plan file> --file <screen file>`,
+   with `--tokens <file>` repeated once per token file.
+   On a failure, fix the file and run it again, up to three attempts in all. If
+   the third still fails, stop: the file stays where it is, marked, and the
+   report lists every failure and says a re-run replaces it. Never change the
+   plan or skip a rule to make it pass.
+9. **Report.** The file's path, whether it replaced an earlier composed one, the
+   gate's counts, every gap (each component asked for that doesn't exist, with the
+   nearest names the script offered, and what was left out because of it), and
+   how to mount the screen where the app picks its screens (its router or entry).
+   Don't edit it.
+
+Never edit a component, a token or the app's routing. If the screen can't be
+built from what the system has, the gap is the finding.
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@radicool/throughline",
-  "version": "0.26.0",
+  "version": "0.27.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/scripts/README.md

@@ -28,7 +28,7 @@ tested here; copied verbatim by `token-crosswalk-builder` into the user's
 | `lib/figma-variables-read.figma.js` | Figma helpers that resolve a colour variable's value in each mode, through aliases. Inlined into `references/figma-checks.md`, `references/figma-adherence.md` and `references/figma-compose.md`; never executed as a module. | plugin-internal (not installed) |
 | `lib/figma-adherence.mjs` | Pure checker for the Figma screen adherence gate: detached components, and raw colours, gaps, padding and radii that a variable has. A raw value no variable has is an advisory. Inlined into `references/figma-adherence.md`; unit-tested against `lib/fixtures/figma-adherence/`. | plugin-internal (not installed) |
 | `lib/figma-adherence-read.figma.js` | Figma reader that turns the screens on one page into the adherence checker's snapshot JSON, read-only, including content added to an instance's slots. Inlined into `references/figma-adherence.md`; never executed as a module. | plugin-internal (not installed) |
-| `lib/figma-compose.mjs` | Pure resolver for composing a Figma screen: checks a screen description against the file's component sets, variables and text styles, and returns every error or a plan of real keys and ids. Inlined into `references/figma-compose.md`; unit-tested against `lib/fixtures/figma-compose/`. | plugin-internal (not installed) |
+| `lib/figma-compose.mjs` | Pure resolver for composing a Figma screen: checks a screen description against the file's component sets, variables and text styles, and returns every error or a plan of real keys and ids. Inlined into `references/figma-compose.md`; unit-tested against `lib/fixtures/figma-compose/`. `compose-code.mjs` imports its `nearestNames`. | run from the plugin (or `.throughline/scripts`) by `compose-code.mjs`; not copied into consumer repos |
 | `lib/figma-compose.figma.js` | Figma reader and writer for screen composition: reads the inventory, builds a `WIP:` screen from the resolver's plan with every value bound, and finalizes or discards it. Inlined into `references/figma-compose.md`; never executed as a module. | plugin-internal (not installed) |
 | `lib/doc-card-plan.mjs` | Pure layout planner for the doc card's `Usage` band + `DOC_CARD_RENDERER_VERSION` (single source of the layout version). Inlined into `references/doc-card-builder.md`; imported by `docs-check.mjs`. | copied alongside docs-check.mjs; also inlined into the generated builder |
 | `verify-check.mjs` | The verification proof bundle: records each stage's entry, and re-derives what it can rather than trusting the record. Fails on an orphaned token, a component documented without its archetype's baseline interaction states, a name that drifts between the manifest, its record and its code surface, or a recorded result the rerun contradicts. | `verify:check` |
@@ -36,6 +36,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. Also inlined into `references/figma-checks.md` for the focus-ring contrast check. | copied alongside `verify-check.mjs`; also inlined into the generated Figma checks |
 | `doc-card-payload.mjs` | Assemble the complete `figma_execute` body that renders one doc card — record, canonical fingerprint, the nine `figma.docCardVariables` lookups, `Body/Default`, the generated snippet and the call — and print the `renderHash` the render must return, so a payload that changed on the way in is caught. Reads the snippet from `../references/doc-card-builder.md`. | run from the plugin (or `.throughline/scripts`); not copied into consumer repos |
+| `compose-code.mjs` | Composing a screen in code: `inventory` lists the system's components with their variant axes from `components.built` and the docs index, `check` resolves a screen's plan before any code is written and returns every gap with the nearest names, and `gate` runs the adherence gate on the one composed file plus three rules only a composed file is held to (`raw-value`, `scale-utility`, `off-plan`). Used by `/throughline:compose-code`. | run from the plugin (or `.throughline/scripts`); not copied into consumer repos |
 | `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-figma-checks.mjs` | Generate `references/figma-checks.md`, the `figma_execute` snippet for the Figma stop conditions, by inlining `lib/component-states.mjs`, `lib/contrast.mjs`, `lib/figma-checks.mjs` and `lib/figma-variables-read.figma.js` above the reader (`lib/figma-checks-read.figma.js`); `references/figma-adherence.md`, the screen adherence gate, from `lib/figma-adherence.mjs`, `lib/figma-variables-read.figma.js` and `lib/figma-adherence-read.figma.js`; and `references/figma-compose.md`, screen composition, from `lib/figma-adherence.mjs`, `lib/figma-compose.mjs`, `lib/figma-variables-read.figma.js` and `lib/figma-compose.figma.js`. `--check` gates CI on all three. | 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) |
@@ -255,7 +256,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.26.0 init --target=cursor|codex|generic
+    npx @radicool/throughline@0.27.0 init --target=cursor|codex|generic
 
 See `scripts/install.mjs` (pure core + CLI + `install.test.mjs`).
 

package/scripts/compose-code.mjs

@@ -0,0 +1,271 @@
+// Composing a screen in code: the inventory a composer may use, a check of its
+// plan before any code is written, and the gate a composed file must pass. Run
+// by /throughline:compose-code from the plugin (or .throughline/scripts).
+//
+//   node scripts/compose-code.mjs inventory --system <dir> --package <spec>
+//   node scripts/compose-code.mjs check --system <dir> --package <spec> --plan <plan.json>
+//   node scripts/compose-code.mjs gate --system <dir> --package <spec> --plan <plan.json>
+//        --file <screen.tsx> --tokens <file> [--tokens <file>...]
+//
+// PLAN: { screen, file, components: [{ name, variants?: { [axis]: value } }] }
+//   `file` is resolved against the working directory. Sub-parts (CardHeader)
+//   come with their owner and need no entry. `gate` compares the file to the
+//   resolved plan, case-folded.
+//
+// Exit: 0 ok, 1 errors or failures, 2 usage or unreadable input.
+//
+// Spec: docs/specs/2026-10-13-compose-code-screen.md
+import { readFileSync, existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { parseArgs } from 'node:util';
+import { pathToFileURL } from 'node:url';
+import { normalizeName } from './lib/source-scan.mjs';
+import { nearestNames } from './lib/figma-compose.mjs';
+import {
+  extract, validate, formatReport, partOwner, blankComments,
+  buildTokenValues, skippedColourTokens, buildDimensionValues,
+} from './validate-adherence.mjs';
+
+export const COMPOSED_MARKER = (screen) => `// Composed by throughline: ${screen}.`;
+const MARKER_LINE = /^\/\/ Composed by throughline: (.*)\.$/;
+const DIRECTIVE = /^(['"])use [a-z]+\1;?$/;
+
+// The screen a file's marker names, '' for a file with no marker. The marker is
+// line 1, or line 2 after a directive ('use client').
+export function readMarker(text) {
+  const lines = String(text).split('\n').map((l) => l.trim());
+  const at = DIRECTIVE.test(lines[0] ?? '') ? 1 : 0;
+  return lines[at]?.match(MARKER_LINE)?.[1] ?? '';
+}
+
+export function codeInventory({ manifest, index, pkg }) {
+  const records = new Map((index?.components ?? []).map((c) => [normalizeName(c.name), c]));
+  const components = (manifest?.components?.built ?? []).map((name) => {
+    const r = records.get(normalizeName(name));
+    if (!r) return { name, documented: false, variants: {}, states: [] };
+    return {
+      name,
+      documented: true,
+      summary: r.summary,
+      whenToUse: r.whenToUse ?? [],
+      whenNotToUse: r.whenNotToUse ?? [],
+      variants: Object.fromEntries(Object.entries(r.variants ?? {}).map(([axis, values]) => [axis, Object.keys(values)])),
+      states: Object.keys(r.states ?? {}),
+    };
+  });
+  return { package: pkg, components };
+}
+
+const fold = (s) => normalizeName(s);
+const isObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+
+// existing: null (no file at plan.file) or the marker's screen name ('' unmarked).
+export function checkPlan(plan, inventory, { existing = null } = {}) {
+  const errors = [];
+  const err = (kind, path, asked, extra = {}) => errors.push({ kind, path, asked, ...extra });
+
+  if (!isObject(plan)) return { ok: false, errors: [{ kind: 'invalid', path: '', asked: plan }], plan: null };
+  for (const key of Object.keys(plan)) {
+    if (!['screen', 'file', 'components'].includes(key)) err('invalid', key, plan[key]);
+  }
+  if (typeof plan.screen !== 'string' || !plan.screen.trim()) err('invalid', 'screen', plan.screen);
+  if (typeof plan.file !== 'string' || !plan.file.trim()) err('invalid', 'file', plan.file);
+  if (!Array.isArray(plan.components)) err('invalid', 'components', plan.components);
+
+  if (existing !== null && existing !== plan.screen) err('name-taken', 'file', plan.file, { marked: existing || null });
+
+  const resolved = [];
+  for (const [i, c] of (Array.isArray(plan.components) ? plan.components : []).entries()) {
+    const path = `components[${i}]`;
+    if (!isObject(c) || typeof c.name !== 'string') { err('invalid', path, c); continue; }
+    for (const key of Object.keys(c)) if (!['name', 'variants'].includes(key)) err('invalid', `${path}.${key}`, c[key]);
+    const found = inventory.components.find((x) => fold(x.name) === fold(c.name));
+    // A sub-part (CardHeader) needs no entry, but one listed resolves to its owner.
+    const owner = found ? null : partOwner(c.name, inventory.components.map((x) => x.name));
+    if (owner) {
+      if (c.variants !== undefined) err('unknown-prop', `${path}.variants`, c.variants);
+      resolved.push({ name: c.name, partOf: owner, variants: {} });
+      continue;
+    }
+    if (!found) {
+      err('missing-component', `${path}.name`, c.name, { nearest: nearestNames(c.name, inventory.components.map((x) => x.name)) });
+      continue;
+    }
+    const variants = {};
+    if (c.variants !== undefined && !isObject(c.variants)) err('invalid', `${path}.variants`, c.variants);
+    for (const [axis, value] of Object.entries(isObject(c.variants) ? c.variants : {})) {
+      const realAxis = Object.keys(found.variants).find((a) => fold(a) === fold(axis));
+      if (!realAxis) { err('unknown-prop', `${path}.variants.${axis}`, axis); continue; }
+      const realValue = found.variants[realAxis].find((v) => fold(v) === fold(value));
+      if (!realValue) { err('unknown-option', `${path}.variants.${axis}`, value, { options: found.variants[realAxis] }); continue; }
+      variants[realAxis] = realValue;
+    }
+    resolved.push({ name: found.name, variants });
+  }
+
+  const ok = errors.length === 0;
+  return { ok, errors, plan: ok ? { screen: plan.screen, file: plan.file, components: resolved } : null };
+}
+
+// Default-scale Tailwind spacing, sizing, type-size and weight utilities, after
+// any variants (`md:`) and as negatives. Throughline's generated preset extends
+// only colours, radius and font family, so these are Tailwind's own values, not
+// tokens. Read anywhere in the file, so cn() and template strings count. Passes:
+// 0, fractions (`w-1/2`), keywords (`full`, `auto`, `screen`), preset names
+// (`text-primary`, `font-sans`) and `[var(--…)]`.
+const SCALE_UTILITY =
+  /(?<![\w-])(?:[\w-]+:)*-?(?:(?:p[xytrblse]?|m[xytrblse]?|gap(?:-[xy])?|space-[xy]|w|h|size|min-w|min-h|max-w|max-h|inset(?:-[xy])?|top|right|bottom|left|text|leading|tracking)-(?:0\.\d+|[1-9]\d*(?:\.\d+)?|px|xs|sm|base|lg|xl|[2-9]xl)|font-(?:thin|extralight|light|normal|medium|semibold|bold|extrabold|black))(?![\w/-])/g;
+// Sizing the gate doesn't read: an arbitrary size that isn't a variable, and a
+// width or height declaration with a raw length (percentages are layout).
+const RAW_SIZE = [
+  /(?<![\w-])(?:[\w-]+:)*(?:w|h|size|min-w|min-h|max-w|max-h)-\[(?!var\()(?!\d+(?:\.\d+)?(?:%|[dsl]?v[hw])\])[^\]\s]+\]/g,
+  /(?<![\w-])(?:min-?|max-?)?(?:[wW]idth|[hH]eight)\s*:\s*['"]?-?(?:\d+(?:\.\d+)?|\.\d+)(?:px|rem|em)?(?![\w%.])/g,
+];
+const NATIVE_CONTROL = /<(button|input|select|textarea)\b/g;
+// Every module reference: a static import (named, default, namespace,
+// type-only, side-effect), a re-export, a dynamic import() and a require().
+const ANY_IMPORT = [
+  /^\s*(?:import|export)\s+(?:[^'";]*?\s+from\s+)?['"]([^'"]+)['"]/gm,
+  /(?<![\w$.])(?:import|require)\s*\(\s*['"]([^'"]+)['"]/g,
+];
+const REACT = /^react(?:-dom)?(?:\/.*)?$/;
+
+const lineOf = (text, i) => text.slice(0, i).split('\n').length;
+
+export function gateFile({ file, text, plan, manifest, index, tokenDicts, pkg }) {
+  const marked = readMarker(text);
+  const extracted = extract(text, pkg, file);
+  const r = validate({
+    built: manifest?.components?.built ?? [],
+    index,
+    tokenValues: buildTokenValues(tokenDicts),
+    colourSkipped: skippedColourTokens(tokenDicts),
+    dimensionValues: buildDimensionValues(tokenDicts),
+    files: [{ path: file, ...extracted }],
+    walked: 1,
+  });
+
+  // On one file, known components that set no variant prop are normal; the plan
+  // check already validated every variant value against the same index.
+  const failures = r.failures.filter((f) => f.rule !== 'variant-rule-inert');
+  const advisories = [...r.advisories, ...r.failures.filter((f) => f.rule === 'variant-rule-inert')];
+
+  // Without the marker, the next run treats this file as a person's.
+  if (marked !== plan?.screen) failures.push({ rule: 'marker', written: marked || '(none)', expected: plan?.screen, file, line: 1 });
+
+  for (const l of extracted.literals) failures.push({ rule: 'raw-value', written: l.value, file, line: l.line });
+  for (const d of extracted.dimensions) failures.push({ rule: 'raw-value', written: d.written, file, line: d.line });
+
+  const code = blankComments(text, file);
+  for (const re of RAW_SIZE) for (const m of code.matchAll(re)) failures.push({ rule: 'raw-value', written: m[0], file, line: lineOf(code, m.index) });
+  for (const m of code.matchAll(SCALE_UTILITY)) failures.push({ rule: 'scale-utility', written: m[0], file, line: lineOf(code, m.index) });
+  for (const re of ANY_IMPORT) for (const m of code.matchAll(re)) {
+    const from = m[1];
+    if (from === pkg || from.startsWith(`${pkg}/`) || REACT.test(from)) continue;
+    failures.push({ rule: 'off-plan', written: `import from '${from}'`, file, line: lineOf(code, m.index + m[0].search(/\S/)) });
+  }
+  for (const m of code.matchAll(NATIVE_CONTROL)) failures.push({ rule: 'off-plan', written: `<${m[1]}>`, file, line: lineOf(code, m.index) });
+
+  const planned = (plan?.components ?? []).map((c) => c.partOf ?? c.name);
+  const plannedKeys = new Set(planned.map(fold));
+  for (const e of extracted.elements) {
+    if (plannedKeys.has(fold(e.component)) || partOwner(e.component, planned)) continue;
+    failures.push({ rule: 'off-plan', written: `<${e.component}>`, file, line: e.line });
+  }
+
+  return { ...r, ok: failures.length === 0, failures, advisories };
+}
+
+const COMPOSER_RULES = {
+  marker: (f) => `${f.file} is marked for ${f.written}, not "${f.expected}" — its first line (second after a directive) must be ${COMPOSED_MARKER(f.expected)}`,
+  'raw-value': (f) => `${f.written} at ${f.file}:${f.line} — write a token variable, not a raw value`,
+  'scale-utility': (f) => `${f.written} at ${f.file}:${f.line} — Tailwind's default scale, not a token; use a token variable (\`-[var(--…)]\`)`,
+  'off-plan': (f) => f.written.startsWith('import')
+    ? `${f.written} at ${f.file}:${f.line} — a composed screen imports only from the system's package and React; anything else is a gap to report`
+    : `${f.written} at ${f.file}:${f.line} — not a planned system component; use one from the plan, or check the plan again`,
+};
+
+export function formatGateReport(r) {
+  const own = r.failures.filter((f) => COMPOSER_RULES[f.rule]);
+  const lines = formatReport({ ...r, failures: r.failures.filter((f) => !COMPOSER_RULES[f.rule]) });
+  if (own.length) {
+    lines.push(`\n${own.length} composer failure(s):`);
+    for (const f of own) lines.push(`  - [${f.rule}] ${COMPOSER_RULES[f.rule](f)}`);
+  }
+  lines.push(r.ok ? '\ncompose-code gate: pass' : '\ncompose-code gate: FAIL');
+  return lines;
+}
+
+function main() {
+  const [mode, ...rest] = process.argv.slice(2);
+  let values;
+  try {
+    ({ values } = parseArgs({
+      args: rest,
+      options: {
+        system: { type: 'string' },
+        package: { type: 'string' },
+        tokens: { type: 'string', multiple: true, default: [] },
+        plan: { type: 'string' },
+        file: { type: 'string' },
+      },
+    }));
+  } catch (e) {
+    console.error(e.message);
+    process.exit(2);
+  }
+  const usage = () => {
+    console.error('usage: compose-code.mjs inventory|check|gate --system <dir> --package <spec> [--plan <file>] [--tokens <file> --tokens <file>...] [--file <path>]');
+    process.exit(2);
+  };
+  if (!['inventory', 'check', 'gate'].includes(mode) || !values.system || !values.package) usage();
+  if (mode !== 'inventory' && !values.plan) usage();
+  if (mode === 'gate' && (!values.file || values.tokens.length === 0)) usage();
+
+  const read = (p, what, parse = true) => {
+    try {
+      const text = readFileSync(p, 'utf8');
+      return parse ? JSON.parse(text) : text;
+    } catch (e) {
+      console.error(`cannot read ${what} at ${p}: ${e.message}`);
+      process.exit(2);
+    }
+  };
+  const manifest = read(join(values.system, 'design-system.json'), 'the manifest');
+  const index = read(join(values.system, 'design-system/docs/index.json'), 'the docs index (run docs:digest first)');
+  const inventory = codeInventory({ manifest, index, pkg: values.package });
+
+  if (mode === 'inventory') {
+    console.log(JSON.stringify(inventory, null, 2));
+    return;
+  }
+
+  const plan = read(values.plan, 'the plan');
+  if (mode === 'check') {
+    const target = typeof plan?.file === 'string' ? resolve(plan.file) : null;
+    const existing = target && existsSync(target) ? readMarker(read(target, 'the target file', false)) : null;
+    const res = checkPlan(plan, inventory, { existing });
+    console.log(JSON.stringify(res, null, 2));
+    process.exit(res.ok ? 0 : 1);
+  }
+
+  // The gate holds a file to a plan check accepts, never to a rejected one.
+  const checked = checkPlan(plan, inventory);
+  if (!checked.ok) {
+    console.error(`the plan doesn't check: ${checked.errors.map((e) => `${e.kind} at ${e.path}`).join(', ')}. Run check and fix it first.`);
+    process.exit(2);
+  }
+  const r = gateFile({
+    file: values.file,
+    text: read(values.file, 'the screen file', false),
+    plan: checked.plan,
+    manifest,
+    index,
+    tokenDicts: values.tokens.map((f) => read(f, 'a token source')),
+    pkg: values.package,
+  });
+  for (const line of formatGateReport(r)) console.log(line);
+  process.exit(r.ok ? 0 : 1);
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) main();

package/scripts/install.mjs

@@ -104,7 +104,8 @@ function stagePayload(srcRoot, destRoot, skip) {
 // renderer and the Figma checks reach Figma pre-inlined inside
 // references/doc-card-builder.md, references/figma-checks.md,
 // references/figma-adherence.md and references/figma-compose.md). Test fixtures
-// under lib/fixtures/ are dropped too.
+// under lib/fixtures/ are dropped too. lib/figma-compose.mjs is inlined the same
+// way but stays: compose-code.mjs imports nearestNames from it.
 const PLUGIN_INTERNAL = new Set([
   'install.mjs',
   'build-doc-card-builder.mjs',
@@ -116,7 +117,6 @@ const PLUGIN_INTERNAL = new Set([
   'lib/figma-variables-read.figma.js',
   'lib/figma-adherence.mjs',
   'lib/figma-adherence-read.figma.js',
-  'lib/figma-compose.mjs',
   'lib/figma-compose.figma.js',
 ]);