@sarjallab09/figma-intelligence 1.0.0

package/figma-intelligence-layer/src/tools/phase5-governance/taxonomy-docs/index.ts

@@ -0,0 +1,406 @@
+/**
+ * figma_taxonomy_docs — Living concept taxonomy documentation
+ *
+ * Generates documentation for the semantic token naming convention by
+ * cross-referencing the concept taxonomy with actual Figma variables.
+ * Supports markdown, JSON, and Figma page output formats.
+ *
+ * The Figma page output supports auto-sync: when variables change in the
+ * file, the documentation page updates automatically.
+ */
+
+import { getBridge } from "../../../shared/figma-bridge.js";
+import {
+  CONCEPT_TAXONOMY,
+  GRAMMAR,
+  getConceptById,
+  getRequiredTokenPaths,
+  getAllTokenPaths,
+  type ConceptDefinition,
+} from "../../../shared/concept-taxonomy.js";
+import { renderMarkdown } from "./renderers/markdown.js";
+import { renderJson } from "./renderers/json.js";
+import { renderFigmaPage } from "./renderers/figma-page.js";
+import { renderNamingGuide } from "./renderers/naming-guide.js";
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+export interface TaxonomyDocsArgs {
+  outputFormat: "markdown" | "json" | "figma" | "naming-guide";
+  concepts?: string[];
+  includeTokenAnatomy?: boolean;
+  showCoverage?: boolean;
+  autoSync?: boolean;
+  pageName?: string;
+}
+
+export interface TaxonomyDocsResult {
+  ok: boolean;
+  format: TaxonomyDocsArgs["outputFormat"];
+  conceptCount: number;
+  tokenCount: number;
+  output: string | TaxonomyDocsJsonOutput;
+  coverage: ConceptCoverage[];
+  notes: string[];
+  autoSyncEnabled?: boolean;
+  pageId?: string;
+}
+
+export interface ConceptCoverage {
+  conceptId: string;
+  conceptName: string;
+  purpose: string;
+  status: "full" | "partial" | "missing";
+  expectedTokens: string[];
+  foundTokens: string[];
+  missingTokens: string[];
+  /** Maps expected token path → actual file token name that matched (for fuzzy matches) */
+  matchedFileTokens: Record<string, string>;
+  typicalForms: string[];
+  validStates: string[];
+  validVariants: string[];
+}
+
+export interface TaxonomyDocsJsonOutput {
+  generatedAt: string;
+  grammar: typeof GRAMMAR;
+  concepts: ConceptCoverage[];
+  totalExpected: number;
+  totalFound: number;
+  totalMissing: number;
+  tokenValues: Record<string, TokenValueSnapshot>;
+}
+
+export interface TokenValueSnapshot {
+  name: string;
+  type: string;
+  collection: string;
+  values: Record<string, unknown>;
+}
+
+// ─── Core Logic ─────────────────────────────────────────────────────────────
+
+interface RawVariable {
+  id: string;
+  name: string;
+  type: string;
+  resolvedType?: string;
+  description?: string;
+  valuesByMode?: Record<string, unknown>;
+}
+
+interface RawCollection {
+  id: string;
+  name: string;
+  modes: Array<{ modeId: string; name: string }>;
+  variables: RawVariable[];
+}
+
+/**
+ * Build a set of all token names present in the Figma file.
+ * Also builds a map of name → snapshot for value rendering.
+ */
+function indexFileTokens(collections: RawCollection[]): {
+  tokenNames: Set<string>;
+  snapshots: Record<string, TokenValueSnapshot>;
+} {
+  const tokenNames = new Set<string>();
+  const snapshots: Record<string, TokenValueSnapshot> = {};
+
+  for (const coll of collections) {
+    for (const v of coll.variables) {
+      const name = v.name;
+      tokenNames.add(name);
+
+      // Also index with common prefix variations for fuzzy matching
+      const segments = name.split("/");
+      if (segments.length > 2) {
+        // Allow suffix matching: "actions/primary/bg/default" matches "color/semantic/actions/primary/bg/default"
+        tokenNames.add(segments.slice(1).join("/"));
+        tokenNames.add(segments.slice(2).join("/"));
+      }
+
+      snapshots[name] = {
+        name,
+        type: v.resolvedType ?? v.type,
+        collection: coll.name,
+        values: v.valuesByMode ?? {},
+      };
+    }
+  }
+
+  return { tokenNames, snapshots };
+}
+
+/**
+ * Check which expected tokens exist for each concept.
+ */
+function computeCoverage(
+  concepts: ConceptDefinition[],
+  tokenNames: Set<string>,
+): ConceptCoverage[] {
+  return concepts.map((concept) => {
+    const allPaths = getAllTokenPaths(concept.id);
+    const requiredPaths = getRequiredTokenPaths(concept.id);
+
+    const foundTokens: string[] = [];
+    const missingTokens: string[] = [];
+    const matchedFileTokens: Record<string, string> = {};
+
+    for (const path of allPaths) {
+      const match = tokenNameMatch(path, tokenNames);
+      if (match) {
+        foundTokens.push(path);
+        if (match !== path) {
+          matchedFileTokens[path] = match;
+        }
+      } else {
+        missingTokens.push(path);
+      }
+    }
+
+    // Coverage status based on required tokens
+    const requiredFound = requiredPaths.filter((p) => tokenNameMatch(p, tokenNames) !== null);
+    let status: ConceptCoverage["status"];
+    if (requiredFound.length === requiredPaths.length) {
+      status = "full";
+    } else if (requiredFound.length > 0 || foundTokens.length > 0) {
+      status = "partial";
+    } else {
+      status = "missing";
+    }
+
+    return {
+      conceptId: concept.id,
+      conceptName: concept.id.charAt(0).toUpperCase() + concept.id.slice(1),
+      purpose: concept.purpose,
+      status,
+      expectedTokens: allPaths,
+      foundTokens,
+      missingTokens,
+      matchedFileTokens,
+      typicalForms: concept.typicalForms,
+      validStates: concept.validStates,
+      validVariants: concept.validVariants,
+    };
+  });
+}
+
+// ─── Semantic keyword synonyms for fuzzy role matching ────────────────────
+// Maps each semantic keyword to a set of equivalent terms found in real
+// design-system token names (Carbon, MUI, Ant, Fluent, Polaris, etc.).
+
+const KEYWORD_SYNONYMS: Record<string, string[]> = {
+  // Concept synonyms
+  actions:    ["action", "actions", "btn", "button", "cta", "link"],
+  field:      ["field", "input", "text-input", "textfield", "form", "select", "textarea"],
+  surface:    ["surface", "card", "panel", "container", "paper", "well", "layer", "bg"],
+  navigation: ["nav", "navigation", "tab", "tabs", "breadcrumb", "sidebar", "appbar", "navbar"],
+  feedback:   ["feedback", "alert", "toast", "banner", "snackbar", "notification", "callout", "message"],
+  // Property synonyms
+  bg:         ["bg", "background", "fill", "surface", "base"],
+  text:       ["text", "label", "foreground", "fg", "content", "on"],
+  icon:       ["icon", "glyph", "symbol"],
+  border:     ["border", "stroke", "outline", "divider", "separator", "edge"],
+  ring:       ["ring", "focus-ring", "outline", "focus"],
+  shadow:     ["shadow", "elevation", "drop-shadow", "box-shadow"],
+  inset:      ["inset", "padding", "pad", "spacing", "inner"],
+  gap:        ["gap", "gutter", "stack", "spacing"],
+  // State synonyms
+  hover:      ["hover", "hovered", "over"],
+  active:     ["active", "pressed", "down", "tap"],
+  focus:      ["focus", "focused", "keyboard"],
+  disabled:   ["disabled", "inactive", "muted", "dimmed"],
+  // Variant synonyms
+  primary:    ["primary", "main", "brand", "accent", "key"],
+  secondary:  ["secondary", "subtle", "alt", "alternative"],
+  ghost:      ["ghost", "text", "plain", "minimal", "bare", "link"],
+  destructive:["destructive", "danger", "error", "critical", "negative", "red"],
+};
+
+/**
+ * Extract semantic keywords from a token path.
+ * E.g. "color/semantic/actions/primary/bg/default" → ["color","semantic","actions","primary","bg","default"]
+ */
+function extractKeywords(path: string): string[] {
+  return path
+    .toLowerCase()
+    .split(/[\/\-_.]+/)
+    .filter(Boolean);
+}
+
+/**
+ * Check if a candidate token matches the semantic role described by `path`
+ * by checking whether the candidate contains synonyms for the key segments.
+ */
+function semanticKeywordMatch(expectedPath: string, candidateName: string): boolean {
+  const expectedKw = extractKeywords(expectedPath);
+  const candidateNorm = candidateName.toLowerCase().replace(/[\/\-_.]+/g, " ");
+
+  // Identify the "meaningful" keywords from the expected path —
+  // skip structural words like "semantic", "default", "control"
+  const STRUCTURAL = new Set(["semantic", "default", "control", "md", "sm", "lg"]);
+  const meaningfulKw = expectedKw.filter((kw) => !STRUCTURAL.has(kw));
+
+  if (meaningfulKw.length === 0) return false;
+
+  // For each meaningful keyword, check if the candidate contains
+  // that keyword or any of its synonyms
+  let matchCount = 0;
+  for (const kw of meaningfulKw) {
+    const synonyms = KEYWORD_SYNONYMS[kw] ?? [kw];
+    const allTerms = [kw, ...synonyms];
+    if (allTerms.some((term) => candidateNorm.includes(term))) {
+      matchCount++;
+    }
+  }
+
+  // Require at least 2 meaningful keyword matches (or all if fewer than 2)
+  const threshold = Math.min(2, meaningfulKw.length);
+  return matchCount >= threshold;
+}
+
+/**
+ * Check if a token name exists in the file tokens.
+ * Uses three strategies in order:
+ * 1. Exact match
+ * 2. Suffix / normalized match
+ * 3. Semantic keyword match (catches tokens named differently but serving the same role)
+ *
+ * Returns the matched file token name, or null if no match.
+ */
+function tokenNameMatch(path: string, tokenNames: Set<string>): string | null {
+  // 1. Exact match
+  if (tokenNames.has(path)) return path;
+
+  // 2. Suffix match — some files prefix with collection name
+  for (const existing of tokenNames) {
+    if (existing.endsWith(`/${path}`) || existing.endsWith(path)) return existing;
+  }
+
+  // 3. Normalized comparison
+  const normalized = path.toLowerCase().replace(/[\/\-_]/g, "");
+  for (const existing of tokenNames) {
+    const n = existing.toLowerCase().replace(/[\/\-_]/g, "");
+    if (n === normalized || n.endsWith(normalized)) return existing;
+  }
+
+  // 4. Semantic keyword matching — find a token that semantically serves the same role
+  for (const existing of tokenNames) {
+    if (semanticKeywordMatch(path, existing)) return existing;
+  }
+
+  return null;
+}
+
+/**
+ * Check if a token name exists in the file tokens, with fuzzy matching.
+ */
+function tokenNameExists(path: string, tokenNames: Set<string>): boolean {
+  return tokenNameMatch(path, tokenNames) !== null;
+}
+
+// ─── Handler ────────────────────────────────────────────────────────────────
+
+export async function taxonomyDocsHandler(args: TaxonomyDocsArgs): Promise<TaxonomyDocsResult> {
+  const bridge = await getBridge();
+  const notes: string[] = [];
+
+  // Fetch actual tokens from the Figma file
+  let collections: RawCollection[] = [];
+  try {
+    collections = (await bridge.getVariables(undefined, "full")) as unknown as RawCollection[];
+  } catch {
+    notes.push("Could not fetch Figma variables — coverage report will show all tokens as missing.");
+  }
+
+  const { tokenNames, snapshots } = indexFileTokens(collections);
+  notes.push(`Indexed ${tokenNames.size} token names from ${collections.length} collections.`);
+
+  // Filter concepts if requested
+  let concepts = CONCEPT_TAXONOMY;
+  if (args.concepts?.length) {
+    const filter = new Set(args.concepts.map((c) => c.toLowerCase()));
+    concepts = concepts.filter((c) => filter.has(c.id));
+    if (concepts.length === 0) {
+      return {
+        ok: false,
+        format: args.outputFormat,
+        conceptCount: 0,
+        tokenCount: 0,
+        output: "No matching concepts found. Available: " + CONCEPT_TAXONOMY.map((c) => c.id).join(", "),
+        coverage: [],
+        notes: ["Filter matched 0 concepts."],
+      };
+    }
+  }
+
+  // Compute coverage
+  const coverage = computeCoverage(concepts, tokenNames);
+  const totalExpected = coverage.reduce((sum, c) => sum + c.expectedTokens.length, 0);
+  const totalFound = coverage.reduce((sum, c) => sum + c.foundTokens.length, 0);
+
+  // Render based on format
+  let output: string | TaxonomyDocsJsonOutput;
+  let pageId: string | undefined;
+  let autoSyncEnabled = false;
+
+  switch (args.outputFormat) {
+    case "markdown":
+      output = renderMarkdown(coverage, snapshots, {
+        includeTokenAnatomy: args.includeTokenAnatomy ?? true,
+        showCoverage: args.showCoverage ?? true,
+      });
+      break;
+
+    case "json":
+      output = renderJson(coverage, snapshots, totalExpected, totalFound);
+      break;
+
+    case "naming-guide":
+      output = renderNamingGuide(coverage);
+      break;
+
+    case "figma": {
+      const figmaOpts = {
+        pageName: args.pageName ?? "Token Taxonomy",
+        includeTokenAnatomy: args.includeTokenAnatomy ?? true,
+        showCoverage: args.showCoverage ?? true,
+        autoSync: args.autoSync ?? false,
+      };
+      const result = await renderFigmaPage(bridge, coverage, snapshots, figmaOpts);
+      pageId = result.pageId;
+      autoSyncEnabled = result.autoSyncEnabled;
+      output = `Figma page "${figmaOpts.pageName}" created with ${concepts.length} concepts. Page ID: ${pageId}`;
+
+      // Register auto-sync handler on the bridge
+      if (autoSyncEnabled && "setTaxonomyAutoSyncHandler" in bridge) {
+        const syncBridge = bridge as unknown as { setTaxonomyAutoSyncHandler: (h: (() => Promise<void>) | null) => void };
+        syncBridge.setTaxonomyAutoSyncHandler(async () => {
+          // Re-fetch tokens, recompute coverage, re-render page
+          let freshCollections: RawCollection[] = [];
+          try {
+            freshCollections = (await bridge.getVariables(undefined, "full")) as unknown as RawCollection[];
+          } catch { /* ignore — page will show all missing */ }
+          const fresh = indexFileTokens(freshCollections);
+          const freshCoverage = computeCoverage(concepts, fresh.tokenNames);
+          await renderFigmaPage(bridge, freshCoverage, fresh.snapshots, figmaOpts);
+        });
+        notes.push("Auto-sync enabled: documentation will update when variables change.");
+      }
+      break;
+    }
+  }
+
+  return {
+    ok: true,
+    format: args.outputFormat,
+    conceptCount: concepts.length,
+    tokenCount: totalFound,
+    output,
+    coverage,
+    notes,
+    autoSyncEnabled,
+    pageId,
+  };
+}

package/figma-intelligence-layer/src/tools/phase5-governance/taxonomy-docs/renderers/figma-page.ts

@@ -0,0 +1,292 @@
+/**
+ * Figma page renderer for taxonomy documentation.
+ * Creates a visual documentation page with concept tables, token anatomy,
+ * coverage badges, and color swatches — all from live Figma data.
+ *
+ * Supports auto-sync: stores the page name so the variable-change event
+ * handler can trigger a lightweight re-render.
+ */
+
+import type { ConceptCoverage, TokenValueSnapshot } from "../index.js";
+
+interface FigmaPageOptions {
+  pageName: string;
+  includeTokenAnatomy: boolean;
+  showCoverage: boolean;
+  autoSync: boolean;
+}
+
+interface FigmaPageResult {
+  pageId: string;
+  autoSyncEnabled: boolean;
+}
+
+// Module-level state for auto-sync
+let autoSyncPageName: string | null = null;
+
+export function getAutoSyncPageName(): string | null {
+  return autoSyncPageName;
+}
+
+export function clearAutoSync(): void {
+  autoSyncPageName = null;
+}
+
+function escapeJs(s: string): string {
+  return JSON.stringify(s);
+}
+
+function statusColor(status: ConceptCoverage["status"]): string {
+  if (status === "full") return "{ r: 0.13, g: 0.73, b: 0.33 }";
+  if (status === "partial") return "{ r: 0.95, g: 0.77, b: 0.06 }";
+  return "{ r: 0.85, g: 0.12, b: 0.12 }";
+}
+
+function statusLabel(status: ConceptCoverage["status"]): string {
+  if (status === "full") return "Full";
+  if (status === "partial") return "Partial";
+  return "Missing";
+}
+
+export async function renderFigmaPage(
+  bridge: { execute: (code: string) => Promise<{ success: boolean; result?: unknown }> },
+  coverage: ConceptCoverage[],
+  snapshots: Record<string, TokenValueSnapshot>,
+  options: FigmaPageOptions,
+): Promise<FigmaPageResult> {
+  const pageName = options.pageName;
+
+  // Track for auto-sync
+  if (options.autoSync) {
+    autoSyncPageName = pageName;
+  }
+
+  const lines: string[] = [];
+  lines.push(`(async () => {`);
+
+  // ── Create or find page ──
+  lines.push(`  let page = figma.root.children.find(p => p.name === ${escapeJs(pageName)});`);
+  lines.push(`  if (!page) {`);
+  lines.push(`    page = figma.createPage();`);
+  lines.push(`    page.name = ${escapeJs(pageName)};`);
+  lines.push(`  }`);
+  lines.push(`  figma.currentPage = page;`);
+  lines.push(``);
+
+  // Clear existing content
+  lines.push(`  for (const child of [...page.children]) { child.remove(); }`);
+  lines.push(``);
+
+  // ── Layout constants ──
+  lines.push(`  const COL_W = 260;`);
+  lines.push(`  const ROW_H = 36;`);
+  lines.push(`  const SECTION_GAP = 60;`);
+  lines.push(`  const HEADER_H = 48;`);
+  lines.push(`  let cursorY = 0;`);
+  lines.push(``);
+
+  // ── Helper: create text node ──
+  lines.push(`  async function txt(x, y, text, size, bold, color) {`);
+  lines.push(`    const t = figma.createText();`);
+  lines.push(`    await figma.loadFontAsync({ family: "Inter", style: bold ? "Bold" : "Regular" });`);
+  lines.push(`    t.fontName = { family: "Inter", style: bold ? "Bold" : "Regular" };`);
+  lines.push(`    t.fontSize = size;`);
+  lines.push(`    t.characters = String(text);`);
+  lines.push(`    t.x = x;`);
+  lines.push(`    t.y = y;`);
+  lines.push(`    if (color) t.fills = [{ type: "SOLID", color: color }];`);
+  lines.push(`    page.appendChild(t);`);
+  lines.push(`    return t;`);
+  lines.push(`  }`);
+  lines.push(``);
+
+  // ── Helper: create rectangle ──
+  lines.push(`  function rect(x, y, w, h, color, radius) {`);
+  lines.push(`    const r = figma.createRectangle();`);
+  lines.push(`    r.x = x; r.y = y; r.resize(w, h);`);
+  lines.push(`    r.fills = [{ type: "SOLID", color: color }];`);
+  lines.push(`    if (radius) r.cornerRadius = radius;`);
+  lines.push(`    page.appendChild(r);`);
+  lines.push(`    return r;`);
+  lines.push(`  }`);
+  lines.push(``);
+
+  // ── Title Section ──
+  lines.push(`  await txt(0, cursorY, "Token Taxonomy", 32, true);`);
+  lines.push(`  cursorY += 44;`);
+  lines.push(`  await txt(0, cursorY, "Generated ${new Date().toISOString().split("T")[0]} — re-run figma_taxonomy_docs to refresh", 14, false, { r: 0.5, g: 0.5, b: 0.5 });`);
+  lines.push(`  cursorY += 32;`);
+  lines.push(``);
+
+  // ── Naming Grammar Section ──
+  lines.push(`  await txt(0, cursorY, "Naming Grammar", 24, true);`);
+  lines.push(`  cursorY += 36;`);
+  lines.push(`  rect(0, cursorY, 800, 70, { r: 0.96, g: 0.96, b: 0.97 }, 8);`);
+  lines.push(`  await txt(16, cursorY + 12, "Semantic:   <category>/<concept>/[<variant>]/<property>/[<state>]", 14, false, { r: 0.1, g: 0.1, b: 0.1 });`);
+  lines.push(`  await txt(16, cursorY + 36, "Component:  component/<component>/[<part>]/[<variant>]/<category>/<property>/[<state>]", 14, false, { r: 0.1, g: 0.1, b: 0.1 });`);
+  lines.push(`  cursorY += 70 + SECTION_GAP;`);
+  lines.push(``);
+
+  // ── Coverage Summary ──
+  if (options.showCoverage) {
+    const full = coverage.filter((c) => c.status === "full").length;
+    const partial = coverage.filter((c) => c.status === "partial").length;
+    const missing = coverage.filter((c) => c.status === "missing").length;
+
+    lines.push(`  await txt(0, cursorY, "Coverage Summary", 24, true);`);
+    lines.push(`  cursorY += 36;`);
+
+    // Status badges
+    lines.push(`  rect(0, cursorY, 120, 40, { r: 0.13, g: 0.73, b: 0.33 }, 8);`);
+    lines.push(`  await txt(12, cursorY + 10, "Full: ${full}", 16, true, { r: 1, g: 1, b: 1 });`);
+
+    lines.push(`  rect(136, cursorY, 120, 40, { r: 0.95, g: 0.77, b: 0.06 }, 8);`);
+    lines.push(`  await txt(148, cursorY + 10, "Partial: ${partial}", 16, true, { r: 0.1, g: 0.1, b: 0.1 });`);
+
+    lines.push(`  rect(272, cursorY, 120, 40, { r: 0.85, g: 0.12, b: 0.12 }, 8);`);
+    lines.push(`  await txt(284, cursorY + 10, "Missing: ${missing}", 16, true, { r: 1, g: 1, b: 1 });`);
+
+    lines.push(`  cursorY += 40 + SECTION_GAP;`);
+    lines.push(``);
+  }
+
+  // ── Concept Overview Table ──
+  lines.push(`  await txt(0, cursorY, "Concept Taxonomy", 24, true);`);
+  lines.push(`  cursorY += 36;`);
+
+  // Table header
+  const cols = [
+    { label: "Concept",  x: 0,    w: 120 },
+    { label: "Purpose",  x: 130,  w: 300 },
+    { label: "Forms",    x: 440,  w: 200 },
+    { label: "States",   x: 650,  w: 200 },
+    { label: "Coverage", x: 860,  w: 100 },
+  ];
+
+  lines.push(`  rect(0, cursorY, 960, 36, { r: 0.94, g: 0.94, b: 0.96 }, 4);`);
+  for (const col of cols) {
+    lines.push(`  await txt(${col.x + 8}, cursorY + 9, ${escapeJs(col.label)}, 13, true);`);
+  }
+  lines.push(`  cursorY += 36;`);
+
+  // Table rows
+  for (const c of coverage) {
+    const forms = c.typicalForms.slice(0, 3).join(", ") + (c.typicalForms.length > 3 ? "..." : "");
+    const states = c.validStates.slice(0, 4).join(", ") + (c.validStates.length > 4 ? "..." : "");
+    const covLabel = `${statusLabel(c.status)} ${c.foundTokens.length}/${c.expectedTokens.length}`;
+
+    // Alternating row background
+    lines.push(`  rect(0, cursorY, 960, 36, { r: 0.99, g: 0.99, b: 1.0 }, 0);`);
+    lines.push(`  await txt(8, cursorY + 9, ${escapeJs(c.conceptName)}, 12, true);`);
+    lines.push(`  await txt(138, cursorY + 9, ${escapeJs(c.purpose.slice(0, 50) + (c.purpose.length > 50 ? "..." : ""))}, 11, false);`);
+    lines.push(`  await txt(448, cursorY + 9, ${escapeJs(forms)}, 11, false);`);
+    lines.push(`  await txt(658, cursorY + 9, ${escapeJs(states)}, 11, false);`);
+
+    // Coverage badge
+    lines.push(`  rect(868, cursorY + 6, 84, 24, ${statusColor(c.status)}, 12);`);
+    lines.push(`  await txt(878, cursorY + 10, ${escapeJs(covLabel)}, 10, true, { r: 1, g: 1, b: 1 });`);
+
+    lines.push(`  cursorY += 36;`);
+  }
+
+  lines.push(`  cursorY += SECTION_GAP;`);
+  lines.push(``);
+
+  // ── Per-Concept Token Anatomy ──
+  if (options.includeTokenAnatomy) {
+    for (const c of coverage) {
+      if (c.expectedTokens.length === 0) continue;
+
+      lines.push(`  // ── ${c.conceptName} anatomy ──`);
+      lines.push(`  await txt(0, cursorY, ${escapeJs(c.conceptName + " Tokens")}, 20, true);`);
+      lines.push(`  cursorY += 28;`);
+      lines.push(`  await txt(0, cursorY, ${escapeJs(c.purpose)}, 12, false, { r: 0.5, g: 0.5, b: 0.5 });`);
+      lines.push(`  cursorY += 24;`);
+
+      for (const token of c.expectedTokens) {
+        const found = c.foundTokens.includes(token);
+        const snap = snapshots[token];
+
+        // Token row with status indicator
+        const indicatorColor = found
+          ? "{ r: 0.13, g: 0.73, b: 0.33 }"
+          : "{ r: 0.85, g: 0.12, b: 0.12 }";
+
+        lines.push(`  rect(0, cursorY + 4, 8, 8, ${indicatorColor}, 4);`);
+        const fileToken = c.matchedFileTokens[token];
+        const displayLabel = fileToken ? `${token}  →  ${fileToken}` : token;
+        lines.push(`  await txt(16, cursorY, ${escapeJs(displayLabel)}, 11, false);`);
+
+        // If it's a color token and we have the value, show a swatch
+        if (snap?.type === "COLOR" && snap.values) {
+          const firstValue = Object.values(snap.values)[0];
+          if (firstValue && typeof firstValue === "object" && "r" in (firstValue as Record<string, unknown>)) {
+            const cv = firstValue as { r: number; g: number; b: number };
+            lines.push(`  rect(500, cursorY, 20, 16, { r: ${cv.r.toFixed(3)}, g: ${cv.g.toFixed(3)}, b: ${cv.b.toFixed(3)} }, 3);`);
+            const hex = `#${Math.round(cv.r * 255).toString(16).padStart(2, "0")}${Math.round(cv.g * 255).toString(16).padStart(2, "0")}${Math.round(cv.b * 255).toString(16).padStart(2, "0")}`.toUpperCase();
+            lines.push(`  await txt(528, cursorY, ${escapeJs(hex)}, 11, false, { r: 0.4, g: 0.4, b: 0.4 });`);
+          }
+        } else if (snap?.values) {
+          const firstValue = Object.values(snap.values)[0];
+          if (firstValue !== undefined && firstValue !== null) {
+            lines.push(`  await txt(500, cursorY, ${escapeJs(String(firstValue))}, 11, false, { r: 0.4, g: 0.4, b: 0.4 });`);
+          }
+        }
+
+        lines.push(`  cursorY += 20;`);
+      }
+
+      lines.push(`  cursorY += 32;`);
+    }
+  }
+
+  // ── Timestamp footer ──
+  lines.push(`  await txt(0, cursorY, "Last synced: ${new Date().toISOString()}", 11, false, { r: 0.6, g: 0.6, b: 0.6 });`);
+  lines.push(``);
+
+  lines.push(`  return { pageId: page.id };`);
+  lines.push(`})();`);
+
+  const result = await bridge.execute(lines.join("\n"));
+
+  let pageId = "unknown";
+  if (result.success && result.result) {
+    try {
+      const parsed = typeof result.result === "string" ? JSON.parse(result.result) : result.result;
+      pageId = parsed.pageId ?? "unknown";
+    } catch {
+      // result may be the page ID string directly
+      pageId = String(result.result);
+    }
+  }
+
+  return {
+    pageId,
+    autoSyncEnabled: options.autoSync,
+  };
+}
+
+/**
+ * Build a lightweight re-render script that updates only dynamic content
+ * (coverage badges, swatches, timestamp) without recreating the full page.
+ * Used by the auto-sync handler.
+ */
+export function buildAutoSyncScript(
+  pageName: string,
+  coverage: ConceptCoverage[],
+): string {
+  // For auto-sync, we regenerate the full page since Figma plugin API
+  // doesn't support efficient partial updates of text/fill properties
+  // across many unrelated nodes. The full re-render is fast enough
+  // (< 500ms for ~25 concepts) given the 2-second debounce.
+  //
+  // This function is called by the variable-change event handler
+  // in figma-bridge.ts — it re-computes coverage and rebuilds the page.
+  return `
+    (async () => {
+      const page = figma.root.children.find(p => p.name === ${escapeJs(pageName)});
+      if (!page) return { skipped: true, reason: "page not found" };
+      return { needsFullRerender: true, pageId: page.id };
+    })();
+  `;
+}