@radicool/throughline 0.24.0 → 0.26.0

package/scripts/README.md

@@ -25,13 +25,19 @@ tested here; copied verbatim by `token-crosswalk-builder` into the user's
 | `lib/doc-card-render.figma.js` | Figma renderer template for the doc card's `Usage` band and header. Inlined into `references/doc-card-builder.md`; never executed as a module. | plugin-internal (not installed) |
 | `lib/figma-checks.mjs` | Pure checker for the Figma stop conditions: the COMPONENT_SET assertion against the full matrix, the state matrix, the focus ring, and the focus ring's 3:1 contrast against the surfaces it's named to sit on, plus the focus-framework rules. Inlined into `references/figma-checks.md`; unit-tested against `lib/fixtures/figma-checks/`. | plugin-internal (not installed) |
 | `lib/figma-checks-read.figma.js` | Figma reader that turns the live COMPONENT_SET into the checker's snapshot JSON. Inlined into `references/figma-checks.md`; never executed as a module. | plugin-internal (not installed) |
+| `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.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` |
 | `lib/proof.mjs` | The proof store's vocabulary and mechanics: the stage list, entry validation, latest-wins merge, and the fingerprint the manifest pointer carries. | copied alongside `verify-check.mjs` |
 | `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 |
 | `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` and `lib/figma-checks.mjs` above the reader (`lib/figma-checks-read.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) |
 | `build-native-adapter-config.mjs` | Generate `references/native-adapter-config.md` by slicing `lib/sd-native.mjs` on its `@doc-section` markers and interleaving each fragment under its prose. Fails when module code falls outside every section, so the doc cannot silently ship incomplete. `--check` gates CI. | plugin-internal (not installed) |
 
@@ -249,7 +255,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.24.0 init --target=cursor|codex|generic
+    npx @radicool/throughline@0.26.0 init --target=cursor|codex|generic
 
 See `scripts/install.mjs` (pure core + CLI + `install.test.mjs`).
 

package/scripts/build-doc-card-builder.mjs

@@ -29,6 +29,18 @@ const HEADER = [
   '',
   '## 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`.',
@@ -97,6 +109,10 @@ const HEADER = [
   '   `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',
   '',

package/scripts/build-figma-checks.mjs

@@ -1,10 +1,18 @@
-// Generates references/figma-checks.md — the canonical figma_execute snippet
-// that runs the Figma stop conditions (COMPONENT_SET assertion, state matrix,
-// focus ring, focus-ring contrast) — by inlining the state table
-// (lib/component-states.mjs), the contrast maths (lib/contrast.mjs) and the
-// pure checker (lib/figma-checks.mjs) above the Figma reader
-// (lib/figma-checks-read.figma.js). Mirrors build-doc-card-builder.mjs: run
-// bare to write, run with --check to gate CI. Zero dependencies.
+// Generates the two canonical figma_execute snippets by inlining tested Node
+// modules above their Figma readers:
+//   references/figma-checks.md — the Figma stop conditions (COMPONENT_SET
+//     assertion, state matrix, focus ring, focus-ring contrast): the state table
+//     (lib/component-states.mjs), the contrast maths (lib/contrast.mjs) and the pure
+//     checker (lib/figma-checks.mjs), then lib/figma-variables-read.figma.js and the
+//     reader (lib/figma-checks-read.figma.js).
+//   references/figma-adherence.md — the screen adherence gate: the pure checker
+//     (lib/figma-adherence.mjs), then lib/figma-variables-read.figma.js and the
+//     screen reader (lib/figma-adherence-read.figma.js).
+//   references/figma-compose.md — screen composition: lib/figma-adherence.mjs (for
+//     dimensionBuckets), the pure resolver (lib/figma-compose.mjs),
+//     lib/figma-variables-read.figma.js, then the writer (lib/figma-compose.figma.js).
+// Mirrors build-doc-card-builder.mjs: run bare to write all three, run with --check
+// to gate CI on all three. Zero dependencies.
 import { readFileSync, writeFileSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
@@ -14,9 +22,16 @@ const STATES = join(REPO_ROOT, 'scripts', 'lib', 'component-states.mjs');
 const CONTRAST = join(REPO_ROOT, 'scripts', 'lib', 'contrast.mjs');
 const CHECKER = join(REPO_ROOT, 'scripts', 'lib', 'figma-checks.mjs');
 const READER = join(REPO_ROOT, 'scripts', 'lib', 'figma-checks-read.figma.js');
+const VARIABLES = join(REPO_ROOT, 'scripts', 'lib', 'figma-variables-read.figma.js');
+const ADHERENCE = join(REPO_ROOT, 'scripts', 'lib', 'figma-adherence.mjs');
+const ADHERENCE_READER = join(REPO_ROOT, 'scripts', 'lib', 'figma-adherence-read.figma.js');
+const COMPOSE = join(REPO_ROOT, 'scripts', 'lib', 'figma-compose.mjs');
+const COMPOSE_WRITER = join(REPO_ROOT, 'scripts', 'lib', 'figma-compose.figma.js');
 const OUT = join(REPO_ROOT, 'references', 'figma-checks.md');
+const ADHERENCE_OUT = join(REPO_ROOT, 'references', 'figma-adherence.md');
+const COMPOSE_OUT = join(REPO_ROOT, 'references', 'figma-compose.md');
 
-const BIND = 'const { checkSpec, checkBuilt } = withTable({ resolveArchetype, BASELINE_STATES, STATE_SYNONYMS, normalizeName, contrastRatio, composite, parseHex, AA_NON_TEXT });';
+const BIND = 'const { checkSpec, checkBuilt, checkExisting } = withTable({ resolveArchetype, BASELINE_STATES, STATE_SYNONYMS, normalizeName, contrastRatio, composite, parseHex, AA_NON_TEXT });';
 
 const HEADER = [
   '# Figma stop-condition checks (GENERATED)',
@@ -45,7 +60,7 @@ const HEADER = [
   '     component sits on, copied from the architect\'s spec. Without it the',
   '     focus-contrast check is skipped. Surfaces are looked up among the file\'s',
   '     local variables only.',
-  '   - `const MODE = \'spec\'` or `\'built\'`.',
+  '   - `const MODE = \'spec\'`, `\'built\'` or `\'existing\'`.',
   '2. End the script with `return await runFigmaChecks(EXPECT, MODE);` and pass',
   '   `timeout: 30000`.',
   '3. Read the result, `{ pass, checks: [{ name, result, detail }] }`. `result` is',
@@ -59,6 +74,18 @@ const HEADER = [
   '   COMPONENT_SET inside the frame named `WIP: <name>` on the current page and runs',
   '   in the self-verify loop. It throws only if that frame is missing; a frame with',
   '   no set, or a set Figma reports as conflicting, fails the structural check.',
+  '5. `\'existing\'` checks a set already in the library, read-only: the first',
+  '   COMPONENT_SET whose name matches `name` ignoring case and punctuation. Add',
+  '   `page` to `EXPECT` (the page holding the components) so only that page is',
+  '   loaded; without it every page loads in turn, which on a large file can stall',
+  '   the bridge. `matrix` is not needed. There is no spec to copy `controlLayer` and',
+  '   `surfaces` from, so the caller names them: `surfaces` as for a build, and',
+  '   `controlLayer` for a wrapped control whose ring sits on an inner layer (without',
+  '   it, a correct ring on an inner layer reads as missing). It runs the state,',
+  '   focus-ring and focus-contrast checks against the set\'s own variants, not the',
+  '   structural check. A set whose focus state is drawn some other way, such as an',
+  '   INSIDE stroke, fails the focus-ring check and skips contrast. It throws when no',
+  '   set has that name.',
   '',
   '```js',
   'const EXPECT = { name: \'Chip\', matrix: { state: [\'default\', \'hover\'] }, uiFramework: \'shadcn\' };',
@@ -72,21 +99,155 @@ const HEADER = [
   '```js',
 ].join('\n');
 
+const ADHERENCE_HEADER = [
+  '# Figma screen adherence gate (GENERATED)',
+  '',
+  '> **GENERATED FILE — do not edit by hand.** Sources: `scripts/lib/figma-adherence.mjs`',
+  '> (the pure checker, unit-tested in Node), `scripts/lib/figma-variables-read.figma.js`',
+  '> (colour-variable resolution) + `scripts/lib/figma-adherence-read.figma.js` (the',
+  '> screen reader). Regenerate with `node scripts/build-figma-checks.mjs`; CI gates',
+  '> freshness with `--check`.',
+  '',
+  'The canonical `figma_execute` snippet that checks Figma screens against the design',
+  'system, read-only. It fails a frame detached from a component, a raw colour that a',
+  'colour variable has (opacity included), and a raw gap, padding or corner radius',
+  'that a spacing or radius variable has, naming the variable to bind. A number',
+  'variable counts by its scope (`GAP`, `CORNER_RADIUS`), or, left at `ALL_SCOPES`,',
+  'by a name that says spacing or radius. A raw value no variable has is an',
+  'advisory, not a failure. A rule that had nothing to compare against fails by name',
+  '(`nothing-scanned`, `colour-rule-inert`, `dimension-rule-inert`). The script is the',
+  'rule; do not re-write it by hand.',
+  '',
+  '## How to call it',
+  '',
+  '1. Paste the snippet below into `figma_execute`, with the two slots filled above it:',
+  '   - `const TARGET = { page, screens, fileKey }` — `page` is the page name (an exact',
+  '     match, or else the one page whose name matches once leading and trailing',
+  '     spaces are trimmed); `screens` is an optional list of screen names (top-level',
+  '     frames, or frames directly inside a top-level section), and without it every',
+  '     screen on the page is read; `fileKey` is `figma.fileKey` from',
+  '     `design-system.json`, used for the links.',
+  '   - `const SKIP = []` — rule names to switch off (`detached-component`,',
+  '     `raw-colour`, `raw-dimension`); a skipped rule\'s inert check is skipped too.',
+  '2. End the script with `return await runScreenGate(TARGET, SKIP);` and pass',
+  '   `timeout: 30000`.',
+  '3. Read the result, `{ pass, failures, advisories, counts, skipped }`. Each failure',
+  '   and advisory has `rule`, `path`, `detail` and a `link` to the node. Report every',
+  '   failure with its link. Never edit the file to make it pass.',
+  '4. Only the named page is loaded, and tokens are the file\'s local variables. A file',
+  '   whose variables all come from a published library fails as inert.',
+  '',
+  '```js',
+  'const TARGET = { page: \'Templates\', fileKey: \'<figma.fileKey>\' };',
+  'const SKIP = [];',
+  '// … the generated snippet …',
+  'return await runScreenGate(TARGET, SKIP);',
+  '```',
+  '',
+  '## The snippet',
+  '',
+  '```js',
+].join('\n');
+
+const COMPOSE_HEADER = [
+  '# Figma screen composition (GENERATED)',
+  '',
+  '> **GENERATED FILE — do not edit by hand.** Sources: `scripts/lib/figma-adherence.mjs`',
+  '> (for `dimensionBuckets`), `scripts/lib/figma-compose.mjs` (the pure resolver,',
+  '> unit-tested in Node), `scripts/lib/figma-variables-read.figma.js` +',
+  '> `scripts/lib/figma-compose.figma.js` (the reader and writer). Regenerate with',
+  '> `node scripts/build-figma-checks.mjs`; CI gates freshness with `--check`.',
+  '',
+  'The canonical `figma_execute` snippet that composes a screen from the file\'s own',
+  'component sets, variables and text styles. A screen is a short JSON description',
+  'written only in those names (its shape is the `DESCRIPTION` comment in the',
+  'snippet, at the top of the resolver).',
+  'The whole description is checked before anything is written: an unknown component,',
+  'property, option, variable or text style, a variable of the wrong kind, or a name',
+  'already held by a screen a person made, comes back as a list of errors and the file',
+  'is untouched. A component the file lacks is a `missing-component` error with the',
+  'nearest names: report it as a gap, never draw a lookalike. Every value the script',
+  'writes is bound to a variable. The script is the rule; do not re-write it by hand.',
+  '',
+  '## How to call it',
+  '',
+  '1. Paste the snippet below into `figma_execute` with `timeout: 30000`, and end it',
+  '   with `return await runCompose(MODE, SPEC);`, one mode per call:',
+  '   - `\'inventory\'`, `SPEC = { componentsPage, iconsPage }`: read-only. Returns',
+  '     `{ summary }`: each set\'s properties and options and whether it has auto',
+  '     layout, swap targets, variables by kind (colour, gap, radius), text styles and',
+  '     modes. Plan only from these names.',
+  '     `iconsPage` is optional; pass it when a swap property needs its targets.',
+  '   - `\'build\'`, `SPEC = { componentsPage, iconsPage, description, fileKey }`:',
+  '     returns `{ ok: false, errors }` with nothing written, or builds the screen into',
+  '     a top-level frame `WIP: <screen>` on the description\'s page (created if',
+  '     missing) and returns `{ ok: true, wipId, wipName, link, ms }`. A throw during',
+  '     the write removes the `WIP:` frame (and a page the build created) before it',
+  '     rethrows, so nothing is left half-built: report it as a composer bug.',
+  '   - `\'finalize\'`, `SPEC = { page, screen, fileKey }`: renames `WIP: <screen>` to',
+  '     `<screen>`, replacing a screen of that name only if throughline composed it.',
+  '     Returns `{ id, link, replaced }`.',
+  '   - `\'discard\'`, `SPEC = { page, screen }`: removes `WIP: <screen>`. Only when',
+  '     the user asks.',
+  '2. Between `build` and `finalize`, run the screen gate',
+  '   (`references/figma-adherence.md`) with `screens: [\'WIP: <screen>\']`. Finalize',
+  '   only a passing screen. A failure is a composer bug: report it and leave the',
+  '   `WIP:` frame.',
+  '3. Pages are found by exact name, or else the one page whose trimmed name matches.',
+  '   Only the named pages are loaded. Components and variables are the file\'s local',
+  '   ones.',
+  '',
+  '```js',
+  'const MODE = \'build\';',
+  'const SPEC = { componentsPage: \'Components\', iconsPage: \'Icons\', fileKey: \'<figma.fileKey>\', description: {',
+  '  screen: \'Sign in\', page: \'Screens\', width: 390, modes: { \'Color / Semantic\': \'Light\' },',
+  '  root: { layout: \'vertical\', gap: \'space/gap/md\', padding: \'space/inset/lg\', fill: \'color/bg/canvas\', children: [',
+  '    { text: \'Sign in\', style: \'Heading/L\', color: \'color/text/primary\' },',
+  '    { component: \'Input\', props: { placeholder: \'Email\' }, sizing: { horizontal: \'fill\' } },',
+  '    { component: \'Button\', props: { label: \'Sign in\', hasTrailing: true, trailingIcon: \'icon/arrow-right\' } },',
+  '  ] },',
+  '} };',
+  '// … the generated snippet …',
+  'return await runCompose(MODE, SPEC);',
+  '```',
+  '',
+  '## The snippet',
+  '',
+  '```js',
+].join('\n');
+
 const FOOTER = ['```', ''].join('\n');
 
 const stripExports = (src) =>
   src.replace(/^export const /gm, 'const ').replace(/^export function /gm, 'function ');
 
-export function buildFigmaChecks({ statesSource, contrastSource, checkerSource, readerSource }) {
-  const states = stripExports(statesSource);
-  const contrast = stripExports(contrastSource);
-  const checker = stripExports(checkerSource);
-  for (const [name, src] of [['component-states.mjs', states], ['contrast.mjs', contrast], ['figma-checks.mjs', checker], ['figma-checks-read.figma.js', readerSource]]) {
+function assertInlinable(sources) {
+  for (const [name, src] of sources) {
     if (/^\s*(import|export)\b/m.test(src)) {
       throw new Error(`${name} must stay import-free (only top-level \`export const\`/\`export function\` allowed) — it is inlined into the Figma snippet where no module system exists`);
     }
   }
-  return `${HEADER}\n${states}\n${contrast}\n${checker}\n${BIND}\n\n${readerSource}${FOOTER}`;
+}
+
+export function buildFigmaChecks({ statesSource, contrastSource, checkerSource, variablesSource, readerSource }) {
+  const states = stripExports(statesSource);
+  const contrast = stripExports(contrastSource);
+  const checker = stripExports(checkerSource);
+  assertInlinable([['component-states.mjs', states], ['contrast.mjs', contrast], ['figma-checks.mjs', checker], ['figma-variables-read.figma.js', variablesSource], ['figma-checks-read.figma.js', readerSource]]);
+  return `${HEADER}\n${states}\n${contrast}\n${checker}\n${BIND}\n\n${variablesSource}\n${readerSource}${FOOTER}`;
+}
+
+export function buildFigmaAdherence({ checkerSource, variablesSource, readerSource }) {
+  const checker = stripExports(checkerSource);
+  assertInlinable([['figma-adherence.mjs', checker], ['figma-variables-read.figma.js', variablesSource], ['figma-adherence-read.figma.js', readerSource]]);
+  return `${ADHERENCE_HEADER}\n${checker}\n${variablesSource}\n${readerSource}${FOOTER}`;
+}
+
+export function buildFigmaCompose({ adherenceSource, composeSource, variablesSource, writerSource }) {
+  const adherence = stripExports(adherenceSource);
+  const compose = stripExports(composeSource);
+  assertInlinable([['figma-adherence.mjs', adherence], ['figma-compose.mjs', compose], ['figma-variables-read.figma.js', variablesSource], ['figma-compose.figma.js', writerSource]]);
+  return `${COMPOSE_HEADER}\n${adherence}\n${compose}\n${variablesSource}\n${writerSource}${FOOTER}`;
 }
 
 if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
@@ -94,18 +255,42 @@ if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href)
     statesSource: readFileSync(STATES, 'utf8'),
     contrastSource: readFileSync(CONTRAST, 'utf8'),
     checkerSource: readFileSync(CHECKER, 'utf8'),
+    variablesSource: readFileSync(VARIABLES, 'utf8'),
     readerSource: readFileSync(READER, 'utf8'),
   });
+  const adherence = buildFigmaAdherence({
+    checkerSource: readFileSync(ADHERENCE, 'utf8'),
+    variablesSource: readFileSync(VARIABLES, 'utf8'),
+    readerSource: readFileSync(ADHERENCE_READER, 'utf8'),
+  });
+  const compose = buildFigmaCompose({
+    adherenceSource: readFileSync(ADHERENCE, 'utf8'),
+    composeSource: readFileSync(COMPOSE, 'utf8'),
+    variablesSource: readFileSync(VARIABLES, 'utf8'),
+    writerSource: readFileSync(COMPOSE_WRITER, 'utf8'),
+  });
+  const outputs = [
+    [OUT, result, 'references/figma-checks.md', 'figma checks'],
+    [ADHERENCE_OUT, adherence, 'references/figma-adherence.md', 'figma adherence'],
+    [COMPOSE_OUT, compose, 'references/figma-compose.md', 'figma compose'],
+  ];
   if (process.argv.includes('--check')) {
-    let onDisk = null;
-    try { onDisk = readFileSync(OUT, 'utf8'); } catch { /* missing counts as drift */ }
-    if (onDisk !== result) {
-      console.error('✗ references/figma-checks.md out of date; run: node scripts/build-figma-checks.mjs');
-      process.exit(1);
+    let stale = false;
+    for (const [path, content, label, what] of outputs) {
+      let onDisk = null;
+      try { onDisk = readFileSync(path, 'utf8'); } catch { /* missing counts as drift */ }
+      if (onDisk !== content) {
+        console.error(`✗ ${label} out of date; run: node scripts/build-figma-checks.mjs`);
+        stale = true;
+      } else {
+        console.log(`✓ ${what} in sync`);
+      }
     }
-    console.log('✓ figma checks in sync');
+    if (stale) process.exit(1);
   } else {
-    writeFileSync(OUT, result);
-    console.log('✓ wrote references/figma-checks.md');
+    for (const [path, content, label] of outputs) {
+      writeFileSync(path, content);
+      console.log(`✓ wrote ${label}`);
+    }
   }
 }

package/scripts/doc-card-payload.mjs

@@ -0,0 +1,115 @@
+// Assembles the complete figma_execute payload that renders one component doc
+// card — steps 1–4 of "How to call it" in references/doc-card-builder.md — so
+// the caller passes one file's contents instead of hand-splicing the record,
+// fingerprint, variable lookups and generated snippet. Also prints the
+// renderHash the render must return: the payload is pasted into the tool call,
+// and a matching hash proves it arrived intact.
+//
+//   node scripts/doc-card-payload.mjs <record.doc.json> <cardNodeId>
+//        [--manifest design-system.json] [--out payload.js] [--font-size 16]
+//
+// Zero dependencies. Reads the generated snippet from ../references, which sits
+// beside scripts/ both in the plugin and in an adapter install's .throughline/.
+import { readFileSync, writeFileSync } from 'node:fs';
+import { join, dirname, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { canonicalFingerprint } from './lib/doc-record.mjs';
+import { planDocCard, fnv1a } from './lib/doc-card-plan.mjs';
+
+const BUILDER = join(dirname(fileURLToPath(import.meta.url)), '..', 'references', 'doc-card-builder.md');
+
+const ROLES = [
+  'textDefault', 'textMuted', 'tonePositive', 'toneNegative', 'border',
+  'spacePadding', 'spaceRowGap', 'spaceBlockGap', 'spaceItemGap',
+];
+
+// The text between "## The snippet"'s opening ```js fence and its closing fence.
+export function extractSnippet(builderMarkdown) {
+  const section = builderMarkdown.split('\n## The snippet\n')[1];
+  if (!section) throw new Error('doc-card-builder.md has no "## The snippet" section');
+  const start = section.indexOf('```js\n');
+  const end = section.lastIndexOf('\n```');
+  if (start === -1 || end <= start) throw new Error('doc-card-builder.md: snippet fence not found');
+  return section.slice(start + '```js\n'.length, end + 1);
+}
+
+export function buildPayload({ record, cardNodeId, manifest, builderMarkdown, fontSize = 16 }) {
+  if (!/^\d+:\d+$/.test(cardNodeId)) throw new Error(`cardNodeId must look like "24:773", got "${cardNodeId}"`);
+  const names = manifest && manifest.figma && manifest.figma.docCardVariables;
+  if (!names) {
+    throw new Error('design-system.json has no figma.docCardVariables — recover the nine roles from an existing card '
+      + '(step 2 of "How to call it" in references/doc-card-builder.md), write them back, then re-run');
+  }
+  const missing = ROLES.filter((r) => typeof names[r] !== 'string' || names[r] === '');
+  if (missing.length) throw new Error('figma.docCardVariables is missing role(s): ' + missing.join(', '));
+
+  const fingerprint = canonicalFingerprint(record);
+  const roleNames = Object.fromEntries(ROLES.map((r) => [r, names[r]]));
+  const code = [
+    `const RECORD = ${JSON.stringify(record)};`,
+    `const CANONICAL_FP = '${fingerprint}';`,
+    extractSnippet(builderMarkdown),
+    `const ROLE_NAMES = ${JSON.stringify(roleNames)};`,
+    'const allVars = await figma.variables.getLocalVariablesAsync();',
+    'const vars = {};',
+    'for (const [role, name] of Object.entries(ROLE_NAMES)) {',
+    '  const hits = allVars.filter((v) => v.name === name);',
+    "  if (hits.length !== 1) throw new Error('docCardVariables.' + role + ' \"' + name + '\" resolves to ' + hits.length + ' variables, not exactly one');",
+    '  vars[role] = await figma.variables.getVariableByIdAsync(hits[0].id);',
+    '}',
+    "const bodyTextStyle = (await figma.getLocalTextStylesAsync()).find((s) => s.name === 'Body/Default');",
+    `const card = await figma.getNodeByIdAsync('${cardNodeId}');`,
+    `if (!card) throw new Error('no node ${cardNodeId} in this file');`,
+    'const summary = await renderDocCard({ card, record: RECORD, vars, bodyTextStyle });',
+    'return { ...summary, bodyFontSize: bodyTextStyle.fontSize };',
+    '',
+  ].join('\n');
+
+  return {
+    code,
+    fingerprint,
+    fontSize,
+    expectedRenderHash: fnv1a(JSON.stringify(planDocCard(record, { fontSize }))),
+  };
+}
+
+function parseArgs(argv) {
+  const positional = [];
+  const opts = { manifest: 'design-system.json', out: null, fontSize: 16 };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--manifest') opts.manifest = argv[++i];
+    else if (a === '--out') opts.out = argv[++i];
+    else if (a === '--font-size') opts.fontSize = Number(argv[++i]);
+    else positional.push(a);
+  }
+  if (positional.length !== 2 || !Number.isFinite(opts.fontSize)) {
+    throw new Error('usage: node scripts/doc-card-payload.mjs <record.doc.json> <cardNodeId> [--manifest design-system.json] [--out payload.js] [--font-size 16]');
+  }
+  return { recordPath: positional[0], cardNodeId: positional[1], ...opts };
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  try {
+    const args = parseArgs(process.argv.slice(2));
+    const result = buildPayload({
+      record: JSON.parse(readFileSync(resolve(args.recordPath), 'utf8')),
+      cardNodeId: args.cardNodeId,
+      manifest: JSON.parse(readFileSync(resolve(args.manifest), 'utf8')),
+      builderMarkdown: readFileSync(BUILDER, 'utf8'),
+      fontSize: args.fontSize,
+    });
+    if (args.out) writeFileSync(resolve(args.out), result.code);
+    else process.stdout.write(result.code);
+    // Machine-readable trailer on stderr so stdout stays a clean payload.
+    console.error(JSON.stringify({
+      fingerprint: result.fingerprint,
+      expectedRenderHash: result.expectedRenderHash,
+      fontSize: result.fontSize,
+      out: args.out,
+    }));
+  } catch (err) {
+    console.error('✗ ' + err.message);
+    process.exit(1);
+  }
+}

package/scripts/install.mjs

@@ -102,7 +102,8 @@ function stagePayload(srcRoot, destRoot, skip) {
 // Scripts that never run from a consuming repo: the installer itself, the
 // reference-doc generators, and the Figma sources they inline (the doc-card
 // renderer and the Figma checks reach Figma pre-inlined inside
-// references/doc-card-builder.md and references/figma-checks.md). Test fixtures
+// 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.
 const PLUGIN_INTERNAL = new Set([
   'install.mjs',
@@ -112,6 +113,11 @@ const PLUGIN_INTERNAL = new Set([
   'build-figma-checks.mjs',
   'lib/figma-checks-read.figma.js',
   'lib/figma-checks.mjs',
+  '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',
 ]);
 
 export const skipScript = (relPosix) =>

package/scripts/lib/doc-card-plan.mjs

@@ -99,3 +99,40 @@ export function planDocCard(record, bodyTextStyle) {
     rows,
   };
 }
+
+// 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.
+export function fnv1a(str) {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < str.length; i++) {
+    h ^= str.charCodeAt(i);
+    h = Math.imul(h, 0x01000193) >>> 0;
+  }
+  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.
+export 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;
+}

package/scripts/lib/doc-card-render.figma.js

@@ -6,20 +6,8 @@
 // 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.
-function fnv1a(str) {
-  let h = 0x811c9dc5;
-  for (let i = 0; i < str.length; i++) {
-    h ^= str.charCodeAt(i);
-    h = Math.imul(h, 0x01000193) >>> 0;
-  }
-  return h.toString(16).padStart(8, '0');
-}
+// 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',
@@ -151,7 +139,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)'