@radicool/throughline 0.13.0 → 0.15.0

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

@@ -0,0 +1,143 @@
+// Generates references/doc-card-builder.md — the canonical figma_execute
+// snippet that renders a doc card's Usage band — by inlining the pure planner
+// (lib/doc-card-plan.mjs) above the Figma renderer template
+// (lib/doc-card-render.figma.js). Mirrors the adapters generate.mjs idiom:
+// run bare to write, run with --check to gate CI. Zero dependencies.
+import { readFileSync, writeFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+const PLANNER = join(REPO_ROOT, 'scripts', 'lib', 'doc-card-plan.mjs');
+const RENDERER = join(REPO_ROOT, 'scripts', 'lib', 'doc-card-render.figma.js');
+const OUT = join(REPO_ROOT, 'references', 'doc-card-builder.md');
+
+const HEADER = [
+  '# Doc-card Usage-band builder (GENERATED)',
+  '',
+  '> **GENERATED FILE — do not edit by hand.** Sources: `scripts/lib/doc-card-plan.mjs`',
+  '> (the pure planner, unit-tested in Node) + `scripts/lib/doc-card-render.figma.js`',
+  '> (the Figma renderer). Regenerate with `node scripts/build-doc-card-builder.mjs`;',
+  '> CI gates freshness with `--check`.',
+  '',
+  'The canonical `figma_execute` snippet that renders a component doc card\'s',
+  '`Usage` band from its `.doc.json` record. Every card is identical by',
+  'construction — never hand-build the usage body. The builder owns the `Usage`',
+  'band and the header\'s record-derived content (its short description and date);',
+  'it reads the specimen and never writes it. The status chip keeps its own owner',
+  '— the finalize write-back in `references/figma-component-standards.md`.',
+  '',
+  '## How to call it',
+  '',
+  '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`.',
+  '   - If present, resolve each of the nine roles to a Variable object **by',
+  '     the recorded name** — do not re-derive, do not substitute a similar',
+  '     name. Look each name up via `figma_get_variables`, then in the script',
+  '     fetch it as a Variable object with',
+  '     `figma.variables.getVariableByIdAsync(id)`. If a recorded name no',
+  '     longer resolves to exactly one variable in the file, **throw** rather',
+  '     than guess — the token was renamed or removed, and silently picking a',
+  '     neighbour is how cards drift apart.',
+  '   - If the field is absent (a project\'s first doc-card render, or any',
+  '     render after the field is cleared), do not resolve fresh by judgement',
+  '     yet — first check whether a doc card already exists in the file. If',
+  '     one does, recover all nine roles from it by resolving each bound',
+  '     variable id back to its name (`figma.variables.getVariableByIdAsync(id)`):',
+  '     - `spacePadding` ← the `Usage` frame\'s `paddingLeft`.',
+  '     - `spaceRowGap` ← the `Usage` frame\'s `itemSpacing`.',
+  '     - `spaceBlockGap` ← a `Usage Row *` frame\'s `itemSpacing`.',
+  '     - `spaceItemGap` ← a `Block: *` frame\'s `itemSpacing` (blocks are the',
+  '       children of a `Usage Row *`).',
+  '     - `border` ← a `Row Divider` frame\'s',
+  '       `fills[0].boundVariables.color`.',
+  '     - `tonePositive` ← the first TEXT child of the `Block: Do` frame\'s',
+  '       `fills[0].boundVariables.color`.',
+  '     - `toneNegative` ← the first TEXT child of the `Block: Don\'t` frame,',
+  '       same property.',
+  '     - `textMuted` ← the first TEXT child of any block other than',
+  '       `Block: Do` / `Block: Don\'t`, same property (tone blocks colour',
+  '       their eyebrow differently, so exclude them here).',
+  '     - `textDefault` ← the second child of that same block when it is a',
+  '       TEXT node — `Block: Overview` is reliable; definition blocks nest',
+  '       frames there instead, so skip those. Same property.',
+  '     A single-row card has no `Row Divider` (no `border`); a card without',
+  '     `Block: Do` / `Block: Don\'t` yields no `tonePositive` / `toneNegative`.',
+  '     Read another rendered card for the roles that specific card can\'t',
+  '     yield, or fall back to judgement for just those. Only when no',
+  '     rendered card exists at all does the caller choose every role by',
+  '     judgement — establishing the project\'s rhythm, not guessing at one.',
+  '   Either way, resolve the nine roles once, **write the mapping back to',
+  '   `design-system.json`** as `figma.docCardVariables`, then render. Every',
+  '   later render reads it.',
+  '   The nine roles: `textDefault`, `textMuted` (text colors), `tonePositive`,',
+  '   `toneNegative` (Do/Don\'t eyebrow colors — success/danger roles), `border`',
+  '   (row dividers), `spacePadding`, `spaceRowGap`, `spaceBlockGap`,',
+  '   `spaceItemGap` (spacing roles: band padding, row gap, block gutter,',
+  '   within-block gap).',
+  '3. Find the body text style: `(await figma.getLocalTextStylesAsync())',
+  '   .find((s) => s.name === \'Body/Default\')`. Missing variables or style =',
+  '   the builder throws (bind-or-throw — the gap is in the token set; fix it',
+  '   there, never hardcode around it).',
+  '4. Prepend the two slots, then the snippet below, then the call:',
+  '',
+  '```js',
+  'const RECORD = /* the parsed .doc.json object */;',
+  'const CANONICAL_FP = \'/* canonicalFingerprint(RECORD), 16 hex chars */\';',
+  '// … the generated snippet …',
+  'const card = await figma.getNodeByIdAsync(cardNodeId);',
+  'const summary = await renderDocCard({ card, record: RECORD, vars, bodyTextStyle });',
+  '```',
+  '',
+  '5. Pass an explicit `timeout` (30000 is right for one card; the ~30s',
+  '   `figma_execute` ceiling fits a single card comfortably — render cards one',
+  '   call at a time, never batched).',
+  '6. Verify from the returned summary — `rowsRendered`, `blocksCreated`,',
+  '   `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.',
+  '',
+  '## The snippet',
+  '',
+  '```js',
+].join('\n');
+
+const FOOTER = [
+  '```',
+  '',
+  'Layout contract and rationale:',
+  '`docs/superpowers/specs/2026-08-09-doc-card-layout-and-voice-design.md`.',
+  '',
+].join('\n');
+
+export function buildDocCardBuilder({ plannerSource, rendererSource }) {
+  const inlined = plannerSource
+    .replace(/^export const /gm, 'const ')
+    .replace(/^export function /gm, 'function ');
+  for (const [name, src] of [['doc-card-plan.mjs', inlined], ['doc-card-render.figma.js', rendererSource]]) {
+    if (/^\s*(import|export)\b/m.test(src)) {
+      throw new Error(`${name} must stay import-free (only top-level \`export const\`/\`export function\` allowed in the planner) — it is inlined into the Figma snippet where no module system exists`);
+    }
+  }
+  return `${HEADER}\n${inlined}\n${rendererSource}${FOOTER}`;
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  const result = buildDocCardBuilder({
+    plannerSource: readFileSync(PLANNER, 'utf8'),
+    rendererSource: readFileSync(RENDERER, 'utf8'),
+  });
+  if (process.argv.includes('--check')) {
+    let onDisk = null;
+    try { onDisk = readFileSync(OUT, 'utf8'); } catch (e) { /* missing counts as drift */ }
+    if (onDisk !== result) {
+      console.error('✗ references/doc-card-builder.md out of date; run: node scripts/build-doc-card-builder.mjs');
+      process.exit(1);
+    }
+    console.log('✓ doc-card builder in sync');
+  } else {
+    writeFileSync(OUT, result);
+    console.log('✓ wrote references/doc-card-builder.md');
+  }
+}

package/scripts/build-docs-digest.mjs

@@ -0,0 +1,74 @@
+// docs:digest — aggregates every component doc record into two AI-facing
+// artifacts: index.json (machine map) and llms.txt (narrative index).
+// Zero dependencies.
+//
+// Usage: node build-docs-digest.mjs [--root <dir>]
+import { readdirSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { parseArgs } from 'node:util';
+import { pathToFileURL } from 'node:url';
+import { loadRecord } from './lib/doc-record.mjs';
+
+const DOCS_DIR = join('design-system', 'docs');
+const COMPONENTS_DIR = join(DOCS_DIR, 'components');
+
+export function buildIndex(records) {
+  return {
+    generatedFrom: 'design-system/docs/components/*.doc.json',
+    components: records.map((r) => ({
+      name: r.name,
+      summary: r.summary ?? '',
+      description: r.description ?? '',
+      whenToUse: r.whenToUse ?? [],
+      whenNotToUse: r.whenNotToUse ?? [],
+      variants: r.variants ?? {},
+      states: r.states ?? {},
+      dos: r.dos ?? [],
+      donts: r.donts ?? [],
+      accessibility: r.accessibility ?? {},
+      tokensUsed: r.tokensUsed ?? [],
+      status: r.status ?? 'draft',
+    })),
+  };
+}
+
+export function buildLlmsTxt(records) {
+  const lines = ['# Design system — component usage guide', ''];
+  lines.push('Generated documentation for AI and human consumers. One section per component.', '');
+  for (const r of records) {
+    lines.push(`## ${r.name}`, '');
+    if (r.summary) lines.push(r.summary, '');
+    if (r.description) lines.push(r.description, '');
+    if ((r.whenToUse ?? []).length) lines.push('**When to use:** ' + r.whenToUse.join('; '));
+    if ((r.whenNotToUse ?? []).length) lines.push('**When not to use:** ' + r.whenNotToUse.join('; '));
+    if ((r.dos ?? []).length) lines.push('**Do:** ' + r.dos.join('; '));
+    if ((r.donts ?? []).length) lines.push("**Don't:** " + r.donts.join('; '));
+    if ((r.tokensUsed ?? []).length) lines.push('**Tokens:** ' + r.tokensUsed.join(', '));
+    lines.push('');
+  }
+  return lines.join('\n');
+}
+
+export function loadAllRecords(root) {
+  const dir = join(root, COMPONENTS_DIR);
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir)
+    .filter((f) => f.endsWith('.doc.json'))
+    .sort()
+    .map((f) => loadRecord(join(dir, f)));
+}
+
+function main() {
+  const { values } = parseArgs({ options: { root: { type: 'string', default: '.' } } });
+  const root = values.root;
+  const records = loadAllRecords(root);
+  const outDir = join(root, DOCS_DIR);
+  if (!existsSync(outDir)) mkdirSync(outDir, { recursive: true });
+  writeFileSync(join(outDir, 'index.json'), JSON.stringify(buildIndex(records), null, 2) + '\n');
+  writeFileSync(join(outDir, 'llms.txt'), buildLlmsTxt(records));
+  console.log(`✓ docs:digest — ${records.length} component(s) → design-system/docs/{index.json,llms.txt}`);
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  main();
+}

package/scripts/docs-check.mjs

@@ -0,0 +1,117 @@
+// docs:check — the documentation drift gate. Compares each component's canonical
+// record and its rendered surfaces against the fingerprints recorded in
+// design-system.json, and reports drift. Zero dependencies.
+//
+// Drift classes: canonical-changed | stale | edited | missing-surface | edit-unverified
+//                | layout-upgrade-available
+// (edit-unverified = a surface the CLI cannot read, e.g. Figma — informational;
+//  it is checked live by the Figma-connected skill instead.
+//  missing-surface = a repo surface that declares a file which is now gone — failing;
+//  distinct from edit-unverified, which has no file to read in the first place.
+//  layout-upgrade-available = informational, docCard only: the card's layout
+//  predates DOC_CARD_RENDERER_VERSION — re-render on next touch, never a failure.)
+//
+// Usage: node docs-check.mjs [--root <dir>]   (default root: cwd)
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { parseArgs } from 'node:util';
+import { pathToFileURL } from 'node:url';
+import { loadRecord, canonicalFingerprint, fingerprint } from './lib/doc-record.mjs';
+import { DOC_CARD_RENDERER_VERSION } from './lib/doc-card-plan.mjs';
+
+// Surfaces whose rendered content the CLI can re-read from the repo.
+const REPO_SURFACES = new Set(['storybookMdx']);
+
+export function classifySurface({ currentCanonical, surface, currentRenderHash, fileMissing = false, expectedRenderer = null }) {
+  const flags = [];
+  if (surface.src !== currentCanonical) flags.push('stale');
+  if (fileMissing) {
+    flags.push('missing-surface');
+  } else if (currentRenderHash === null) {
+    flags.push('edit-unverified');
+  } else if (surface.render !== currentRenderHash) {
+    flags.push('edited');
+  }
+  if (expectedRenderer !== null
+      && (!surface.renderer || Number(surface.renderer) < Number(expectedRenderer))) {
+    flags.push('layout-upgrade-available');
+  }
+  return flags;
+}
+
+export function checkComponent({ name, meta, root }) {
+  const out = [];
+  const doc = meta && meta.doc;
+  if (!doc) return out;
+
+  const recordPath = join(root, doc.path);
+  if (!existsSync(recordPath)) {
+    out.push({ name, surface: 'canonical', flags: ['missing-record'] });
+    return out;
+  }
+  const currentCanonical = canonicalFingerprint(loadRecord(recordPath));
+  if (currentCanonical !== doc.fingerprint) {
+    out.push({ name, surface: 'canonical', flags: ['canonical-changed'] });
+  }
+
+  for (const [surfaceName, surface] of Object.entries(doc.surfaces || {})) {
+    let currentRenderHash = null;
+    let fileMissing = false;
+    if (REPO_SURFACES.has(surfaceName) && surface.file) {
+      const filePath = join(root, surface.file);
+      if (existsSync(filePath)) {
+        currentRenderHash = fingerprint(readFileSync(filePath, 'utf8'));
+      } else {
+        fileMissing = true;
+      }
+    }
+    const flags = classifySurface({
+      currentCanonical, surface, currentRenderHash, fileMissing,
+      expectedRenderer: surfaceName === 'docCard' ? DOC_CARD_RENDERER_VERSION : null,
+    });
+    if (flags.length) out.push({ name, surface: surfaceName, flags });
+  }
+  return out;
+}
+
+export function checkAll(manifest, root) {
+  const out = [];
+  const meta = (manifest && manifest.components && manifest.components.meta) || {};
+  for (const [name, m] of Object.entries(meta)) {
+    out.push(...checkComponent({ name, meta: m, root }));
+  }
+  return out;
+}
+
+const FAILING = new Set(['canonical-changed', 'stale', 'edited', 'missing-record', 'missing-surface']);
+
+function main() {
+  const { values } = parseArgs({ options: { root: { type: 'string', default: '.' } } });
+  const root = values.root;
+  const manifestPath = join(root, 'design-system.json');
+  if (!existsSync(manifestPath)) {
+    console.error(`docs:check — no design-system.json at ${root}`);
+    process.exit(1);
+  }
+  const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+  const results = checkAll(manifest, root);
+
+  const drift = results.filter((r) => r.flags.some((f) => FAILING.has(f)));
+  const info = results.filter((r) => !r.flags.some((f) => FAILING.has(f)));
+
+  for (const r of drift) console.error(`  ✗ ${r.name} · ${r.surface}: ${r.flags.join(', ')}`);
+  for (const r of info) {
+    const note = r.flags.includes('edit-unverified') ? ' (check in a Figma session)' : '';
+    console.log(`  ~ ${r.name} · ${r.surface}: ${r.flags.join(', ')}${note}`);
+  }
+
+  if (drift.length) {
+    console.error(`✗ docs:check — ${drift.length} drifted surface(s); reconcile with /document-component`);
+    process.exit(1);
+  }
+  console.log(`✓ docs:check — no drift${info.length ? ` (${info.length} Figma surface(s) unverified)` : ''}`);
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  main();
+}

package/scripts/docs-lint.mjs

@@ -0,0 +1,163 @@
+#!/usr/bin/env node
+// Copy lint for component doc records (.doc.json). Warnings only — findings
+// never affect the exit code; the lint shapes a draft before user approval
+// rather than gating CI. Rules: references/doc-writing-standard.md (pinned in
+// the design spec's lint table).
+//
+// Usage: node docs-lint.mjs <path/to/Component.doc.json> [--json]
+// Output: one warning per line — `<file>: <block-path>: <rule>: <message>`;
+// --json emits {"warnings":[{path, rule, message}]}.
+// Exit: 0 for any parseable record; 2 for unusable invocation.
+
+import { readFileSync } from 'node:fs';
+import { pathToFileURL } from 'node:url';
+
+// Machinery vocabulary banned from user-facing prose — the system's own
+// build-compliance language. Real names of things (aria-label, role, Enter)
+// are not banned; readers search for those.
+const MACHINERY = [
+  'token', 'tokens', 'variable', 'variables', 'binding', 'bindings',
+  'fingerprint', 'fingerprints', 'provenance', 'projection', 'projections',
+  'surface', 'surfaces',
+];
+
+// Visual-treatment words that must not LEAD a variant/state meaning.
+const TREATMENT = [
+  'fill', 'filled', 'solid', 'stroke', 'border', 'bordered', 'outline',
+  'shadow', 'opacity', 'elevation',
+];
+
+const STOPWORDS = new Set([
+  'a', 'an', 'the', 'and', 'or', 'but', 'of', 'to', 'in', 'on', 'for',
+  'with', 'as', 'at', 'by', 'is', 'are', 'was', 'were', 'be', 'been', 'it',
+  'its', 'this', 'that', 'these', 'those', 'you', 'your', 'not', 'no', 'do',
+  'does', 'did', 'has', 'have', 'had', 'can', 'could', 'should', 'would',
+  'will', 'may', 'might', 'must', 'when', 'how', 'what', 'which', 'who',
+  'while', 'than', 'then', 'so', 'if', 'into', 'onto', 'from', 'over',
+  'under', 'up', 'down', 'out', 'about',
+]);
+
+const words = (s) => String(s).toLowerCase().match(/[a-z0-9'’-]+/g) || [];
+// Naive plural/verb-s stemming: enough to match "Triggers" to "trigger".
+const stem = (w) => (w.length > 3 && w.endsWith('s') ? w.slice(0, -1) : w);
+
+export function lintRecord(record) {
+  const warnings = [];
+  const warn = (path, rule, message) => warnings.push({ path, rule, message });
+
+  // Every user-facing prose field, as [block-path, text].
+  const prose = [];
+  if (typeof record.summary === 'string') prose.push(['summary', record.summary]);
+  if (typeof record.description === 'string') prose.push(['description', record.description]);
+  for (const key of ['whenToUse', 'whenNotToUse', 'dos', 'donts']) {
+    (Array.isArray(record[key]) ? record[key] : []).forEach((t, i) => prose.push([`${key}[${i}]`, t]));
+  }
+  const meanings = [];
+  for (const axis of Object.keys(record.variants || {})) {
+    for (const [term, meaning] of Object.entries(record.variants[axis] || {})) {
+      meanings.push([`variants.${axis}.${term}`, meaning]);
+    }
+  }
+  for (const [term, meaning] of Object.entries(record.states || {})) {
+    meanings.push([`states.${term}`, meaning]);
+  }
+  prose.push(...meanings);
+  const a11y = record.accessibility || {};
+  (Array.isArray(a11y.keyboard) ? a11y.keyboard : []).forEach((t, i) => prose.push([`accessibility.keyboard[${i}]`, t]));
+  (Array.isArray(a11y.notes) ? a11y.notes : []).forEach((t, i) => prose.push([`accessibility.notes[${i}]`, t]));
+
+  for (const [path, text] of prose) {
+    const ws = words(text);
+    const banned = MACHINERY.find((b) => ws.includes(b));
+    if (banned) {
+      warn(path, 'machinery-vocabulary',
+        `"${banned}" is the system's machinery vocabulary — describe the thing and how to use it, never how it was made`);
+    }
+    if (/`[^`]+`/.test(String(text))) {
+      warn(path, 'no-inline-code',
+        'inline-code backticks render as literal characters on the doc card and are stripped from the Figma description — write the term as plain text');
+    }
+    for (const sentence of String(text).split(/[.!?]+/)) {
+      const n = words(sentence).length;
+      if (n > 35) warn(path, 'run-on-sentence', `sentence has ${n} words (max 35)`);
+    }
+  }
+
+  if (typeof record.summary === 'string') {
+    const n = words(record.summary).length;
+    if (n > 12) warn('summary', 'summary-length', `${n} words (max 12)`);
+  }
+
+  if (typeof record.description === 'string') {
+    const n = words(record.description).length;
+    if (n < 15 || n > 70) warn('description', 'description-length', `${n} words (want 15–70)`);
+  }
+
+  if (typeof record.summary === 'string' && Array.isArray(record.whenToUse)
+      && typeof record.whenToUse[0] === 'string') {
+    const summaryStems = [...new Set(
+      words(record.summary).filter((w) => !STOPWORDS.has(w)).map(stem),
+    )];
+    const targetStems = new Set(words(record.whenToUse[0]).map(stem));
+    if (summaryStems.length > 0) {
+      const matched = summaryStems.filter((s) => targetStems.has(s)).length;
+      const pct = matched / summaryStems.length;
+      if (pct > 0.6) {
+        warn('whenToUse[0]', 'summary-echo',
+          `${Math.round(pct * 100)}% of the summary's content words reappear — describe a situation, not the summary again`);
+      }
+    }
+  }
+
+  for (const key of ['dos', 'donts']) {
+    (Array.isArray(record[key]) ? record[key] : []).forEach((entry, i) => {
+      const path = `${key}[${i}]`;
+      const n = words(entry).length;
+      if (n > 14) warn(path, 'guidance-length', `${n} words (max 14)`);
+      if (!/\.$/.test(String(entry).trim())) {
+        warn(path, 'terminal-stop', 'end the entry with a full stop');
+      }
+      if (key === 'donts' && !/^(don['’]?t|do not|never|avoid)\b/i.test(String(entry).trim())) {
+        warn(path, 'dont-shape', "open with Don't / Never / Avoid and name the alternative");
+      }
+    });
+  }
+
+  for (const [path, meaning] of meanings) {
+    const ws = words(meaning);
+    if (ws.length < 3) {
+      warn(path, 'empty-meaning', `${ws.length} word(s) — say what it means, not just that it exists`);
+    }
+    if (ws.slice(0, 4).some((w) => TREATMENT.includes(w))) {
+      warn(path, 'treatment-lead', 'leads with visual treatment — lead with meaning; treatment is optional detail');
+    }
+  }
+
+  return warnings;
+}
+
+const invokedAsCli = process.argv[1]
+  && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (invokedAsCli) {
+  const args = process.argv.slice(2);
+  const asJson = args.includes('--json');
+  const file = args.find((a) => !a.startsWith('--'));
+  if (!file) {
+    console.error('usage: docs-lint.mjs <path/to/Component.doc.json> [--json]');
+    process.exit(2);
+  }
+  let record;
+  try {
+    record = JSON.parse(readFileSync(file, 'utf8'));
+  } catch (e) {
+    console.error(`docs-lint: cannot read ${file}: ${e.message}`);
+    process.exit(2);
+  }
+  const warnings = lintRecord(record);
+  if (asJson) {
+    console.log(JSON.stringify({ warnings }, null, 2));
+  } else {
+    for (const w of warnings) console.log(`${file}: ${w.path}: ${w.rule}: ${w.message}`);
+  }
+  process.exit(0);
+}

package/scripts/install.mjs

@@ -99,6 +99,18 @@ function stagePayload(srcRoot, destRoot, skip) {
   return written;
 }
 
+// Scripts that never run from a consuming repo: the installer itself, the
+// doc-card builder generator, and the renderer template it inlines (the
+// renderer reaches Figma pre-inlined inside references/doc-card-builder.md).
+const PLUGIN_INTERNAL = new Set([
+  'install.mjs',
+  'build-doc-card-builder.mjs',
+  'lib/doc-card-render.figma.js',
+]);
+
+export const skipScript = (relPosix) =>
+  relPosix.startsWith('adapters/') || relPosix.endsWith('.test.mjs') || PLUGIN_INTERNAL.has(relPosix);
+
 export function install({ target, dir, pkgRoot = PKG_ROOT }) {
   if (!TARGETS.includes(target)) {
     throw new Error(`unknown target "${target}"; expected one of: ${TARGETS.join(', ')}`);
@@ -124,7 +136,7 @@ export function install({ target, dir, pkgRoot = PKG_ROOT }) {
   }
   const payload = [
     ...stagePayload(join(pkgRoot, 'references'), join(dir, BASE, 'references')),
-    ...stagePayload(join(pkgRoot, 'scripts'), join(dir, BASE, 'scripts'), (r) => r.startsWith('adapters/') || r.endsWith('.test.mjs') || r === 'install.mjs'),
+    ...stagePayload(join(pkgRoot, 'scripts'), join(dir, BASE, 'scripts'), skipScript),
   ];
   return { target, dir, written, payload };
 }

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

@@ -0,0 +1,101 @@
+// Pure layout planner for the component doc card's Usage band.
+// ZERO imports, `export const`/`export function` only — this module is inlined
+// verbatim into the generated Figma snippet (references/doc-card-builder.md) by
+// build-doc-card-builder.mjs, so it must run in both Node and the Figma plugin
+// sandbox. build-doc-card-builder.mjs enforces the no-imports rule.
+//
+// Layout contract: docs/superpowers/specs/2026-08-09-doc-card-layout-and-voice-design.md
+
+// Single source of truth for the doc-card layout version. Imported by
+// docs-check.mjs and embedded (via inlining) into the generated builder snippet.
+export const DOC_CARD_RENDERER_VERSION = '4';
+
+// columnUnit = clamp(round(bodyFontSize × 30), 280, 480) px.
+// 30 ≈ 60ch × ~0.5em average glyph width for UI text faces. Layout chrome, not
+// a design value — the one documented exception to the no-hardcoded-px rule.
+export function columnUnit(bodyFontSize) {
+  return Math.min(480, Math.max(280, Math.round(bodyFontSize * 30)));
+}
+
+// columns = max(max blocks in any row, 3). Content alone decides: the grid
+// never mints a column no row can fill, and never drops below the 3-unit floor.
+// The specimen is deliberately NOT an input — the render widens the card, the
+// card's hug propagates into FILL siblings including the specimen, so any
+// specimen measurement is a value this render mutates and the next one reads.
+export function cardColumns(maxBlocksPerRow) {
+  return Math.max(3, maxBlocksPerRow);
+}
+
+function listBlock(eyebrow, items) {
+  if (!Array.isArray(items) || items.length === 0) return null;
+  return { type: 'list', name: `Block: ${eyebrow}`, eyebrow, items };
+}
+
+function definitionBlock(eyebrow, meanings) {
+  const terms = Object.keys(meanings || {}).map((k) => ({ term: k, meaning: meanings[k] }));
+  if (terms.length === 0) return null;
+  return { type: 'definition', name: `Block: ${eyebrow}`, eyebrow, terms };
+}
+
+// The whole layout decision, as data. Rows keep canonical numbering (an absent
+// row's number is skipped, never renumbered) so node names stay stable across
+// sparse records. bodyTextStyle: only .fontSize is read — passing a full Figma
+// TextStyle object is fine.
+export function planDocCard(record, bodyTextStyle) {
+  const unit = columnUnit(bodyTextStyle.fontSize);
+
+  const row1 = [];
+  if (typeof record.description === 'string' && record.description.trim() !== '') {
+    row1.push({ type: 'prose', name: 'Block: Overview', eyebrow: 'Overview', text: record.description });
+  }
+  const whenTo = listBlock('When to use', record.whenToUse);
+  if (whenTo) row1.push(whenTo);
+  const whenNot = listBlock('When not to use', record.whenNotToUse);
+  if (whenNot) row1.push(whenNot);
+
+  const row2 = [];
+  if (Array.isArray(record.dos) && record.dos.length) {
+    row2.push({ type: 'list-tone', name: 'Block: Do', eyebrow: '✓ Do', tone: 'positive', items: record.dos });
+  }
+  if (Array.isArray(record.donts) && record.donts.length) {
+    row2.push({ type: 'list-tone', name: "Block: Don't", eyebrow: "✕ Don't", tone: 'negative', items: record.donts });
+  }
+
+  const row3 = [];
+  for (const axis of Object.keys(record.variants || {})) {
+    const block = definitionBlock(`What each ${axis} means`, record.variants[axis]);
+    if (block) row3.push(block);
+  }
+  const stateBlock = definitionBlock('What each state means', record.states);
+  if (stateBlock) row3.push(stateBlock);
+  const a11y = record.accessibility || {};
+  // role is not rendered on the card — it lives in the description field / MDX.
+  const a11yBlock = listBlock('Accessibility', [...(a11y.keyboard || []), ...(a11y.notes || [])]);
+  if (a11yBlock) row3.push(a11yBlock);
+
+  const rows = [
+    { name: 'Usage Row 1', blocks: row1 },
+    { name: 'Usage Row 2', blocks: row2 },
+    { name: 'Usage Row 3', blocks: row3 },
+  ].filter((r) => r.blocks.length > 0);
+
+  const maxBlocksPerRow = rows.reduce((m, r) => Math.max(m, r.blocks.length), 0);
+  const columns = cardColumns(maxBlocksPerRow);
+
+  return {
+    rendererVersion: DOC_CARD_RENDERER_VERSION,
+    columnUnit: unit,
+    columns,
+    cardWidth: columns * unit,
+    termColumn: Math.round(unit * 0.3),
+    // The header band's record-derived content. Carried in the plan (not read
+    // straight off the record by the renderer) so renderHash describes every
+    // string the builder writes onto the card, header included. Always strings:
+    // an undefined would drop the key from JSON.stringify and move the hash.
+    header: {
+      summary: typeof record.summary === 'string' ? record.summary : '',
+      updatedAt: typeof record.updatedAt === 'string' ? record.updatedAt : '',
+    },
+    rows,
+  };
+}