@radicool/throughline 0.14.0 → 0.16.0

package/scripts/docs-check.mjs

@@ -3,10 +3,13 @@
 // 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.)
+//  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';
@@ -14,11 +17,12 @@ 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 }) {
+export function classifySurface({ currentCanonical, surface, currentRenderHash, fileMissing = false, expectedRenderer = null }) {
   const flags = [];
   if (surface.src !== currentCanonical) flags.push('stale');
   if (fileMissing) {
@@ -28,6 +32,10 @@ export function classifySurface({ currentCanonical, surface, currentRenderHash,
   } 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;
 }
 
@@ -57,7 +65,10 @@ export function checkComponent({ name, meta, root }) {
         fileMissing = true;
       }
     }
-    const flags = classifySurface({ currentCanonical, surface, currentRenderHash, fileMissing });
+    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;
@@ -89,7 +100,10 @@ function main() {
   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) console.log(`  ~ ${r.name} · ${r.surface}: ${r.flags.join(', ')} (check in a Figma session)`);
+  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`);

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,19 @@ function stagePayload(srcRoot, destRoot, skip) {
   return written;
 }
 
+// Scripts that never run from a consuming repo: the installer itself, the two
+// reference-doc generators, and the renderer template one of them 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',
+  'build-native-adapter-config.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 +137,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,
+  };
+}