@radicool/throughline 0.25.0 → 0.26.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.26.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,8 @@ 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.
+
 Update anytime with `/plugin marketplace update throughline-marketplace`.
 
 #### Cursor, Codex, or a generic AGENTS.md agent
@@ -116,9 +118,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.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
 ```
 
 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-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-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-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,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-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-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.26.0",
   "description": "Build a complete design system end to end — author in Figma, sync tokens to code, generate Storybook. Usable from Claude Code, Cursor, Codex, or any AGENTS.md agent.",
   "type": "module",
   "bin": {

package/references/doc-card-builder.md

@@ -14,6 +14,18 @@ it reads the specimen and never writes it. The status chip keeps its own owner
 
 ## How to call it
 
+Steps 1–4 are one command once `figma.docCardVariables` is recorded:
+
+```sh
+node scripts/doc-card-payload.mjs design-system/docs/components/<Name>.doc.json <cardNodeId> --out <scratch>/payload.js
+```
+
+It writes the complete `figma_execute` body — record, fingerprint, the nine
+role lookups by recorded name, `Body/Default`, the snippet and the call — and
+prints the `expectedRenderHash` to stderr. Pass the file's contents as the
+`code` unchanged, then do steps 5–6. The steps below are what it does, and
+what to do by hand when the mapping isn't recorded yet.
+
 1. Load the record and compute its canonical fingerprint in Node
    (`canonicalFingerprint` in `scripts/lib/doc-record.mjs`).
 2. Read `figma.docCardVariables` from `design-system.json`.
@@ -82,6 +94,10 @@ const summary = await renderDocCard({ card, record: RECORD, vars, bodyTextStyle
    `cardWidth` — not from a screenshot, then stamp the manifest from it:
    `surfaces.docCard = { src: summary.fingerprint, render: summary.renderHash,
    renderer: summary.rendererVersion }`. Never re-read the card to stamp.
+   With the payload script, first check `summary.renderHash` equals the
+   `expectedRenderHash` it printed. A mismatch means the payload changed on
+   the way in, or `Body/Default` isn't the size the script assumed — the
+   summary's `bodyFontSize` says which; re-run with `--font-size`.
 
 ## The snippet
 
@@ -188,20 +204,11 @@ function planDocCard(record, bodyTextStyle) {
   };
 }
 
-// Figma plugin-API renderer for the doc-card Usage band. This file is NOT a
-// Node module — build-doc-card-builder.mjs concatenates it after the inlined
-// planner (doc-card-plan.mjs) into references/doc-card-builder.md, and the
-// result runs inside figma_execute (dynamic-page mode). Constraints honored
-// here (see references/figma-scripting.md): async APIs only, style/font set
-// BEFORE .characters, fonts loaded up front, resize() sizing modes re-asserted,
-// bound paints seeded light-gray (never pure black).
-//
-// In-scope globals when assembled: planDocCard, DOC_CARD_RENDERER_VERSION
-// (inlined planner) and the caller-filled slots RECORD, CANONICAL_FP.
-
-// 32-bit FNV-1a — the render hash. Only ever compared against itself (the
-// manifest's surfaces.docCard.render), so it does not need to match the
-// sha256-based canonical fingerprint, which cannot run in the Figma sandbox.
+// 32-bit FNV-1a — the render hash: fnv1a(JSON.stringify(plan)). Only ever
+// compared against itself (the manifest's surfaces.docCard.render), so it does
+// not need to match the sha256-based canonical fingerprint, which cannot run in
+// the Figma sandbox. Lives here, not in the renderer, so Node can compute the
+// hash a render should return (doc-card-payload.mjs) with the same code.
 function fnv1a(str) {
   let h = 0x811c9dc5;
   for (let i = 0; i < str.length; i++) {
@@ -211,6 +218,40 @@ function fnv1a(str) {
   return h.toString(16).padStart(8, '0');
 }
 
+// When a header's title row has no node named `Status Pill`/`Status`, name the
+// node that most likely IS the chip so the error can say what to rename. Never
+// used to pick a node to write — the renderer still refuses to guess. A
+// candidate is a FRAME below the title row whose only child is a TEXT node
+// (the chip shape: a pill frame around its label). Exactly one candidate or
+// no hint. Reads only type/name/id/characters/children, so it runs on Figma
+// nodes and on plain test objects alike.
+function statusChipHint(titleRow) {
+  if (!titleRow || titleRow.type !== 'FRAME') return null;
+  const found = [];
+  const walk = (node) => {
+    for (const child of node.children || []) {
+      if (child.type === 'FRAME' && child.children && child.children.length === 1
+        && child.children[0].type === 'TEXT') {
+        found.push({ id: child.id, name: child.name, label: child.children[0].characters });
+      }
+      walk(child);
+    }
+  };
+  walk(titleRow);
+  return found.length === 1 ? found[0] : null;
+}
+
+// Figma plugin-API renderer for the doc-card Usage band. This file is NOT a
+// Node module — build-doc-card-builder.mjs concatenates it after the inlined
+// planner (doc-card-plan.mjs) into references/doc-card-builder.md, and the
+// result runs inside figma_execute (dynamic-page mode). Constraints honored
+// here (see references/figma-scripting.md): async APIs only, style/font set
+// BEFORE .characters, fonts loaded up front, resize() sizing modes re-asserted,
+// bound paints seeded light-gray (never pure black).
+//
+// In-scope globals when assembled: planDocCard, DOC_CARD_RENDERER_VERSION,
+// fnv1a, statusChipHint (inlined planner) and the caller-filled slots RECORD, CANONICAL_FP.
+
 const REQUIRED_VARS = [
   'textDefault', 'textMuted', 'tonePositive', 'toneNegative', 'border',
   'spacePadding', 'spaceRowGap', 'spaceBlockGap', 'spaceItemGap',
@@ -341,7 +382,13 @@ async function renderDocCard({ card, record, vars, bodyTextStyle }) {
   const descAmbiguous = !named && descCandidates.length > 1;
 
   const missingAnchors = [];
-  if (!hasStatusAnchor) missingAnchors.push('status (title row must contain a descendant named "Status Pill" or "Status")');
+  if (!hasStatusAnchor) {
+    const hint = statusChipHint(titleRow);
+    missingAnchors.push('status (title row must contain a descendant named "Status Pill" or "Status"'
+      + (hint ? ' — frame ' + hint.id + ' "' + hint.name + '" holding "' + hint.label
+        + '" looks like the status chip; rename it "Status Pill" and re-run' : '')
+      + ')');
+  }
   if (!headerDescCandidate) {
     missingAnchors.push(descAmbiguous
       ? 'description (found ' + descCandidates.length + ' candidate TEXT children, cannot tell which is the description — name the right one "Header Description" by hand and re-run)'

package/references/figma-adherence.md

@@ -345,6 +345,19 @@ function overriddenRecords(instance, path, underDetached) {
   return records;
 }
 
+// The SLOT nodes on this instance's own surface: its slots, and the slots of
+// instances nested in its component, reached only through component sublayers
+// (ids 'I…'). A slot inside content added to a slot is left out here; the walk
+// reaches it through that content.
+function slotsOf(instance) {
+  return instance.findAll((n) => n.type === 'SLOT').filter((slot) => {
+    for (let node = slot.parent; node && node !== instance; node = node.parent) {
+      if (!String(node.id).startsWith('I')) return false;
+    }
+    return true;
+  });
+}
+
 function screensOn(page, names) {
   const all = [];
   for (const top of page.children) {
@@ -405,6 +418,14 @@ async function readScreens(target) {
     if (node.visible === false) return;
     if (node.type === 'INSTANCE') {
       nodes.push(...overriddenRecords(node, path, insideDetached));
+      // Content added to a slot is the screen's own, and isn't listed in
+      // instance.overrides. A slot's placeholder children keep instance-sublayer
+      // ids ('I…;…') and stay part of the component.
+      for (const slot of slotsOf(node)) {
+        for (const child of slot.children) {
+          if (!String(child.id).startsWith('I')) walk(child, `${path} / ${slot.name} / ${child.name}`, false, insideDetached);
+        }
+      }
       return;
     }
     const mixedPaints = node.fills === figma.mixed;