@radicool/throughline 0.24.0 → 0.25.0

package/scripts/lib/figma-adherence-read.figma.js

@@ -0,0 +1,207 @@
+// Figma plugin-API reader for the screen adherence gate. This file is NOT a Node
+// module — build-figma-checks.mjs concatenates it after the inlined
+// figma-adherence.mjs and figma-variables-read.figma.js into
+// references/figma-adherence.md, and the result runs inside figma_execute.
+// Constraints honored here (see references/figma-scripting.md): async getters
+// only; only the target page is loaded; overridden nodes are found inside their
+// instance, never with getNodeByIdAsync in a loop (that stalled the bridge on a
+// large file). Read-only: nothing here writes to the file. Untested in Node
+// beyond the generator's snippet test; the pure checker it feeds is unit-tested.
+//
+// In-scope globals when assembled: checkScreens and dimensionBuckets (figma-adherence.mjs),
+// colorHex and variableColors (figma-variables-read.figma.js), and the caller-filled slots
+// TARGET = { page, screens?, fileKey } and SKIP = [rule, ...]. The snapshot shape is
+// documented at the top of scripts/lib/figma-adherence.mjs.
+
+const CORNERS = [
+  ['topLeftRadius', 'top-left'],
+  ['topRightRadius', 'top-right'],
+  ['bottomRightRadius', 'bottom-right'],
+  ['bottomLeftRadius', 'bottom-left'],
+];
+const SIDES = [
+  ['paddingTop', 'top'],
+  ['paddingRight', 'right'],
+  ['paddingBottom', 'bottom'],
+  ['paddingLeft', 'left'],
+];
+
+function solidPaints(node, field, kind) {
+  const list = node[field];
+  if (!Array.isArray(list)) return [];
+  const bound = (node.boundVariables && node.boundVariables[field]) || [];
+  const styleId = field === 'fills' ? node.fillStyleId : node.strokeStyleId;
+  const styled = typeof styleId === 'string' && styleId !== '';
+  const out = [];
+  list.forEach((paint, i) => {
+    if (paint.visible === false || paint.type !== 'SOLID') return;
+    // The paint's opacity goes into the hex the way colorHex writes a translucent
+    // variable, so a 50% black matches a 50% black token and not the opaque one.
+    const opacity = paint.opacity === undefined ? 1 : paint.opacity;
+    out.push({
+      kind,
+      hex: colorHex({ r: paint.color.r, g: paint.color.g, b: paint.color.b, a: opacity }),
+      bound: Boolean(bound[i]),
+      styled,
+    });
+  });
+  return out;
+}
+
+function gapOf(node) {
+  if (!node.layoutMode || node.layoutMode === 'NONE') return null;
+  const inFlow = (node.children || []).filter((c) => c.visible !== false && c.layoutPositioning !== 'ABSOLUTE');
+  return {
+    value: node.itemSpacing,
+    bound: Boolean(node.boundVariables && node.boundVariables.itemSpacing),
+    renders: inFlow.length >= 2 && node.primaryAxisAlignItems !== 'SPACE_BETWEEN',
+  };
+}
+
+function paddingOf(node) {
+  if (!node.layoutMode || node.layoutMode === 'NONE') return [];
+  const bound = node.boundVariables || {};
+  return SIDES.map(([field, side]) => ({ side, value: node[field], bound: Boolean(bound[field]) }));
+}
+
+function radiusOf(node) {
+  if (!('cornerRadius' in node)) return [];
+  const bound = node.boundVariables || {};
+  if (node.cornerRadius !== figma.mixed) {
+    return [{ corner: 'all', value: node.cornerRadius, bound: Boolean(bound.topLeftRadius) }];
+  }
+  return CORNERS.map(([field, corner]) => ({ corner, value: node[field], bound: Boolean(bound[field]) }));
+}
+
+function detachedOf(node, page) {
+  let info = null;
+  try {
+    info = node.detachedInfo;
+  } catch {
+    return null;
+  }
+  if (!info) return null;
+  if (info.type === 'library') return { kind: 'library', name: null, id: null, key: info.componentKey };
+  const main = page.findOne((n) => n.id === info.componentId);
+  return { kind: 'local', name: main ? main.name : null, id: info.componentId, key: null };
+}
+
+function overriddenRecords(instance, path, underDetached) {
+  const records = [];
+  for (const entry of instance.overrides || []) {
+    const fields = entry.overriddenFields.filter((f) => f === 'fills' || f === 'strokes');
+    if (!fields.length) continue;
+    const node = entry.id === instance.id ? instance : instance.findOne((n) => n.id === entry.id);
+    if (!node) continue;
+    records.push({
+      id: node.id,
+      path: node === instance ? path : `${path} / ${node.name}`,
+      isRoot: false,
+      inInstance: true,
+      underDetached,
+      overridden: fields,
+      paints: [...solidPaints(node, 'fills', 'fill'), ...solidPaints(node, 'strokes', 'stroke')],
+      mixedPaints: false,
+      gap: null,
+      padding: [],
+      radius: [],
+      detached: null,
+    });
+  }
+  return records;
+}
+
+function screensOn(page, names) {
+  const all = [];
+  for (const top of page.children) {
+    if (top.type === 'FRAME') all.push(top);
+    else if (top.type === 'SECTION') for (const c of top.children) if (c.type === 'FRAME') all.push(c);
+  }
+  if (!names || !names.length) return all;
+  return names.map((name) => {
+    const hit = all.find((s) => s.name === name);
+    if (!hit) throw new Error(`no screen named "${name}" on page "${page.name}"`);
+    return hit;
+  });
+}
+
+async function readTokens() {
+  const colours = {};
+  for (const variable of await figma.variables.getLocalVariablesAsync('COLOR')) {
+    const { modes } = await variableColors(variable);
+    for (const hex of Object.values(modes)) {
+      if (!hex) continue;
+      const names = colours[hex] || (colours[hex] = []);
+      if (!names.includes(variable.name)) names.push(variable.name);
+    }
+  }
+  const gap = {};
+  const radius = {};
+  const add = (table, value, name) => {
+    if (typeof value !== 'number') return;
+    const names = table[String(value)] || (table[String(value)] = []);
+    if (!names.includes(name)) names.push(name);
+  };
+  for (const variable of await figma.variables.getLocalVariablesAsync('FLOAT')) {
+    const buckets = dimensionBuckets(variable.name, variable.scopes || []);
+    for (const value of Object.values(variable.valuesByMode)) {
+      if (buckets.gap) add(gap, value, variable.name);
+      if (buckets.radius) add(radius, value, variable.name);
+    }
+  }
+  return { colours, gap, radius };
+}
+
+// Exact name first. Page names often carry decoration nobody types (01. Design
+// System's are "    ↳ Templates"), so a unique match on the trimmed name also counts.
+function findPage(name) {
+  const exact = figma.root.children.find((p) => p.name === name);
+  if (exact) return exact;
+  const trimmed = figma.root.children.filter((p) => p.name.trim() === String(name).trim());
+  if (trimmed.length === 1) return trimmed[0];
+  throw new Error(`no page named "${name}"`);
+}
+
+async function readScreens(target) {
+  const page = findPage(target.page);
+  await page.loadAsync();
+  const screens = screensOn(page, target.screens);
+  const nodes = [];
+  const walk = (node, path, isRoot, insideDetached) => {
+    if (node.visible === false) return;
+    if (node.type === 'INSTANCE') {
+      nodes.push(...overriddenRecords(node, path, insideDetached));
+      return;
+    }
+    const mixedPaints = node.fills === figma.mixed;
+    const detached = detachedOf(node, page);
+    const underDetached = insideDetached || detached !== null;
+    nodes.push({
+      id: node.id,
+      path,
+      isRoot,
+      inInstance: false,
+      underDetached,
+      overridden: [],
+      paints: [...solidPaints(node, 'fills', 'fill'), ...solidPaints(node, 'strokes', 'stroke')],
+      mixedPaints,
+      gap: gapOf(node),
+      padding: paddingOf(node),
+      radius: radiusOf(node),
+      detached,
+    });
+    for (const child of node.children || []) walk(child, `${path} / ${child.name}`, false, underDetached);
+  };
+  for (const screen of screens) walk(screen, `${page.name.trim()} / ${screen.name}`, true, false);
+  return {
+    // The caller passes the fileKey from design-system.json: figma.fileKey is only
+    // exposed to private plugins.
+    fileKey: target.fileKey || figma.fileKey,
+    nodes,
+    tokens: await readTokens(),
+  };
+}
+
+async function runScreenGate(TARGET, SKIP) {
+  return checkScreens(await readScreens(TARGET), { skip: SKIP || [] });
+}

package/scripts/lib/figma-adherence.mjs

@@ -0,0 +1,146 @@
+// The adherence gate for Figma screens as a pure checker: detached components,
+// raw colours a token has, and raw gaps, padding and radii a token has. ZERO
+// imports, `export const`/`export function` only. It is inlined, with the shared
+// variable reader and the screen reader below it, into the generated Figma script
+// (references/figma-adherence.md) by build-figma-checks.mjs, so it must run in
+// both Node and the Figma plugin sandbox.
+//
+// Spec: docs/specs/2026-10-13-figma-adherence-gate.md
+// The code-side counterpart is scripts/validate-adherence.mjs. Both follow its
+// spec's Decision 3: a raw value fails only when a token has it; any other raw
+// value is an advisory.
+//
+// SNAPSHOT (what the reader returns):
+//   {
+//     fileKey,                          // for links; the caller passes it (TARGET.fileKey)
+//     nodes: [{
+//       id, path,                       // path: 'Page / Screen / … / Node'
+//       isRoot,                         // the screen frame itself
+//       inInstance,                     // an overridden node inside an INSTANCE (or the instance itself)
+//       underDetached,                  // a detached frame, or anything inside one
+//       overridden: ['fills' | 'strokes'],   // inInstance nodes only
+//       paints: [{ kind: 'fill' | 'stroke', hex, bound, styled }],   // visible SOLID paints only;
+//                                       // hex is '#rrggbb', or '#rrggbbaa' when the paint's opacity < 1
+//       mixedPaints,                    // fills is figma.mixed (text with mixed runs)
+//       gap: { value, bound, renders } | null,
+//       padding: [{ side, value, bound }],
+//       radius: [{ corner, value, bound }],
+//       detached: { kind: 'local' | 'library', name, id, key } | null,
+//     }],
+//     tokens: {
+//       colours: { '#rrggbb': [variableName] },   // every mode's value
+//       gap: { '<number>': [variableName] },      // FLOAT scoped GAP or ALL_SCOPES
+//       radius: { '<number>': [variableName] },   // FLOAT scoped CORNER_RADIUS or ALL_SCOPES
+//     },
+//   }
+//
+// RESULT: { pass, failures, advisories, counts, skipped }
+//   failures/advisories: [{ rule, id, path, detail, link }], sorted by path then detail
+//   counts: { [rule]: { checked, failed } }
+//   `pass` is false when any failure exists. A failed assertion is data; nothing throws.
+
+export const RULES = ['detached-component', 'raw-colour', 'raw-dimension'];
+
+const PAINT_FIELD = { fill: 'fills', stroke: 'strokes' };
+
+// Which dimension tables a number variable belongs in. An explicit scope decides.
+// A variable left at ALL_SCOPES (Figma's default) counts only when its name says
+// what it is: on Zygarden every number variable is ALL_SCOPES, and without the
+// name test a 72 px gap failed with "bind text/7xl". Letter-spacing says "spacing"
+// but is type, not layout.
+const SPACING_WORDS = /spac|gap|inset|stack|inline|padding|gutter/i;
+const NOT_SPACING = /letter/i;
+const RADIUS_WORDS = /radius|corner|round/i;
+export function dimensionBuckets(name, scopes = []) {
+  const all = scopes.includes('ALL_SCOPES');
+  return {
+    gap: scopes.includes('GAP') || (all && SPACING_WORDS.test(name) && !NOT_SPACING.test(name)),
+    radius: scopes.includes('CORNER_RADIUS') || (all && RADIUS_WORDS.test(name)),
+  };
+}
+
+export function checkScreens(snapshot, { skip = [] } = {}) {
+  const nodes = snapshot.nodes ?? [];
+  const tokens = snapshot.tokens ?? {};
+  const colours = tokens.colours ?? {};
+  const gapTokens = tokens.gap ?? {};
+  const radiusTokens = tokens.radius ?? {};
+  const on = (rule) => !skip.includes(rule);
+  const link = (id) => `https://www.figma.com/design/${snapshot.fileKey}?node-id=${String(id).replace(/:/g, '-')}`;
+
+  const failures = [];
+  const advisories = [];
+  const counts = Object.fromEntries(RULES.filter(on).map((rule) => [rule, { checked: 0, failed: 0 }]));
+  const entry = (rule, node, detail) => ({ rule, id: node.id, path: node.path, detail, link: link(node.id) });
+  const fail = (rule, node, detail) => {
+    counts[rule].failed += 1;
+    failures.push(entry(rule, node, detail));
+  };
+  const advise = (rule, node, detail) => advisories.push(entry(rule, node, detail));
+
+  // A bound value passes. A raw one fails when a token has it, naming the token;
+  // otherwise it is an advisory.
+  const raw = (rule, node, table, value, bound, what) => {
+    counts[rule].checked += 1;
+    if (bound) return;
+    const names = table[String(value)];
+    if (names && names.length) fail(rule, node, `${what}: bind ${names.join(', ')}`);
+    else advise(rule, node, rule === 'raw-colour' ? `${what}: no colour variable has this value` : `off-scale ${what}`);
+  };
+
+  for (const node of nodes) {
+    if (on('detached-component')) {
+      counts['detached-component'].checked += 1;
+      const d = node.detached;
+      if (d) {
+        let from;
+        if (d.kind === 'library') from = `a library component (key ${d.key})`;
+        else if (d.name) from = d.name;
+        else from = `a local component on another page (id ${d.id})`;
+        fail('detached-component', node, `detached from ${from}`);
+      }
+    }
+
+    // Inside a detached copy, the one detached-component failure is the finding:
+    // re-instancing fixes every raw value under it. On 01. Design System's
+    // Archtypes page, checking them anyway turned 8 detached frames into ~200 failures.
+    if (node.underDetached) continue;
+
+    if (on('raw-colour')) {
+      if (node.mixedPaints) advise('raw-colour', node, 'mixed paints not read');
+      for (const paint of node.paints ?? []) {
+        if (node.inInstance && !(node.overridden ?? []).includes(PAINT_FIELD[paint.kind])) continue;
+        raw('raw-colour', node, colours, paint.hex, paint.bound || paint.styled, `${paint.kind} ${paint.hex}`);
+      }
+    }
+
+    if (on('raw-dimension') && !node.inInstance) {
+      const gap = node.gap;
+      if (gap && gap.renders && gap.value > 0) raw('raw-dimension', node, gapTokens, gap.value, gap.bound, `gap ${gap.value}`);
+      for (const p of node.padding ?? []) {
+        if (p.value > 0) raw('raw-dimension', node, gapTokens, p.value, p.bound, `padding-${p.side} ${p.value}`);
+      }
+      if (!node.isRoot) {
+        for (const r of node.radius ?? []) {
+          if (r.value > 0) raw('raw-dimension', node, radiusTokens, r.value, r.bound, `radius-${r.corner} ${r.value}`);
+        }
+      }
+    }
+  }
+
+  // Every enabled rule must have had something to check (code gate Decision 7).
+  const inert = (rule, detail) => failures.push({ rule, id: null, path: '', detail, link: null });
+  if (nodes.length === 0) inert('nothing-scanned', 'no node was read; check the page and screen names');
+  if (on('raw-colour') && Object.keys(colours).length === 0) {
+    inert('colour-rule-inert', 'the file has no local colour variables, so no raw colour could be matched to one');
+  }
+  if (on('raw-dimension') && Object.keys(gapTokens).length === 0 && Object.keys(radiusTokens).length === 0) {
+    inert('dimension-rule-inert', 'the file has no local number variable for spacing or radius: none is scoped GAP or CORNER_RADIUS, and none left at ALL_SCOPES is named for spacing or radius');
+  }
+
+  const cmp = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+  const byPath = (a, b) => cmp(a.path, b.path) || cmp(a.detail, b.detail);
+  failures.sort(byPath);
+  advisories.sort(byPath);
+  return { pass: failures.length === 0, failures, advisories, counts, skipped: RULES.filter((rule) => !on(rule)) };
+}

package/scripts/lib/figma-checks-read.figma.js

@@ -1,7 +1,7 @@
 // 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
+// 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
@@ -11,7 +11,8 @@
 // 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
+// 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.
 
@@ -26,37 +27,6 @@ async function variableName(alias) {
   return variable.name;
 }
 
-function colorHex(value) {
-  if (!value || typeof value !== 'object' || !('r' in value)) return null;
-  const byte = (x) => Math.round(x * 255).toString(16).padStart(2, '0');
-  const alpha = value.a === undefined ? 1 : value.a;
-  return `#${byte(value.r)}${byte(value.g)}${byte(value.b)}${alpha < 1 ? byte(alpha) : ''}`;
-}
-
-// The value of `variable` in the mode named `modeName` (after the fold), else
-// its collection's default mode, following aliases up to 10 hops.
-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 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);
-  }
-  return colorHex(value);
-}
-
-// { modes: { [modeName]: hex | null }, defaultMode } over the variable's own collection.
-async function variableColors(variable) {
-  const collection = await figma.variables.getVariableCollectionByIdAsync(variable.variableCollectionId);
-  if (!collection) return { modes: {}, defaultMode: undefined };
-  const modes = {};
-  for (const mode of collection.modes) modes[mode.name] = await resolveColor(variable, mode.name, 0);
-  const fallback = collection.modes.find((m) => m.modeId === collection.defaultModeId);
-  return { modes, defaultMode: fallback ? fallback.name : undefined };
-}
-
 // 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) || [];
@@ -114,19 +84,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]) => {
@@ -169,6 +165,10 @@ 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/lib/figma-checks.mjs

@@ -9,7 +9,7 @@
 // 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
@@ -46,7 +46,8 @@
 //
 // 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
@@ -281,7 +282,7 @@ export 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 ?? [];
@@ -369,9 +370,11 @@ export 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),
@@ -381,5 +384,13 @@ export 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)]);
+  }
+
+  return { checkSpec, checkBuilt, checkExisting };
 }

package/scripts/lib/figma-variables-read.figma.js

@@ -0,0 +1,39 @@
+// 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.
+
+const foldModeName = (s) => String(s).toLowerCase().replace(/[^a-z0-9]/g, '');
+
+function colorHex(value) {
+  if (!value || typeof value !== 'object' || !('r' in value)) return null;
+  const byte = (x) => Math.round(x * 255).toString(16).padStart(2, '0');
+  const alpha = value.a === undefined ? 1 : value.a;
+  return `#${byte(value.r)}${byte(value.g)}${byte(value.b)}${alpha < 1 ? byte(alpha) : ''}`;
+}
+
+// The value of `variable` in the mode named `modeName` (after the fold), else
+// its collection's default mode, following aliases up to 10 hops.
+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) => 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);
+  }
+  return colorHex(value);
+}
+
+// { modes: { [modeName]: hex | null }, defaultMode } over the variable's own collection.
+async function variableColors(variable) {
+  const collection = await figma.variables.getVariableCollectionByIdAsync(variable.variableCollectionId);
+  if (!collection) return { modes: {}, defaultMode: undefined };
+  const modes = {};
+  for (const mode of collection.modes) modes[mode.name] = await resolveColor(variable, mode.name, 0);
+  const fallback = collection.modes.find((m) => m.modeId === collection.defaultModeId);
+  return { modes, defaultMode: fallback ? fallback.name : undefined };
+}

package/scripts/lib/fixtures/figma-adherence/clean.json

@@ -0,0 +1,90 @@
+{
+  "covers": "everything bound passes with no advisories",
+  "snapshot": {
+    "fileKey": "FILE",
+    "screens": [
+      {
+        "id": "0:1",
+        "name": "Screen"
+      }
+    ],
+    "nodes": [
+      {
+        "id": "1:1",
+        "path": "Templates / Screen / Node",
+        "isRoot": false,
+        "inInstance": false,
+        "overridden": [],
+        "paints": [
+          {
+            "kind": "fill",
+            "hex": "#ffffff",
+            "bound": true,
+            "styled": false
+          },
+          {
+            "kind": "stroke",
+            "hex": "#111827",
+            "bound": false,
+            "styled": true
+          }
+        ],
+        "mixedPaints": false,
+        "gap": {
+          "value": 12,
+          "bound": true,
+          "renders": true
+        },
+        "padding": [
+          {
+            "side": "top",
+            "value": 16,
+            "bound": true
+          }
+        ],
+        "radius": [
+          {
+            "corner": "all",
+            "value": 8,
+            "bound": true
+          }
+        ],
+        "detached": null
+      }
+    ],
+    "tokens": {
+      "colours": {
+        "#ffffff": [
+          "color/bg/canvas"
+        ],
+        "#111827": [
+          "color/text/primary"
+        ]
+      },
+      "gap": {
+        "8": [
+          "spacing/2"
+        ],
+        "12": [
+          "spacing/3"
+        ],
+        "16": [
+          "spacing/4"
+        ]
+      },
+      "radius": {
+        "8": [
+          "radius/md"
+        ],
+        "32": [
+          "radius/xl"
+        ]
+      }
+    }
+  },
+  "expected": {
+    "pass": true,
+    "failures": [],
+    "advisories": 0
+  }
+}