@radicool/throughline 0.24.0 → 0.25.0

package/references/figma-checks.md

@@ -24,7 +24,7 @@ these checks by hand.
      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
@@ -38,6 +38,18 @@ these checks by hand.
    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' };
@@ -259,7 +271,7 @@ function composite(fgHex, bgHex) {
 // The state table is not imported. `withTable({ resolveArchetype, BASELINE_STATES,
 // STATE_SYNONYMS, normalizeName, contrastRatio, composite, parseHex, AA_NON_TEXT })`
 // takes it, the fold and the contrast maths from the caller and returns
-// { checkSpec, checkBuilt }. In the generated script the caller passes the
+// { checkSpec, checkBuilt, checkExisting }. In the generated script the caller passes the
 // inlined component-states.mjs names; in tests it passes the module's own exports.
 //
 // Spec: docs/specs/2026-10-07-figma-checks-as-scripts.md
@@ -296,7 +308,8 @@ function composite(fgHex, bgHex) {
 //
 // RESULT: { pass, checks: [{ name, result: 'pass' | 'fail' | 'skip', detail }] }
 //   built mode returns four checks: structural-read-back, state-baseline,
-//   focus-indicator, focus-contrast.
+//   focus-indicator, focus-contrast. existing mode (a set already in the library,
+//   docs/specs/2026-10-13-figma-adherence-gate.md) returns the last three.
 //   `pass` ignores skips. A failed assertion is data; nothing here throws.
 
 // The in-scope `uiFramework` values and the focus recipe each one uses. An absent or
@@ -531,7 +544,7 @@ function withTable({
       return {
         name,
         result: 'skip',
-        detail: 'no surfaces named; the architect names the colour variables of the surfaces the component sits on',
+        detail: 'no surfaces named; name the colour variables of the surfaces the component sits on (from the architect spec, or ask the user)',
       };
     }
     const missing = snapshot.missingSurfaces ?? [];
@@ -619,9 +632,11 @@ function withTable({
     return result([stateBaseline(expect, entries)]);
   }
 
+  const variantEntries = (snapshot) => (snapshot.children ?? []).flatMap((c) => Object.entries(c.variantProperties ?? {}));
+
   // After the build: the node as read.
   function checkBuilt(snapshot, expect) {
-    const entries = (snapshot.children ?? []).flatMap((c) => Object.entries(c.variantProperties ?? {}));
+    const entries = variantEntries(snapshot);
     const indicator = focusIndicator(snapshot, expect);
     return result([
       structural(snapshot, expect),
@@ -631,38 +646,27 @@ function withTable({
     ]);
   }
 
-  return { checkSpec, checkBuilt };
-}
+  // An existing set has no spec matrix, so the structural check is not run; the
+  // other three read only the set itself.
+  function checkExisting(snapshot, expect) {
+    const entries = variantEntries(snapshot);
+    const indicator = focusIndicator(snapshot, expect);
+    return result([stateBaseline(expect, entries), indicator, focusContrast(snapshot, expect, indicator)]);
+  }
 
-const { checkSpec, checkBuilt } = withTable({ resolveArchetype, BASELINE_STATES, STATE_SYNONYMS, normalizeName, contrastRatio, composite, parseHex, AA_NON_TEXT });
+  return { checkSpec, checkBuilt, checkExisting };
+}
 
-// Figma plugin-API reader for the stop-condition checks. This file is NOT a
-// Node module — build-figma-checks.mjs concatenates it after the inlined
-// component-states.mjs, contrast.mjs and figma-checks.mjs into
-// references/figma-checks.md, and
-// the result runs inside figma_execute (dynamic-page mode). Constraints honored
-// here (see references/figma-scripting.md): async getters only, variable names
-// and per-mode colour values resolved with getVariableByIdAsync and only for
-// focus variants and their controlLayer, plus the EXPECT.surfaces names, which
-// are looked up among the file's LOCAL colour variables only (a surface from a
-// published library reads as missing). Untested in Node, like the doc-card
-// renderer; the pure checker it feeds is unit-tested.
-//
-// In-scope globals when assembled: normalizeName (inlined
-// component-states.mjs), checkSpec, checkBuilt (bound from withTable) and the
-// caller-filled slots EXPECT and MODE (passed to runFigmaChecks). The snapshot
-// shape is documented at the top of scripts/lib/figma-checks.mjs.
+const { checkSpec, checkBuilt, checkExisting } = withTable({ resolveArchetype, BASELINE_STATES, STATE_SYNONYMS, normalizeName, contrastRatio, composite, parseHex, AA_NON_TEXT });
 
-// Colour variables read on focus nodes, by name, for the contrast check.
-const readVariables = new Map();
+// Figma plugin-API helpers for reading colour variables, shared by the Figma
+// checks reader and the screen reader. This file is NOT a Node module:
+// build-figma-checks.mjs inlines it into both generated scripts
+// (references/figma-checks.md, references/figma-adherence.md). It depends on
+// nothing else, so it carries its own mode-name fold. Async getters only
+// (references/figma-scripting.md). Untested in Node, like the readers.
 
-async function variableName(alias) {
-  if (!alias || !alias.id) return null;
-  const variable = await figma.variables.getVariableByIdAsync(alias.id);
-  if (!variable) return null;
-  if (variable.resolvedType === 'COLOR') readVariables.set(variable.name, variable);
-  return variable.name;
-}
+const foldModeName = (s) => String(s).toLowerCase().replace(/[^a-z0-9]/g, '');
 
 function colorHex(value) {
   if (!value || typeof value !== 'object' || !('r' in value)) return null;
@@ -677,7 +681,7 @@ async function resolveColor(variable, modeName, hops) {
   if (!variable || hops > 10) return null;
   const collection = await figma.variables.getVariableCollectionByIdAsync(variable.variableCollectionId);
   if (!collection) return null;
-  const mode = collection.modes.find((m) => normalizeName(m.name) === normalizeName(modeName));
+  const mode = collection.modes.find((m) => foldModeName(m.name) === foldModeName(modeName));
   const value = variable.valuesByMode[mode ? mode.modeId : collection.defaultModeId];
   if (value && value.type === 'VARIABLE_ALIAS') {
     return resolveColor(await figma.variables.getVariableByIdAsync(value.id), modeName, hops + 1);
@@ -695,6 +699,35 @@ async function variableColors(variable) {
   return { modes, defaultMode: fallback ? fallback.name : undefined };
 }
 
+// Figma plugin-API reader for the stop-condition checks. This file is NOT a
+// Node module — build-figma-checks.mjs concatenates it after the inlined
+// component-states.mjs, contrast.mjs, figma-checks.mjs and
+// figma-variables-read.figma.js into references/figma-checks.md, and
+// the result runs inside figma_execute (dynamic-page mode). Constraints honored
+// here (see references/figma-scripting.md): async getters only, variable names
+// and per-mode colour values resolved with getVariableByIdAsync and only for
+// focus variants and their controlLayer, plus the EXPECT.surfaces names, which
+// are looked up among the file's LOCAL colour variables only (a surface from a
+// published library reads as missing). Untested in Node, like the doc-card
+// renderer; the pure checker it feeds is unit-tested.
+//
+// In-scope globals when assembled: normalizeName (inlined
+// component-states.mjs), variableColors (figma-variables-read.figma.js),
+// checkSpec, checkBuilt, checkExisting (bound from withTable) and the
+// caller-filled slots EXPECT and MODE (passed to runFigmaChecks). The snapshot
+// shape is documented at the top of scripts/lib/figma-checks.mjs.
+
+// Colour variables read on focus nodes, by name, for the contrast check.
+const readVariables = new Map();
+
+async function variableName(alias) {
+  if (!alias || !alias.id) return null;
+  const variable = await figma.variables.getVariableByIdAsync(alias.id);
+  if (!variable) return null;
+  if (variable.resolvedType === 'COLOR') readVariables.set(variable.name, variable);
+  return variable.name;
+}
+
 // The fields the focus check reads from a variant, a control layer or a direct child.
 async function readFocusNode(node, { withEffects }) {
   const strokes = (node.boundVariables && node.boundVariables.strokes) || [];
@@ -752,19 +785,45 @@ function groupProperties(set) {
   }
 }
 
-async function readComponentSet(expect) {
-  readVariables.clear();
+// The set a build just made: the COMPONENT_SET in the `WIP: <name>` frame on the
+// current page. A frame holding plain FRAMEs where the set should be is a failed
+// assertion, not a missing target, so it comes back as `{ empty }` for the
+// structural check to name.
+async function findWipSet(expect) {
   await figma.currentPage.loadAsync();
   const frameName = `WIP: ${expect.name}`;
   const frame = figma.currentPage.findOne((n) => n.name === frameName);
   if (!frame) throw new Error(`no node named "${frameName}" on the current page`);
   const set = frame.type === 'COMPONENT_SET' ? frame : (frame.children || []).find((c) => c.type === 'COMPONENT_SET');
-  // A frame holding plain FRAMEs where the set should be is a failed assertion,
-  // not a missing target: report what is there so the structural check names it.
-  if (!set) {
-    const first = (frame.children || [])[0];
-    return { type: first ? first.type : 'NONE', variantGroupProperties: {}, children: [] };
+  if (set) return { set };
+  const first = (frame.children || [])[0];
+  return { empty: { type: first ? first.type : 'NONE', variantGroupProperties: {}, children: [] } };
+}
+
+// A set already in the library: the first COMPONENT_SET whose name folds to the
+// same name. With `pageName`, only that page is loaded (exact name, or a unique
+// match on the trimmed name). Without it every page is loaded in turn until one
+// has the set, which on a miss is the whole file; a whole-file load stalled the
+// bridge on a large file, so callers pass the page.
+async function findExistingSet(name, pageName) {
+  const want = normalizeName(name);
+  let pages = figma.root.children;
+  if (pageName !== undefined && pageName !== null) {
+    const exact = pages.filter((p) => p.name === pageName);
+    const trimmed = pages.filter((p) => p.name.trim() === String(pageName).trim());
+    pages = exact.length ? exact : trimmed.length === 1 ? trimmed : [];
+    if (!pages.length) throw new Error(`no page named "${pageName}"`);
   }
+  for (const page of pages) {
+    await page.loadAsync();
+    const set = page.findAllWithCriteria({ types: ['COMPONENT_SET'] }).find((s) => normalizeName(s.name) === want);
+    if (set) return set;
+  }
+  throw new Error(`no component set named "${name}"${pageName ? ` on page "${pageName}"` : ' in this file'}`);
+}
+
+async function readSet(set, expect) {
+  readVariables.clear();
 
   const isFocusState = (props) =>
     Object.entries(props || {}).some(([k, v]) => {
@@ -807,7 +866,11 @@ async function readComponentSet(expect) {
 
 async function runFigmaChecks(EXPECT, MODE) {
   if (MODE === 'spec') return checkSpec(EXPECT);
-  if (MODE === 'built') return checkBuilt(await readComponentSet(EXPECT), EXPECT);
-  throw new Error(`MODE must be 'spec' or 'built', got ${JSON.stringify(MODE)}`);
+  if (MODE === 'built') {
+    const { set, empty } = await findWipSet(EXPECT);
+    return checkBuilt(set ? await readSet(set, EXPECT) : empty, EXPECT);
+  }
+  if (MODE === 'existing') return checkExisting(await readSet(await findExistingSet(EXPECT.name, EXPECT.page), EXPECT), EXPECT);
+  throw new Error(`MODE must be 'spec', 'built' or 'existing', got ${JSON.stringify(MODE)}`);
 }
 ```

package/scripts/README.md

@@ -25,13 +25,16 @@ 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 both `references/figma-checks.md` and `references/figma-adherence.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. Inlined into `references/figma-adherence.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 |
 | `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`); and `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`. `--check` gates CI on both. | 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 +252,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.25.0 init --target=cursor|codex|generic
 
 See `scripts/install.mjs` (pure core + CLI + `install.test.mjs`).
 

package/scripts/build-figma-checks.mjs

@@ -1,10 +1,15 @@
-// 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).
+// Mirrors build-doc-card-builder.mjs: run bare to write both, run with --check to
+// gate CI on both. Zero dependencies.
 import { readFileSync, writeFileSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
@@ -14,9 +19,13 @@ 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 OUT = join(REPO_ROOT, 'references', 'figma-checks.md');
+const ADHERENCE_OUT = join(REPO_ROOT, 'references', 'figma-adherence.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 +54,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 +68,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 +93,81 @@ 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 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}`;
 }
 
 if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
@@ -94,18 +175,35 @@ 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 outputs = [
+    [OUT, result, 'references/figma-checks.md', 'figma checks'],
+    [ADHERENCE_OUT, adherence, 'references/figma-adherence.md', 'figma adherence'],
+  ];
   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/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 and
+// references/figma-adherence.md). Test fixtures
 // under lib/fixtures/ are dropped too.
 const PLUGIN_INTERNAL = new Set([
   'install.mjs',
@@ -112,6 +113,9 @@ 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',
 ]);
 
 export const skipScript = (relPosix) =>