@radicool/throughline 0.23.0 → 0.25.0

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,21 +1,30 @@
 // 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 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
-// resolved with getVariableByIdAsync and only for focus variants and their
-// controlLayer. Untested in Node, like the doc-card renderer; the pure checker
-// it feeds is unit-tested.
+// 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
+// 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);
-  return variable ? variable.name : null;
+  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.
@@ -75,18 +84,45 @@ function groupProperties(set) {
   }
 }
 
-async function readComponentSet(expect) {
+// 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]) => {
@@ -106,15 +142,33 @@ async function readComponentSet(expect) {
     }
     children.push(read);
   }
+  const colors = {};
+  for (const [name, variable] of readVariables) colors[name] = await variableColors(variable);
+  const missingSurfaces = [];
+  const surfaces = expect.surfaces || [];
+  if (surfaces.length) {
+    const local = await figma.variables.getLocalVariablesAsync('COLOR');
+    for (const name of surfaces) {
+      const variable = local.find((v) => v.name === name);
+      if (variable) colors[name] = await variableColors(variable);
+      else missingSurfaces.push(name);
+    }
+  }
   return {
     type: set.type,
     variantGroupProperties: groupProperties(set),
     children,
+    colors,
+    missingSurfaces,
   };
 }
 
 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

@@ -1,26 +1,35 @@
 // The Figma stop conditions as a pure checker: the COMPONENT_SET assertion against
-// the full variant matrix, the state matrix, and the focus ring. ZERO imports,
+// the full variant matrix, the state matrix, the focus ring, and the focus ring's
+// contrast against the surfaces it sits on. ZERO imports,
 // `export const`/`export function` only. This module is inlined, with
-// component-states.mjs above it, into the generated Figma script
+// component-states.mjs and contrast.mjs above it, into the generated Figma script
 // (references/figma-checks.md) by build-figma-checks.mjs, so it must run in both
 // Node and the Figma plugin sandbox.
 //
 // The state table is not imported. `withTable({ resolveArchetype, BASELINE_STATES,
-// STATE_SYNONYMS, normalizeName })` takes it, and the fold, from the caller and
-// returns { checkSpec, checkBuilt }. In the generated script the caller passes the
+// STATE_SYNONYMS, normalizeName, contrastRatio, composite, parseHex, AA_NON_TEXT })`
+// takes it, the fold and the contrast maths from the caller and returns
+// { 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
 // Rules: references/figma-component-standards.md (State handling; audit items 8, 9)
 //
-// EXPECT: { name, matrix: { axis: [values] }, uiFramework, controlLayer? }
+// Spec (focus contrast): docs/specs/2026-10-13-focus-ring-contrast.md
+//
+// EXPECT: { name, matrix: { axis: [values] }, uiFramework, controlLayer?, surfaces? }
+//   surfaces: colour-variable names of the page surfaces the component sits on.
 //
 // SNAPSHOT (what the reader returns for the COMPONENT_SET in `WIP: <name>`):
 //   {
 //     type,                               // the set's node type, 'COMPONENT_SET'
 //     variantGroupProperties: { Axis: { values: [...] }, ... },   // only the keys are read
-//     children: [ VARIANT, ... ]
+//     children: [ VARIANT, ... ],
+//     colors: { [variableName]: { modes: { [modeName]: '#rrggbb' | '#rrggbbaa' | null }, defaultMode } },
+//     missingSurfaces: [name, ...]          // EXPECT.surfaces names with no local colour variable
 //   }
+//   `colors` holds every colour variable read on focus variants and their
+//   controlLayer, plus each EXPECT.surfaces name that was found.
 //   VARIANT (every child):  { type, variantProperties: { Axis: 'Value' } }
 //   A VARIANT whose state value folds to `focus` also carries FOCUS NODE fields
 //   (below), plus `controlLayer` when EXPECT names one.
@@ -36,6 +45,9 @@
 //   Variable names are resolved by the reader and only for focus variants and their controlLayer.
 //
 // RESULT: { pass, checks: [{ name, result: 'pass' | 'fail' | 'skip', detail }] }
+//   built mode returns four checks: structural-read-back, state-baseline,
+//   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
@@ -61,11 +73,17 @@ function frameworkRecipe(uiFramework) {
     : null;
 }
 
-// A focus variable is any variable whose name has a `focus` segment:
-// `border/focus`, `color/border/focus` and `color/focus/ring` count; `focusRing` and
-// a raw colour (null) do not.
+// A focus variable is any variable whose name has `focus` as a whole word: in a
+// `/` segment of its own, or inside one split on `-`, `_`, spaces or a camelCase
+// boundary. `border/focus`, `color/focus/ring`, `color/focusRing` and
+// `interaction/border-primary-focus` count; `color/bg/focused` and a raw colour
+// (null) do not.
 function isFocusVariable(name) {
-  return typeof name === 'string' && name.split('/').some((seg) => seg.trim().toLowerCase() === 'focus');
+  if (typeof name !== 'string') return false;
+  const words = name
+    .split('/')
+    .flatMap((seg) => seg.replace(/([a-z0-9])([A-Z])/g, '$1 $2').split(/[\s_-]+/));
+  return words.some((word) => word.toLowerCase() === 'focus');
 }
 
 // A choice control may carry selection on its own axis instead of as a `selected`
@@ -102,7 +120,34 @@ function lacksRing(target, recipe, isInput) {
       ];
 }
 
-export function withTable({ resolveArchetype, BASELINE_STATES, STATE_SYNONYMS, normalizeName }) {
+// The focus-variable names that make up the ring `lacksRing` accepted, for the
+// contrast check. Same recipes, same tests.
+function ringVariables(target, recipe, isInput) {
+  const children = target.children ?? [];
+  const focusStrokes = (node) => (node.strokeVariables ?? []).filter(isFocusVariable);
+  if (recipe === 'mui' && isInput) return focusStrokes(target);
+  if (recipe === 'outline') {
+    return [target, ...children].filter((n) => n.strokeAlign === 'OUTSIDE').flatMap(focusStrokes);
+  }
+  const shadows = (target.effects ?? [])
+    .filter((e) => e.type === 'DROP_SHADOW' && e.visible !== false && e.spread > 0 && isFocusVariable(e.colorVariable))
+    .map((e) => e.colorVariable);
+  const ringChildren = children
+    .filter((c) => c.layoutPositioning === 'ABSOLUTE' && c.strokeAlign === 'OUTSIDE')
+    .flatMap(focusStrokes);
+  return [...shadows, ...ringChildren];
+}
+
+export function withTable({
+  resolveArchetype,
+  BASELINE_STATES,
+  STATE_SYNONYMS,
+  normalizeName,
+  contrastRatio,
+  composite,
+  parseHex,
+  AA_NON_TEXT,
+}) {
   const fold = normalizeName;
   const foldState = (value) => {
     const name = fold(value);
@@ -122,6 +167,10 @@ export function withTable({ resolveArchetype, BASELINE_STATES, STATE_SYNONYMS, n
       .map(([k, v]) => `${k}=${v}`)
       .join(', ');
 
+  const isFocusVariant = (child) =>
+    child.type === 'COMPONENT' &&
+    Object.entries(child.variantProperties ?? {}).some(([k, v]) => fold(k) === 'state' && fold(v) === 'focus');
+
   function crossProduct(matrix) {
     let combos = [{}];
     for (const [axis, values] of Object.entries(matrix ?? {})) {
@@ -199,9 +248,6 @@ export function withTable({ resolveArchetype, BASELINE_STATES, STATE_SYNONYMS, n
     if (recipe === null) {
       return { name, result: 'skip', detail: `uiFramework "${expect.uiFramework}" is out of scope for the focus check` };
     }
-    const isFocusVariant = (child) =>
-      child.type === 'COMPONENT' &&
-      Object.entries(child.variantProperties ?? {}).some(([k, v]) => fold(k) === 'state' && fold(v) === 'focus');
     const variants = (snapshot.children ?? []).filter(isFocusVariant);
     if (variants.length === 0) {
       return { name, result: 'fail', detail: 'no COMPONENT variant has a state of focus, so no ring can be read; the state check stops on this' };
@@ -224,17 +270,127 @@ export function withTable({ resolveArchetype, BASELINE_STATES, STATE_SYNONYMS, n
       : { name, result: 'pass', detail: `all ${variants.length} focus variants carry a ${recipe}-recipe focus indicator` };
   }
 
+  // WCAG 1.4.11: each ring colour against each named surface, in every mode either
+  // side has. Runs only on a ring focusIndicator accepted.
+  function focusContrast(snapshot, expect, indicator) {
+    const name = 'focus-contrast';
+    if (indicator.result !== 'pass') {
+      return { name, result: 'skip', detail: 'focus-indicator did not pass, so there is no ring to measure' };
+    }
+    const surfaces = expect.surfaces ?? [];
+    if (surfaces.length === 0) {
+      return {
+        name,
+        result: 'skip',
+        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 ?? [];
+    if (missing.length) {
+      return { name, result: 'fail', detail: `no local colour variable named: ${missing.join(', ')}` };
+    }
+
+    const recipe = frameworkRecipe(expect.uiFramework);
+    const isInput = resolveArchetype({ name: expect.name }) === 'input';
+    const hasLayer = expect.controlLayer !== undefined && expect.controlLayer !== null;
+    const rings = new Set();
+    for (const variant of (snapshot.children ?? []).filter(isFocusVariant)) {
+      const target = hasLayer ? variant.controlLayer : variant;
+      if (target) for (const ring of ringVariables(target, recipe, isInput)) rings.add(ring);
+    }
+
+    const colors = snapshot.colors ?? {};
+    // A mode's value: the same-named mode after the fold, else the default.
+    const valueIn = (entry, foldedMode) => {
+      const modes = entry?.modes ?? {};
+      const hit = Object.keys(modes).find((m) => fold(m) === foldedMode);
+      if (hit !== undefined) return modes[hit];
+      return entry?.defaultMode !== undefined ? modes[entry.defaultMode] ?? null : null;
+    };
+    const skipped = { unresolved: 0, translucentSurface: 0 };
+    const failures = [];
+    const modesSeen = new Set();
+    let pairs = 0;
+    for (const ring of [...rings].sort()) {
+      for (const surface of [...surfaces].sort()) {
+        const ringEntry = colors[ring];
+        const surfaceEntry = colors[surface];
+        // Modes come from the side(s) with more than one: a single-mode collection
+        // reads the same value in every mode, so its own mode name adds nothing.
+        // When both are single-mode, the ring's one mode is the only comparison.
+        const entries = [ringEntry, surfaceEntry];
+        const multi = entries.filter((e) => Object.keys(e?.modes ?? {}).length > 1);
+        const single = Object.keys(ringEntry?.modes ?? {}).length ? [ringEntry] : [surfaceEntry];
+        const modeNames = new Map();
+        for (const entry of multi.length ? multi : single) {
+          for (const m of Object.keys(entry?.modes ?? {})) if (!modeNames.has(fold(m))) modeNames.set(fold(m), m);
+        }
+        if (modeNames.size === 0) {
+          skipped.unresolved += 1;
+          continue;
+        }
+        for (const [foldedMode, mode] of [...modeNames].sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0))) {
+          const ringHex = valueIn(ringEntry, foldedMode);
+          const surfaceHex = valueIn(surfaceEntry, foldedMode);
+          const surfaceParsed = parseHex(surfaceHex);
+          if (parseHex(ringHex) === null || surfaceParsed === null) {
+            skipped.unresolved += 1;
+            continue;
+          }
+          if (surfaceParsed.a < 1) {
+            skipped.translucentSurface += 1;
+            continue;
+          }
+          const surfaceOpaque = surfaceHex.slice(0, 7);
+          const ratio = contrastRatio(composite(ringHex, surfaceOpaque), surfaceOpaque);
+          pairs += 1;
+          modesSeen.add(foldedMode);
+          if (ratio < AA_NON_TEXT) {
+            const shown = (Math.floor(ratio * 100) / 100).toFixed(2);
+            failures.push(`${ring} on ${surface} in ${mode}: ${shown}:1, needs ${AA_NON_TEXT}:1`);
+          }
+        }
+      }
+    }
+    const skipNote = [
+      skipped.unresolved && `${skipped.unresolved} skipped as unresolved or not a colour`,
+      skipped.translucentSurface && `${skipped.translucentSurface} skipped for a translucent surface`,
+    ].filter(Boolean);
+    if (failures.length) return { name, result: 'fail', detail: failures.join('; ') };
+    if (pairs === 0) {
+      return { name, result: 'skip', detail: `no ring/surface pair could be compared: ${skipNote.join(', ') || 'no ring colour found'}` };
+    }
+    const passed = `${pairs} ring/surface pair(s) clear ${AA_NON_TEXT}:1 across ${modesSeen.size} mode(s)`;
+    return { name, result: 'pass', detail: skipNote.length ? `${passed}; ${skipNote.join(', ')}` : passed };
+  }
+
   // Before anything is written: the matrix the spec asks for against the state table.
   function checkSpec(expect) {
     const entries = Object.entries(expect.matrix ?? {}).flatMap(([axis, values]) => values.map((v) => [axis, v]));
     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 ?? {}));
-    return result([structural(snapshot, expect), stateBaseline(expect, entries), focusIndicator(snapshot, expect)]);
+    const entries = variantEntries(snapshot);
+    const indicator = focusIndicator(snapshot, expect);
+    return result([
+      structural(snapshot, expect),
+      stateBaseline(expect, entries),
+      indicator,
+      focusContrast(snapshot, expect, indicator),
+    ]);
+  }
+
+  // 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 };
+  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
+  }
+}