@hegemonart/get-design-done 1.30.6 → 1.31.0

package/.claude-plugin/marketplace.json

@@ -5,14 +5,14 @@
   },
   "metadata": {
     "description": "Get Design Done — 5-stage agent-orchestrated design pipeline with 9 connections, handoff-first workflow, bidirectional Figma write-back, 22+ specialized agents, queryable knowledge layer (intel store, dependency analysis, learnings extraction), and a self-improvement loop (reflector, frontmatter + budget feedback, global-skills layer). v1.20.0 ships the SDK foundation: gdd-state MCP server (11 typed tools), lockfile-safe STATE.md mutations, event stream, and resilience primitives (jittered-backoff, rate-guard, error-classifier, iteration-budget) for rate-limit + 429 + context-overflow recovery. Full CI/CD pipeline (Node 22/24 × Linux/macOS/Windows) and release automation (auto-tag + GitHub Release + release-time smoke test).",
-    "version": "1.30.6"
+    "version": "1.31.0"
   },
   "plugins": [
     {
       "name": "get-design-done",
       "source": "./",
       "description": "Agent-orchestrated 5-stage design pipeline: Brief → Explore → Plan → Design → Verify. 22+ specialized agents, 9 connections (Figma, Refero, Preview, Storybook, Chromatic, Figma Writer, Graphify, Pinterest, Claude Design), Claude Design handoff, bidirectional Figma write-back, and a queryable intel store (.design/intel/) for dependency and learnings queries. Standalone commands: style, darkmode, compare, figma-write, graphify, handoff, analyze-dependencies, skill-manifest, extract-learnings. Embeds NNG heuristics, WCAG thresholds, typographic systems, motion framework, and anti-pattern catalog. Ships with a full CI/CD pipeline (Node 22/24 × Linux/macOS/Windows) and release automation. Optimization layer (v1.0.4.1, retroactive): gdd-router + gdd-cache-manager skills, PreToolUse budget-enforcer hook, tier-aware agent frontmatter, lazy checker gates, streaming synthesizer, /gdd:warm-cache + /gdd:optimize commands, and cost telemetry at .design/telemetry/costs.jsonl — targeting 50-70% per-task token-cost reduction with no quality-floor regression. v1.20.0 SDK foundation: gdd-state MCP server (11 typed tools), lockfile-safe STATE.md mutations, event stream at .design/telemetry/events.jsonl, resilience primitives (jittered-backoff, rate-guard, error-classifier, iteration-budget) with rate-limit + 429 + context-overflow recovery, and TypeScript toolchain.",
-      "version": "1.30.6",
+      "version": "1.31.0",
       "author": {
         "name": "hegemonart"
       },
@@ -68,7 +68,10 @@
         "gemini",
         "mcp",
         "parallel-agents",
-        "agent-sdk"
+        "agent-sdk",
+        "figma",
+        "extractor",
+        "design-system-sync"
       ]
     }
   ]

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "get-design-done",
   "short_name": "gdd",
-  "version": "1.30.6",
+  "version": "1.31.0",
   "description": "Agent-orchestrated 5-stage design pipeline: Brief → Explore → Plan → Design → Verify. 22+ specialized agents, 9 connections (Figma, Refero, Preview, Storybook, Chromatic, Figma Writer, Graphify, Pinterest, Claude Design), handoff-first workflow via Claude Design bundles, bidirectional Figma write-back (annotations, Code Connect), queryable intel store (`.design/intel/`) for O(1) design surface lookups, and self-improvement loop (reflector agent, frontmatter + budget feedback, global-skills layer at `~/.claude/gdd/global-skills/`). Standalone commands: style, darkmode, compare, figma-write, graphify, handoff, analyze-dependencies, skill-manifest, extract-learnings, reflect, apply-reflections. Embeds NNG heuristics, WCAG thresholds, typographic systems, motion framework, and anti-pattern catalog. Ships with a full CI/CD pipeline (Node 22/24 × Linux/macOS/Windows, lint + schema + frontmatter + stale-ref + shellcheck + gitleaks + injection-scan + blocking size-budget) and release automation (auto-tag + GitHub Release + release-time smoke test). Optimization layer (v1.0.4.1, retroactive): gdd-router + gdd-cache-manager skills, PreToolUse budget-enforcer hook, tier-aware agent frontmatter, lazy checker gates, streaming synthesizer, /gdd:warm-cache + /gdd:optimize commands, and cost telemetry at .design/telemetry/costs.jsonl — targeting 50-70% per-task token-cost reduction with no quality-floor regression. v1.20.0 SDK foundation: gdd-state MCP server (11 typed tools), lockfile-safe STATE.md mutations, event stream at .design/telemetry/events.jsonl, resilience primitives (jittered-backoff, rate-guard, error-classifier, iteration-budget) with rate-limit + 429 + context-overflow recovery, and TypeScript toolchain. v1.27.7 ships gdd-mcp (Phase 27.7): 12 read-only MCP tools for sub-3s priming. v1.28.0 (Phase 28): Foundational References Tier 2 — 5 new reference files (color-theory, composition, proportion-systems, i18n, contrast-advanced), 2 verifier i18n probes + 1 explore i18n-readiness probe, 12 additive cross-link insertions across 10 existing references, 2 orthogonal audit-scoring lens-tags (composition_alignment + i18n_readiness).",
   "author": {
     "name": "hegemonart",
@@ -62,7 +62,10 @@
     "agent-sdk",
     "mcp-server",
     "context-loading",
-    "cross-session"
+    "cross-session",
+    "figma",
+    "extractor",
+    "design-system-sync"
   ],
   "skills": [
     "./skills/"

package/CHANGELOG.md

@@ -4,6 +4,67 @@ All notable changes to get-design-done are documented here. Versions follow [sem
 
 ---
 
+## [1.31.0] - 2026-05-29
+
+### Phase 31 — Figma Off-Context Extractor + Variables Sync Plugin
+
+Ships `gdd-figma-extract` — pull a whole Figma design system into a compact, queryable local digest (`DESIGN.md` + `tokens.json` + `components.json`) **without the raw JSON ever entering Claude's context**. One command extracts the file via the Figma REST API to a local raw cache; a separate digest stage reduces it to an LLM-readable spec. Plus a thin **"GDD Sync"** Figma plugin that fills the Variables-API-Enterprise gap by reading `figma.variables` from inside Figma (works on any plan — including Free) and POSTing them to an ephemeral localhost receiver. 10 plans across 4 waves: Wave A (raw puller + digest + styles resolver + SKILL), Wave B (plugin scaffold + export + receiver), Wave C (`--component` slice + `figma_extract` health check), Wave D (closeout).
+
+### Motivation — the spike trail
+
+Spike 001 (commit `c3a9cf6`, `.planning/spikes/001-figma-offcontext-extractor/`) validated the economics: **898× compression** (223 MB raw → 254 KB digest), a 15.7K-token DESIGN.md (under the 20K target), 127 component sets + 40 singletons captured with variants/props/defaults, ~33s wall time, and crucially **0 Claude tokens + 0 Figma MCP calls during extraction**. This is the economic alternative to Figma MCP for whole-design-system workflows (Figma MCP remains correct for spot questions on individual components). The spike surfaced two gaps, both closed by this phase:
+
+1. **Variables API → 403 (Enterprise-only)** — closed by **Path C** (the GDD Sync plugin reads variables locally and POSTs to the receiver).
+2. **Legacy styles → 0 tokens** — closed by **Path B** (two-step `/styles` + `/nodes?ids=` lookup; published-style source nodes live in canvas frames, not the main document tree).
+
+### Added
+
+- **`gdd-figma-extract` off-context extractor** — the two-stage pipeline (D-01: extract → digest stay separated, re-digest without re-pulling):
+  - `scripts/lib/figma-extract/pull.cjs` — productionized Figma REST puller (retry/backoff, version-based cache invalidation with 1h TTL fallback per D-11, drops `geometry=paths` per D-03). Writes raw JSON to disk only; raw bodies never returned to a logging caller.
+  - `scripts/lib/figma-extract/digest.cjs` — reads the raw cache, walks the node tree with **variant rollup** (D-02 — naive walk inflates ~16×), assembles tokens via the 3-path chain, renders `DESIGN.md` + `tokens.json` + `components.json`.
+  - `scripts/lib/figma-extract/styles-resolver.cjs` — **Path B** two-step `/styles` + `/nodes?ids=` resolver (fixes the spike's 0-tokens bug).
+  - `scripts/lib/figma-extract/render-md.cjs` + `walk.cjs` — deterministic, byte-stable DESIGN.md renderer + the variant-rollup walker.
+- **Three-path token extraction (D-04)** with a fallback chain — Path A (Variables API, Enterprise; 403 skipped silently), Path B (`/styles` + `/nodes`), Path C (plugin sync). Resolution priority on collision: Variables > plugin sync > styles, with a `--prefer-styles` escape hatch.
+- **"GDD Sync" Figma plugin** (`figma-plugin/`, D-05) — TypeScript, single "Export to GDD" button. Reads ALL local variables (D-13 — digest filters later), resolves aliases + modes, and POSTs to the localhost receiver.
+- **Localhost receiver** (`scripts/lib/figma-extract/receiver.cjs`, D-06) — ephemeral, **127.0.0.1-only**, port hardcoded to 5179, schema-validated, refuses non-loopback remotes, exits on first valid receipt or timeout.
+- **`--component <name|glob>` digest slice** (D-08) — a ~500-token per-component slice instead of the full ~16K digest; strictly additive (omitting it reproduces the full digest unchanged).
+- **`figma_extract` health check** (Plan 31-09) — `/gdd:health` now reports one of three exact states: `figma extract: ready (token set)`, `figma extract: token missing`, or `figma extract: plugin sync needed for variables (Free tier detected)`. Presence-only token check (D-10); the Free-tier signal is read from the local raw-pull cache only (no network call).
+- **`skills/figma-extract/SKILL.md`** (`name: gdd-figma-extract`) — off-context orchestration that never instructs reading `raw/*.json` (D-12).
+- **`tests/phase-31-baseline.test.cjs`** + 6 baseline files at `test-fixture/baselines/phase-31/` (design-md, components-json, tokens-json, health-line, manifest-network-scope, token-isolation-static), **`tests/phase-31-end-to-end.test.cjs`** (offline pull+digest against fixtures), and **`tests/figma-extract-token-isolation.test.cjs`** (the D-10 static scanner + meta-tests).
+
+### Security & guarantees
+
+- **Off-context guarantee (D-12) — statically enforced.** The SKILL never instructs reading `raw/*.json`; the digest is a pure function of the raw cache. The raw pull consumes 0 Claude tokens.
+- **Token isolation (D-10) — statically enforced.** `FIGMA_TOKEN` (fallback `FIGMA_PERSONAL_ACCESS_TOKEN`) is read from the environment only and is sent ONLY as the `X-Figma-Token` request header — never logged, never written to disk. `tests/figma-extract-token-isolation.test.cjs` scans every file under `scripts/lib/figma-extract/` for any `writeFile`/`appendFile`/`console.*`/`logger.*`/`process.std*.write` call referencing the token and fails on a non-zero count (meta-tested to prove the scanner is not vacuous).
+- **Receiver network scope (D-06).** The plugin manifest's `allowedDomains` is exactly the localhost pair (`http://localhost:5179`, `http://127.0.0.1:5179`) — any widening trips the baseline test. No external host, no wildcard.
+
+### Deferred
+
+- **Live Figma validation (D-07).** The phase ships with hermetic offline tests (stubbed fetch against committed fixtures); a one-time end-to-end run against a real Figma file with a live token is a maintainer follow-up, not a v1.31.0 blocker. Plugin Community-directory submission is likewise deferred (dev-install path ships now).
+
+### Decisions (D-01 through D-13)
+
+- **D-01**: Two-stage pipeline (extract → digest) stays separated. Re-run digest without re-pulling.
+- **D-02**: Variant rollup default-on — skip COMPONENT children of a COMPONENT_SET; record variants as a field on the parent (naive walk inflates ~16×).
+- **D-03**: Drop the `geometry=paths` query param (~30% smaller raw; geometry is discarded in the digest).
+- **D-04**: Three-path token extraction with a fallback chain (Variables > plugin sync > styles; `--prefer-styles` escape).
+- **D-05**: "GDD Sync" plugin as a separate `figma-plugin/` package (TypeScript, single button).
+- **D-06**: Receiver is ephemeral + 127.0.0.1-only + hardcoded port 5179; refuses non-loopback; closes on receipt or timeout.
+- **D-07**: Plugin distribution is dev-build now, Community submission as a follow-up; live-Figma validation is a maintainer follow-up — neither blocks v1.31.0.
+- **D-08**: `--component <name|glob>` filter on digest for per-component slicing (~500 tokens vs ~16K).
+- **D-09**: Raw cache gitignored (`.figma-extract-cache/`), reproducible from `pull.cjs`; `digest/` artifacts may be committed.
+- **D-10**: Token never logged or persisted — `FIGMA_TOKEN` from env only; CI static-analysis test enforces it library-wide.
+- **D-11**: Cache invalidation is content-based via Figma's `version` field, with a 1h wall-clock TTL fallback.
+- **D-12**: Off-context guarantee enforced statically — the skill never instructs reading `raw/*.json`.
+- **D-13**: Plugin emits ALL local variables (not just published-collection ones); filtering happens at the digest stage.
+
+### Backward compatibility
+
+- 4-manifest + 2 Tier-2 manifest lockstep at v1.31.0 (`package.json` + `.claude-plugin/plugin.json` + `.claude-plugin/marketplace.json` (metadata.version + plugins[0].version) + `.cursor-plugin/plugin.json` + `.codex-plugin/plugin.json`). Keywords `figma`, `extractor`, `design-system-sync` added across the manifest keyword arrays.
+- `NOTICE` preserved verbatim — Phase 31 productionizes our own spike (`c3a9cf6`) and uses Figma's official REST + plugin APIs plus `@figma/plugin-typings` (a normal npm devDependency, not a vendored code transplant). No third-party CODE was vendored, so no new attribution is owed.
+
+---
+
 ## [1.30.6] - 2026-05-28
 
 ### Phase 30.6 — Graphify Self-Ownership

package/README.md

@@ -256,6 +256,27 @@ When K=3 stable clusters surface across M=10 reflection cycles (defaults in `ref
 **Discipline preserved.** Reflector authors nothing that auto-ships. `/gdd:apply-reflections` remains the single human gate (Phase 11 SC-8). Stage 1 never auto-flips — user opts in.
 
 
+### Figma off-context extraction (v1.31.0+)
+
+Pull an entire Figma design system into a compact, LLM-readable local digest — **without the raw JSON ever entering Claude's context**. One command extracts the file via the Figma REST API into a local raw cache; a separate digest stage reduces it to `DESIGN.md` + `tokens.json` + `components.json`.
+
+```bash
+# Stage 1 — raw pull (0 Claude tokens; writes a gitignored cache)
+node scripts/lib/figma-extract/pull.cjs <figma-file-url-or-key>
+# Stage 2 — digest (reads the cache, writes the compact spec)
+node scripts/lib/figma-extract/digest.cjs --raw <cache>/raw/<key> --out .design/figma
+```
+
+**The economics.** A spike measured **898× compression** (223 MB raw → 254 KB digest) with a ~15.7K-token `DESIGN.md`, capturing 127 component sets + 40 singletons (variants, props, defaults) in ~33s — at **0 Claude tokens and 0 Figma MCP calls during extraction**. This is the cost-sane alternative to the Figma MCP for whole-design-system work, which can run tens of minutes and 50–500K+ tokens for the same data. (The Figma MCP remains the right tool for spot questions on a single component.)
+
+- **Token-safe by construction.** `FIGMA_TOKEN` is read from the environment only and sent solely as a request header — never logged, never written to disk (a CI static-analysis test enforces this across the whole extract library). The digest never reads raw JSON into context.
+- **Works on any Figma plan.** The optional **"GDD Sync"** Figma plugin (`figma-plugin/`) fills the Variables-API-Enterprise gap: it reads `figma.variables` from inside Figma and POSTs them to an ephemeral, 127.0.0.1-only receiver — so Free-tier users get full token coverage too.
+- **Per-component slices.** `digest --component <name|glob>` renders a ~500-token slice of just the components you ask for, instead of the full digest.
+- **Health-aware.** `/gdd:health` reports a `figma_extract` readiness line (token set / token missing / Free-tier plugin-sync needed).
+
+See [`skills/figma-extract/SKILL.md`](skills/figma-extract/SKILL.md) and [`figma-plugin/README.md`](figma-plugin/README.md) for the full flow.
+
+
 ## How It Works
 
 > **New to an existing codebase?** Run `/gdd:map` first. It dispatches 5 specialist mappers in parallel (tokens, components, visual hierarchy, a11y, motion) and writes structured JSON to `.design/map/` — much higher signal than the grep-based fallback in Explore.

package/SKILL.md

@@ -35,6 +35,7 @@ Each stage produces artifacts in `.design/` inside the current project.
 | `darkmode` | `get-design-done:gdd-darkmode` | Audit dark mode architecture + contrast + anti-patterns → .design/DARKMODE-AUDIT.md |
 | `compare` | `get-design-done:gdd-compare` | Delta between DESIGN.md baseline and DESIGN-VERIFICATION.md → .design/COMPARE-REPORT.md |
 | `figma-write <mode>` | `get-design-done:gdd-figma-write` | Write design decisions to Figma (annotate/tokenize/mappings) |
+| `figma-extract <file-url-or-key>` | `get-design-done:gdd-figma-extract` | Off-context Figma design-system extraction → compact local digest (DESIGN.md + tokens.json + components.json), zero raw JSON in context |
 | `graphify <subcommand>` | `get-design-done:gdd-graphify` | Manage Graphify knowledge graph (build/query/status/diff) |
 | `discuss [topic] [--all] [--spec] [--cycle <name>]` | `get-design-done:gdd-discuss` | Adaptive design interview — spawns design-discussant; appends D-XX decisions to STATE.md |
 | `list-assumptions [--area]` | `get-design-done:gdd-list-assumptions` | Surface implicit design assumptions baked into the codebase |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hegemonart/get-design-done",
-  "version": "1.30.6",
+  "version": "1.31.0",
   "description": "A design-quality pipeline for AI coding agents: brief, plan, implement, and verify UI work against your design system.",
   "author": "Hegemon",
   "homepage": "https://github.com/hegemonart/get-design-done",
@@ -80,7 +80,10 @@
     "gemini",
     "mcp",
     "parallel-agents",
-    "agent-sdk"
+    "agent-sdk",
+    "figma",
+    "extractor",
+    "design-system-sync"
   ],
   "skills": [
     "SKILL.md"

package/scripts/lib/figma-extract/digest.cjs

@@ -0,0 +1,430 @@
+'use strict';
+/**
+ * Plan 31-02 — productionized from spike 001 digest.mjs (orchestration + token extraction).
+ *
+ * DIGEST stage of the two-stage pipeline (decision D-01: extract → digest stay
+ * separated). This module reads ONLY the raw/ cache that pull.cjs (31-01) wrote;
+ * it performs ZERO network calls, so it can re-run against an existing cache
+ * without re-pulling (idempotent / off-line).
+ *
+ * Three-path token assembly (decision D-04):
+ *   Path A — Variables API body (rawDir/variables.json without the plugin marker)
+ *   Path B — styles resolver (rawDir/styles.json) — pluggable seam; 31-03 ships
+ *            the real two-step /styles + /nodes?ids= resolver
+ *   Path C — plugin sync (rawDir/variables.json WITH the receiver marker, written
+ *            by 31-06's localhost receiver)
+ *   Resolution priority on name collision: Variables > plugin sync > styles.
+ *   The --prefer-styles escape inverts the chain to prefer styles.
+ *
+ * Pure CommonJS, no external deps, no network.
+ *
+ * Per-component slicing (decision D-08):
+ *   digest({..., component})    — when `component` is a name or glob (e.g.
+ *            'Sample/Button', 'Sample/*', 'Form/Butt?'), the digest renders ONLY
+ *            the matching component(s) — a ~500-token slice instead of the full
+ *            ~16K digest. The filter is strictly ADDITIVE: omitting `component`
+ *            reproduces 31-02's full-digest behavior unchanged. Glob support is a
+ *            few lines of in-file string work (no external glob dependency).
+ *
+ * Exports:
+ *   digest(opts)                — async orchestrator (reads raw/, writes digest/)
+ *   assembleTokens(opts)        — pure three-path merge by priority
+ *   DEFAULT_TOKEN_PRIORITY      — ['variables','plugin','styles'] (D-04)
+ *   globToRegExp(pattern)       — minimal glob→RegExp (D-08 component filter)
+ */
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const { collectComponents } = require('./walk.cjs');
+const { renderDesignMd } = require('./render-md.cjs');
+
+// D-04: Variables > plugin sync > styles.
+const DEFAULT_TOKEN_PRIORITY = ['variables', 'plugin', 'styles'];
+
+// Receiver-written payload marker (31-06 contract). A rawDir/variables.json that
+// carries this top-level field is the plugin's Path-C payload, NOT the Figma
+// Variables API body.
+const PLUGIN_PAYLOAD_MARKER = 'gdd-plugin';
+
+// ── component filter (D-08) ────────────────────────────────────────────────────
+
+/**
+ * Translate a minimal glob pattern into an anchored, case-sensitive RegExp.
+ *
+ * Supported wildcards (the only two the acceptance criterion needs):
+ *   `*` → `.*`  (zero or more of any char)
+ *   `?` → `.`   (exactly one char)
+ * Every other character — including regex metacharacters like `.`/`/`/`(`/`+`
+ * and the Figma `Sample/Path/Name` separators — is treated LITERALLY. We escape
+ * the whole pattern first, then re-activate the escaped `\*`/`\?` placeholders,
+ * so e.g. the `.` in 'Sample.Icon' is literal and does NOT over-match 'Sample/Icon'.
+ *
+ * Matching is exact (anchored `^...$`) and case-sensitive — Figma component
+ * names are case-significant, and an exact name with no wildcard must match only
+ * that one component.
+ *
+ * @param {string} pattern  a component name or glob (e.g. 'Button*', 'Form/*')
+ * @returns {RegExp}
+ */
+function globToRegExp(pattern) {
+  // Escape ALL regex metacharacters (incl. * and ? for now).
+  const escaped = String(pattern).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  // Re-activate the wildcards: escaped '\*' → '.*', escaped '\?' → '.'.
+  const body = escaped.replace(/\\\*/g, '.*').replace(/\\\?/g, '.');
+  return new RegExp(`^${body}$`);
+}
+
+/**
+ * Collect the set of token names that are RELEVANT to a set of components, so a
+ * slice can carry just those tokens instead of the full ~hundreds-of-tokens
+ * catalog (which would blow past the ~500-token budget). Relevance = a token
+ * whose name is referenced by a component's prop default/options, variant name,
+ * or the component name itself. When nothing is determinable we return an empty
+ * set and the slice renders component shape only — keeping the slice bounded
+ * regardless of catalog size (D-08 size guarantee).
+ *
+ * @param {Array} matched      matched component entries (from collectComponents)
+ * @param {Array} tokens       the full assembled token list
+ * @returns {Array} the subset of `tokens` referenced by the matched components
+ */
+function tokensForComponents(matched, tokens) {
+  if (!Array.isArray(tokens) || tokens.length === 0) return [];
+  // Build a haystack of strings drawn from the matched components.
+  const haystack = [];
+  for (const c of matched) {
+    if (c.name) haystack.push(c.name);
+    for (const v of c.variants || []) haystack.push(v);
+    for (const p of c.props || []) {
+      if (p.name) haystack.push(p.name);
+      if (p.default !== undefined) haystack.push(String(p.default));
+      for (const o of p.options || []) haystack.push(String(o));
+    }
+  }
+  const blob = haystack.join('\n');
+  return tokens.filter((t) => t && t.name !== undefined && blob.includes(t.name));
+}
+
+// ── helpers (Path A) ─────────────────────────────────────────────────────────
+
+/** Convert a Figma {r,g,b,a?} (0..1 floats) colour to a hex string. */
+function rgbToHex({ r, g, b, a }) {
+  const to = (v) => Math.round(v * 255).toString(16).padStart(2, '0');
+  const hex = `#${to(r)}${to(g)}${to(b)}`;
+  return a !== undefined && a < 1 ? `${hex}${to(a)}` : hex;
+}
+
+/**
+ * Path A — extract tokens from a Figma Variables API body
+ * (`/v1/files/:key/variables/local`). Mirrors the spike's extractTokensFromVariables.
+ * @param {object|null} vars  the Variables API response (has .meta.{variables,variableCollections})
+ * @returns {Array<{name,type,collection?,modes?}>}
+ */
+function extractTokensFromVariables(vars) {
+  if (!vars || !vars.meta) return [];
+  const collections = vars.meta.variableCollections || {};
+  const variables = vars.meta.variables || {};
+  const tokens = [];
+  for (const v of Object.values(variables)) {
+    const collection = collections[v.variableCollectionId];
+    const modes = collection?.modes || [];
+    const valuesByMode = {};
+    for (const mode of modes) {
+      const raw = v.valuesByMode?.[mode.modeId];
+      if (raw && typeof raw === 'object' && 'r' in raw) {
+        valuesByMode[mode.name] = rgbToHex(raw);
+      } else if (raw && raw.type === 'VARIABLE_ALIAS') {
+        valuesByMode[mode.name] = `{${variables[raw.id]?.name || raw.id}}`;
+      } else {
+        valuesByMode[mode.name] = raw;
+      }
+    }
+    tokens.push({
+      name: v.name,
+      type: v.resolvedType,
+      collection: collection?.name,
+      modes: valuesByMode,
+    });
+  }
+  return tokens;
+}
+
+/**
+ * Path C — normalize a receiver-written plugin payload into the common token
+ * shape. The plugin (D-13) emits ALL local variables; we accept either a
+ * pre-shaped `tokens[]` array or the raw `variables`/`meta` form and pass it
+ * through extractTokensFromVariables when needed.
+ * @param {object|null} payload  variables.json carrying source:'gdd-plugin'
+ * @returns {Array}
+ */
+function normalizePluginPayload(payload) {
+  if (!payload) return [];
+  // Preferred shape: the plugin already emits a flat tokens[] array.
+  if (Array.isArray(payload.tokens)) return payload.tokens;
+  // Fallback: it carries a Variables-API-like body — reuse Path A extraction.
+  if (payload.meta) return extractTokensFromVariables(payload);
+  return [];
+}
+
+// ── three-path merge (D-04) ──────────────────────────────────────────────────
+
+/**
+ * Merge the three token sources by priority. On a NAME collision the
+ * higher-priority source wins.
+ *
+ * Implementation note: we iterate the priority chain HIGHEST-first and only set
+ * a name the first time we see it (skip-if-present), so the highest-priority
+ * source's entry is the one that survives.
+ *
+ * @param {object} opts
+ * @param {Array} [opts.variables]        Path A tokens
+ * @param {Array} [opts.pluginVariables]  Path C tokens
+ * @param {Array} [opts.styleTokens]      Path B tokens
+ * @param {boolean} [opts.preferStyles]   D-04 escape — move styles to the front
+ * @returns {Array} merged tokens (insertion order follows the priority chain)
+ */
+function assembleTokens({ variables, pluginVariables, styleTokens, preferStyles } = {}) {
+  const bySource = {
+    variables: Array.isArray(variables) ? variables : [],
+    plugin: Array.isArray(pluginVariables) ? pluginVariables : [],
+    styles: Array.isArray(styleTokens) ? styleTokens : [],
+  };
+  const priority = preferStyles
+    ? ['styles', 'variables', 'plugin']
+    : DEFAULT_TOKEN_PRIORITY;
+
+  const merged = new Map();
+  for (const source of priority) {
+    for (const tok of bySource[source]) {
+      if (!tok || tok.name === undefined) continue;
+      if (!merged.has(tok.name)) merged.set(tok.name, tok);
+    }
+  }
+  return [...merged.values()];
+}
+
+// ── orchestrator ─────────────────────────────────────────────────────────────
+
+/** Read+parse a JSON file from the raw cache; return null if absent/unreadable. */
+async function readJson(rawDir, name) {
+  try {
+    const body = await fs.readFile(path.join(rawDir, `${name}.json`), 'utf8');
+    return JSON.parse(body);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Run the digest: read raw/ cache → walk (variant rollup) → 3-path token
+ * assembly → render DESIGN.md + write tokens.json + components.json.
+ *
+ * @param {object} opts
+ * @param {string} opts.rawDir              raw/ cache dir produced by pull.cjs (31-01) — REQUIRED
+ * @param {string} opts.outDir              dir to write DESIGN.md/tokens.json/components.json — REQUIRED for writes
+ * @param {Function} [opts.stylesResolver]  fn(file, styles) → styleTokens[] (Path B; 31-03 provides real impl)
+ * @param {boolean} [opts.preferStyles]     D-04 escape hatch
+ * @param {string} [opts.fetchedAtOverride] deterministic provenance header for tests
+ * @param {string} [opts.component]         D-08 — name or glob; when set, render a
+ *                                          per-component SLICE (~500 tokens) of only
+ *                                          the matching component(s). Additive: when
+ *                                          absent, the full-digest path is unchanged.
+ * @returns {Promise<object>}
+ *   full:   { ok:true, counts, bytes, outDir }
+ *   sliced: { ok:true, sliced:true, matched:[names], counts:{components,tokens}, bytes, outDir, note? }
+ *   error:  { ok:false, error }
+ */
+async function digest({ rawDir, outDir, stylesResolver, preferStyles, fetchedAtOverride, component } = {}) {
+  if (!rawDir) {
+    return { ok: false, error: 'rawDir is required — run pull.cjs first' };
+  }
+
+  // (1) Required input — graceful guard (mirrors spike). NEVER throws.
+  const file = await readJson(rawDir, 'file');
+  if (!file) {
+    return { ok: false, error: 'raw/file.json not found — run pull.cjs first' };
+  }
+
+  // (2) Optional inputs.
+  const variablesRaw = await readJson(rawDir, 'variables');
+  const styles = await readJson(rawDir, 'styles');
+  const meta = await readJson(rawDir, '_meta');
+
+  // Distinguish Path A (Variables API body) from Path C (receiver plugin payload)
+  // by the receiver marker. Only one of the two is populated from variables.json.
+  let apiVariables = null;
+  let pluginPayload = null;
+  if (variablesRaw && variablesRaw.source === PLUGIN_PAYLOAD_MARKER) {
+    pluginPayload = variablesRaw; // Path C
+  } else {
+    apiVariables = variablesRaw; // Path A (may be null)
+  }
+
+  // (3) Components + widgets — variant rollup is default-on (D-02).
+  const { components, widgets } = collectComponents(file.document);
+
+  // (4) Three token paths.
+  const pathATokens = extractTokensFromVariables(apiVariables);
+  const styleTokens = stylesResolver ? await stylesResolver(file, styles) : [];
+  const pluginVariables = normalizePluginPayload(pluginPayload);
+
+  // (5) Merge by priority (D-04).
+  const tokens = assembleTokens({
+    variables: pathATokens,
+    pluginVariables,
+    styleTokens,
+    preferStyles,
+  });
+
+  // (6) Provenance — fetched_at is injectable for deterministic output.
+  const fileMeta = {
+    file_key: meta?.file_key,
+    fetched_at: fetchedAtOverride !== undefined ? fetchedAtOverride : meta?.fetched_at,
+    name: file.name,
+  };
+
+  // (6b) D-08 — per-component SLICE. When `component` is provided we short-circuit
+  // the full digest and render only the matching component(s) + their relevant
+  // tokens. This is additive: the block below is skipped entirely when `component`
+  // is undefined, so the full-digest path (step 7) stays byte-identical.
+  if (component !== undefined && component !== null && component !== '') {
+    const rx = globToRegExp(component);
+    const matched = components.filter((c) => rx.test(c.name));
+    // Only tokens referenced by the matched components — keeps the slice ~500
+    // tokens instead of dumping the whole catalog.
+    const sliceTokens = tokensForComponents(matched, tokens);
+    const sliceMd = renderDesignMd({
+      tokens: sliceTokens,
+      components: matched,
+      widgets: [], // a per-component slice omits page/widget noise
+      fileMeta,
+    });
+    if (outDir) {
+      await fs.mkdir(outDir, { recursive: true });
+      // Write the slice to DESIGN.md (the SKILL/e2e read whatever digest writes).
+      await fs.writeFile(path.join(outDir, 'DESIGN.md'), sliceMd);
+    }
+    const result = {
+      ok: true,
+      sliced: true,
+      matched: matched.map((c) => c.name),
+      counts: { components: matched.length, tokens: sliceTokens.length },
+      bytes: { designMd: Buffer.byteLength(sliceMd, 'utf8') },
+      outDir,
+    };
+    if (matched.length === 0) result.note = `no component matched ${component}`;
+    return result;
+  }
+
+  // (7) Render + write artifacts (D-09: digest/ is commit-able).
+  const designMd = renderDesignMd({ tokens, components, widgets, fileMeta });
+  const tokensJson = JSON.stringify(tokens, null, 2);
+  const componentsJson = JSON.stringify(components, null, 2);
+
+  if (outDir) {
+    await fs.mkdir(outDir, { recursive: true });
+    await fs.writeFile(path.join(outDir, 'DESIGN.md'), designMd);
+    await fs.writeFile(path.join(outDir, 'tokens.json'), tokensJson);
+    await fs.writeFile(path.join(outDir, 'components.json'), componentsJson);
+  }
+
+  return {
+    ok: true,
+    counts: {
+      tokens: tokens.length,
+      components: components.length,
+      widgets: widgets.length,
+    },
+    bytes: {
+      designMd: Buffer.byteLength(designMd, 'utf8'),
+      tokensJson: Buffer.byteLength(tokensJson, 'utf8'),
+      componentsJson: Buffer.byteLength(componentsJson, 'utf8'),
+    },
+    outDir,
+  };
+}
+
+module.exports = {
+  digest,
+  assembleTokens,
+  DEFAULT_TOKEN_PRIORITY,
+  // exported for unit reuse / downstream (31-08 --component, 31-03 normalization parity)
+  extractTokensFromVariables,
+  normalizePluginPayload,
+  PLUGIN_PAYLOAD_MARKER,
+  // D-08 component filter — exported for unit reuse / downstream slicing tools.
+  globToRegExp,
+  tokensForComponents,
+};
+
+// ── CLI entry (31-08) ──────────────────────────────────────────────────────────
+//
+// Thin argv wrapper invoked by the figma-extract SKILL (31-07) and the e2e test
+// (31-10). The callable API (digest/assembleTokens/…) above is the import surface;
+// this block runs ONLY when the file is executed directly. Flag → option map
+// (contract from 31-02 SUMMARY, extended with --component for D-08):
+//
+//   --raw <dir>          rawDir   (required)  raw cache dir written by pull.cjs
+//   --out <dir>          outDir   (required)  digest artifact output dir
+//   --prefer-styles      preferStyles:true    D-04 escape — styles-first priority
+//   --component <name>   component            D-08 per-component slice (name or glob)
+//
+// D-10: this block NEVER reads, logs, or persists FIGMA_TOKEN — digest is offline
+// and token-free by construction; the CLI only echoes counts/paths.
+
+/** Minimal flag parser for the four supported options (no external dep). */
+function parseArgv(argv) {
+  const opts = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--raw') opts.rawDir = argv[++i];
+    else if (a === '--out') opts.outDir = argv[++i];
+    else if (a === '--prefer-styles') opts.preferStyles = true;
+    else if (a === '--component') opts.component = argv[++i];
+    else if (a === '--help' || a === '-h') opts.help = true;
+  }
+  return opts;
+}
+
+const CLI_USAGE =
+  'Usage: node digest.cjs --raw <dir> --out <dir> [--prefer-styles] [--component <name|glob>]';
+
+if (require.main === module) {
+  (async () => {
+    const opts = parseArgv(process.argv.slice(2));
+    if (opts.help) {
+      process.stdout.write(`${CLI_USAGE}\n`);
+      return;
+    }
+    if (!opts.rawDir || !opts.outDir) {
+      process.stderr.write(`${CLI_USAGE}\n--raw and --out are required.\n`);
+      process.exitCode = 2;
+      return;
+    }
+    const res = await digest({
+      rawDir: opts.rawDir,
+      outDir: opts.outDir,
+      preferStyles: opts.preferStyles,
+      component: opts.component,
+    });
+    if (!res.ok) {
+      process.stderr.write(`digest failed: ${res.error}\n`);
+      process.exitCode = 1;
+      return;
+    }
+    if (res.sliced) {
+      const summary =
+        res.matched.length > 0
+          ? `sliced ${res.counts.components} component(s): ${res.matched.join(', ')} (${res.counts.tokens} tokens) → ${res.outDir}`
+          : `${res.note} → ${res.outDir} (empty slice)`;
+      process.stdout.write(`${summary}\n`);
+    } else {
+      process.stdout.write(
+        `digest ok: ${res.counts.components} components, ${res.counts.tokens} tokens, ${res.counts.widgets} widgets → ${res.outDir}\n`
+      );
+    }
+  })().catch((err) => {
+    // Never leak a token; surface only the message.
+    process.stderr.write(`digest error: ${err && err.message ? err.message : err}\n`);
+    process.exitCode = 1;
+  });
+}