@radicool/throughline 0.25.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.25.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. |
@@ -109,6 +109,10 @@ This is the reliable entry point — it runs environment setup first, ahead of a
 
 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.
 
+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
@@ -116,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.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
+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,8 @@ 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`.
 - `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/component-builder.md

@@ -327,9 +327,11 @@ reference register, not this skill's guide voice.
   always last.
 - **Doc card body.** Render the card's `Usage` band with the canonical builder
   snippet in `.throughline/references/doc-card-builder.md` (via
-  `figma_execute` with an explicit `timeout`, one card per call): fill the
-  RECORD/CANONICAL_FP slots, resolve the nine required semantic variables and
-  the `Body/Default` text style per that file's call contract, run it, and
+  `figma_execute` with an explicit `timeout`, one card per call): assemble the
+  call with `node .throughline/scripts/doc-card-payload.mjs <record> <cardNodeId>`
+  (it fills the RECORD/CANONICAL_FP slots and resolves the nine semantic
+  variables and `Body/Default` per that file's call contract), run it, check
+  `summary.renderHash` against the `expectedRenderHash` it printed, and
   verify the returned summary (`rowsRendered`, `blocksCreated`, `cardWidth`) —
   not a screenshot. The builder creates the `Doc Fingerprint` node itself and
   is the only thing that may build the usage body — never hand-assemble it.

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/codex/prompts/compose-figma.md

@@ -0,0 +1,59 @@
+Compose the screen the user asked for in Figma, from what the file already has.
+Use the settings already in `design-system.json` (`figma.fileKey`) 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 compose in.
+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. **Read what exists.** Unless the user named them, ask which page holds the
+   component sets and which page the screen goes on (it's created if missing). Run
+   the snippet in `.throughline/references/figma-compose.md` verbatim, called
+   as its "How to call it" section says (`MODE` and `SPEC` declared above it,
+   `return await runCompose(MODE, SPEC);` below it), with `MODE = 'inventory'` and
+   `SPEC = { componentsPage }`. If the plan will set an instance-swap property (an
+   icon, say), ask which page holds the swap targets and run `inventory` again with
+   `iconsPage`.
+4. **Plan.** Write the screen description (its shape is the `DESCRIPTION` comment
+   in the snippet, at the top of the resolver) using only names from the
+   inventory's summary: component sets and their properties and options, variables
+   by kind, text styles, modes. Leave `sizing` off an instance unless it should
+   fill; `hug` works only on a set whose summary says `autoLayout: true`. Frames
+   carry layout only (auto layout, gap, padding, fill, stroke, radius); everything
+   the user sees is a component instance or styled text. When the request needs a
+   component the inventory doesn't have, say so before building and ask: leave it
+   out, use a named existing component instead, or stop. Never draw a lookalike
+   from frames.
+5. **Build.** Run the snippet with `MODE = 'build'` and
+   `SPEC = { componentsPage, iconsPage, description, fileKey }`. If it returns
+   errors, nothing was written: fix the description (a `missing-component` error
+   goes back to the user as in step 4) and build again. A `name-taken` error on
+   `<screen>` means a screen a person made already has that name: ask for another
+   name. On `WIP: <screen>` it means an unmarked frame holds the working name: ask
+   the user to rename or remove it. If the call throws instead, the build rolled
+   itself back and nothing was written: stop, and report the error as a composer
+   bug rather than reworking the screen around it.
+6. **Gate.** Run the screen gate in
+   `.throughline/references/figma-adherence.md` verbatim with
+   `TARGET = { page, screens: ['WIP: <screen>'], fileKey }` and `SKIP = []`. If it
+   fails, stop: report its failures as a composer bug, with their links, and leave
+   the `WIP:` frame for inspection. Don't change the description to make it pass.
+   Remove that frame with `MODE = 'discard'` and `SPEC = { page, screen }` only
+   when the user asks.
+7. **Finalize.** Run the snippet with `MODE = 'finalize'` and
+   `SPEC = { page, screen, fileKey }`. It replaces an earlier screen of that name
+   only if throughline composed it.
+8. **Review.** Dispatch the `reviewer` agent in Figma-visual mode with the screen's
+   node id (from finalize), the fileKey, the project's working directory (where
+   `design-system.json` is) and the user's request as its spec, unless the host
+   can't dispatch agents, in which case screenshot the screen yourself and say so.
+9. **Report.** The screen's link, whether it replaced an earlier one, the gate's
+   counts, the reviewer's verdict, and every gap: each component that was asked
+   for and doesn't exist, with the nearest names the script offered, and anything
+   left out of the request because of it.
+
+Never edit a component, a variable or a text style, and never write a raw value.
+If the screen can't be built from what the system has, the gap is the finding.
+

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

@@ -24,8 +24,9 @@ Ask which component to document (e.g. "Button"), then:
 2. **Project it.** Write `design-system/docs/components/<Name>.doc.json`, set the
    Figma component `description`, rebuild the doc card's `Usage` band with the
    canonical builder (`.throughline/references/doc-card-builder.md` —
-   verify its returned summary and stamp `surfaces.docCard.{src,render,renderer}`
-   from it), and (if the repo/code side exists) render MDX/JSDoc and run
+   assemble the call with `node .throughline/scripts/doc-card-payload.mjs`,
+   check the returned `renderHash` against the one it printed, verify the
+   returned summary and stamp `surfaces.docCard.{src,render,renderer}` from it), and (if the repo/code side exists) render MDX/JSDoc and run
    `docs:digest` per the `storybook-chromatic-builder` render step.
    Before the Figma writes, run the active-file preflight in
    `.throughline/references/figma-scripting.md` — this command writes

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/cursor/.cursor/commands/compose-figma.md

@@ -0,0 +1,59 @@
+Compose the screen the user asked for in Figma, from what the file already has.
+Use the settings already in `design-system.json` (`figma.fileKey`) 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 compose in.
+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. **Read what exists.** Unless the user named them, ask which page holds the
+   component sets and which page the screen goes on (it's created if missing). Run
+   the snippet in `.throughline/references/figma-compose.md` verbatim, called
+   as its "How to call it" section says (`MODE` and `SPEC` declared above it,
+   `return await runCompose(MODE, SPEC);` below it), with `MODE = 'inventory'` and
+   `SPEC = { componentsPage }`. If the plan will set an instance-swap property (an
+   icon, say), ask which page holds the swap targets and run `inventory` again with
+   `iconsPage`.
+4. **Plan.** Write the screen description (its shape is the `DESCRIPTION` comment
+   in the snippet, at the top of the resolver) using only names from the
+   inventory's summary: component sets and their properties and options, variables
+   by kind, text styles, modes. Leave `sizing` off an instance unless it should
+   fill; `hug` works only on a set whose summary says `autoLayout: true`. Frames
+   carry layout only (auto layout, gap, padding, fill, stroke, radius); everything
+   the user sees is a component instance or styled text. When the request needs a
+   component the inventory doesn't have, say so before building and ask: leave it
+   out, use a named existing component instead, or stop. Never draw a lookalike
+   from frames.
+5. **Build.** Run the snippet with `MODE = 'build'` and
+   `SPEC = { componentsPage, iconsPage, description, fileKey }`. If it returns
+   errors, nothing was written: fix the description (a `missing-component` error
+   goes back to the user as in step 4) and build again. A `name-taken` error on
+   `<screen>` means a screen a person made already has that name: ask for another
+   name. On `WIP: <screen>` it means an unmarked frame holds the working name: ask
+   the user to rename or remove it. If the call throws instead, the build rolled
+   itself back and nothing was written: stop, and report the error as a composer
+   bug rather than reworking the screen around it.
+6. **Gate.** Run the screen gate in
+   `.throughline/references/figma-adherence.md` verbatim with
+   `TARGET = { page, screens: ['WIP: <screen>'], fileKey }` and `SKIP = []`. If it
+   fails, stop: report its failures as a composer bug, with their links, and leave
+   the `WIP:` frame for inspection. Don't change the description to make it pass.
+   Remove that frame with `MODE = 'discard'` and `SPEC = { page, screen }` only
+   when the user asks.
+7. **Finalize.** Run the snippet with `MODE = 'finalize'` and
+   `SPEC = { page, screen, fileKey }`. It replaces an earlier screen of that name
+   only if throughline composed it.
+8. **Review.** Dispatch the `reviewer` agent in Figma-visual mode with the screen's
+   node id (from finalize), the fileKey, the project's working directory (where
+   `design-system.json` is) and the user's request as its spec, unless the host
+   can't dispatch agents, in which case screenshot the screen yourself and say so.
+9. **Report.** The screen's link, whether it replaced an earlier one, the gate's
+   counts, the reviewer's verdict, and every gap: each component that was asked
+   for and doesn't exist, with the nearest names the script offered, and anything
+   left out of the request because of it.
+
+Never edit a component, a variable or a text style, and never write a raw value.
+If the screen can't be built from what the system has, the gap is the finding.
+

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

@@ -24,8 +24,9 @@ Ask which component to document (e.g. "Button"), then:
 2. **Project it.** Write `design-system/docs/components/<Name>.doc.json`, set the
    Figma component `description`, rebuild the doc card's `Usage` band with the
    canonical builder (`.throughline/references/doc-card-builder.md` —
-   verify its returned summary and stamp `surfaces.docCard.{src,render,renderer}`
-   from it), and (if the repo/code side exists) render MDX/JSDoc and run
+   assemble the call with `node .throughline/scripts/doc-card-payload.mjs`,
+   check the returned `renderHash` against the one it printed, verify the
+   returned summary and stamp `surfaces.docCard.{src,render,renderer}` from it), and (if the repo/code side exists) render MDX/JSDoc and run
    `docs:digest` per the `storybook-chromatic-builder` render step.
    Before the Figma writes, run the active-file preflight in
    `.throughline/references/figma-scripting.md` — this command writes

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

@@ -331,9 +331,11 @@ reference register, not this skill's guide voice.
   always last.
 - **Doc card body.** Render the card's `Usage` band with the canonical builder
   snippet in `.throughline/references/doc-card-builder.md` (via
-  `figma_execute` with an explicit `timeout`, one card per call): fill the
-  RECORD/CANONICAL_FP slots, resolve the nine required semantic variables and
-  the `Body/Default` text style per that file's call contract, run it, and
+  `figma_execute` with an explicit `timeout`, one card per call): assemble the
+  call with `node .throughline/scripts/doc-card-payload.mjs <record> <cardNodeId>`
+  (it fills the RECORD/CANONICAL_FP slots and resolves the nine semantic
+  variables and `Body/Default` per that file's call contract), run it, check
+  `summary.renderHash` against the `expectedRenderHash` it printed, and
   verify the returned summary (`rowsRendered`, `blocksCreated`, `cardWidth`) —
   not a screenshot. The builder creates the `Doc Fingerprint` node itself and
   is the only thing that may build the usage body — never hand-assemble it.

package/adapters/generic/AGENTS.md

@@ -20,6 +20,8 @@ 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`.
 - `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/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/commands/compose-figma.md

@@ -0,0 +1,59 @@
+Compose the screen the user asked for in Figma, from what the file already has.
+Use the settings already in `design-system.json` (`figma.fileKey`) 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 compose in.
+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. **Read what exists.** Unless the user named them, ask which page holds the
+   component sets and which page the screen goes on (it's created if missing). Run
+   the snippet in `.throughline/references/figma-compose.md` verbatim, called
+   as its "How to call it" section says (`MODE` and `SPEC` declared above it,
+   `return await runCompose(MODE, SPEC);` below it), with `MODE = 'inventory'` and
+   `SPEC = { componentsPage }`. If the plan will set an instance-swap property (an
+   icon, say), ask which page holds the swap targets and run `inventory` again with
+   `iconsPage`.
+4. **Plan.** Write the screen description (its shape is the `DESCRIPTION` comment
+   in the snippet, at the top of the resolver) using only names from the
+   inventory's summary: component sets and their properties and options, variables
+   by kind, text styles, modes. Leave `sizing` off an instance unless it should
+   fill; `hug` works only on a set whose summary says `autoLayout: true`. Frames
+   carry layout only (auto layout, gap, padding, fill, stroke, radius); everything
+   the user sees is a component instance or styled text. When the request needs a
+   component the inventory doesn't have, say so before building and ask: leave it
+   out, use a named existing component instead, or stop. Never draw a lookalike
+   from frames.
+5. **Build.** Run the snippet with `MODE = 'build'` and
+   `SPEC = { componentsPage, iconsPage, description, fileKey }`. If it returns
+   errors, nothing was written: fix the description (a `missing-component` error
+   goes back to the user as in step 4) and build again. A `name-taken` error on
+   `<screen>` means a screen a person made already has that name: ask for another
+   name. On `WIP: <screen>` it means an unmarked frame holds the working name: ask
+   the user to rename or remove it. If the call throws instead, the build rolled
+   itself back and nothing was written: stop, and report the error as a composer
+   bug rather than reworking the screen around it.
+6. **Gate.** Run the screen gate in
+   `.throughline/references/figma-adherence.md` verbatim with
+   `TARGET = { page, screens: ['WIP: <screen>'], fileKey }` and `SKIP = []`. If it
+   fails, stop: report its failures as a composer bug, with their links, and leave
+   the `WIP:` frame for inspection. Don't change the description to make it pass.
+   Remove that frame with `MODE = 'discard'` and `SPEC = { page, screen }` only
+   when the user asks.
+7. **Finalize.** Run the snippet with `MODE = 'finalize'` and
+   `SPEC = { page, screen, fileKey }`. It replaces an earlier screen of that name
+   only if throughline composed it.
+8. **Review.** Dispatch the `reviewer` agent in Figma-visual mode with the screen's
+   node id (from finalize), the fileKey, the project's working directory (where
+   `design-system.json` is) and the user's request as its spec, unless the host
+   can't dispatch agents, in which case screenshot the screen yourself and say so.
+9. **Report.** The screen's link, whether it replaced an earlier one, the gate's
+   counts, the reviewer's verdict, and every gap: each component that was asked
+   for and doesn't exist, with the nearest names the script offered, and anything
+   left out of the request because of it.
+
+Never edit a component, a variable or a text style, and never write a raw value.
+If the screen can't be built from what the system has, the gap is the finding.
+

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

@@ -24,8 +24,9 @@ Ask which component to document (e.g. "Button"), then:
 2. **Project it.** Write `design-system/docs/components/<Name>.doc.json`, set the
    Figma component `description`, rebuild the doc card's `Usage` band with the
    canonical builder (`.throughline/references/doc-card-builder.md` —
-   verify its returned summary and stamp `surfaces.docCard.{src,render,renderer}`
-   from it), and (if the repo/code side exists) render MDX/JSDoc and run
+   assemble the call with `node .throughline/scripts/doc-card-payload.mjs`,
+   check the returned `renderHash` against the one it printed, verify the
+   returned summary and stamp `surfaces.docCard.{src,render,renderer}` from it), and (if the repo/code side exists) render MDX/JSDoc and run
    `docs:digest` per the `storybook-chromatic-builder` render step.
    Before the Figma writes, run the active-file preflight in
    `.throughline/references/figma-scripting.md` — this command writes

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

@@ -327,9 +327,11 @@ reference register, not this skill's guide voice.
   always last.
 - **Doc card body.** Render the card's `Usage` band with the canonical builder
   snippet in `.throughline/references/doc-card-builder.md` (via
-  `figma_execute` with an explicit `timeout`, one card per call): fill the
-  RECORD/CANONICAL_FP slots, resolve the nine required semantic variables and
-  the `Body/Default` text style per that file's call contract, run it, and
+  `figma_execute` with an explicit `timeout`, one card per call): assemble the
+  call with `node .throughline/scripts/doc-card-payload.mjs <record> <cardNodeId>`
+  (it fills the RECORD/CANONICAL_FP slots and resolves the nine semantic
+  variables and `Body/Default` per that file's call contract), run it, check
+  `summary.renderHash` against the `expectedRenderHash` it printed, and
   verify the returned summary (`rowsRendered`, `blocksCreated`, `cardWidth`) —
   not a screenshot. The builder creates the `Doc Fingerprint` node itself and
   is the only thing that may build the usage body — never hand-assemble it.

package/package.json

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