@radicool/throughline 0.12.0

package/references/figma-scripting.md

@@ -0,0 +1,278 @@
+# Figma scripting via `figma_execute`
+
+Shared gotchas for **any** skill that writes to Figma through the Console MCP's
+`figma_execute` (component-builder, icon-system-builder, token-builder,
+token-sheet-builder). The bridge runs in Figma's **`dynamic-page`** document mode
+and executes batched JS. Several behaviors below have caused silent, hard-to-
+screenshot corruption — read this before authoring `figma_execute` scripts, and
+keep the read-backs in your post-build audit.
+
+## Preflight: one *live* bridge instance per file (concurrent-write corruption)
+
+Before any write, call **`figma_get_status`** and inspect `otherInstances`.
+Concurrent writes from two **live** Desktop Bridge instances connected to the same
+`fileKey` collide and produce **truncated parent frames and orphaned node
+fragments** at negative coordinates — damage a screenshot won't reveal. So a second
+*live* instance is a hard stop.
+
+**But do not hard-block on *stale* entries (bug B4).** Users routinely hit a wall
+where `otherInstances` lists ports they never opened — phantom/stale connections
+left by a plugin reload, a file switch, or an MCP reconnect that spawned a new port
+without reaping the old one. Telling them to "close the other instance" is useless
+when they never opened one. Distinguish the two cases before blocking:
+
+1. **Verify liveness, don't assume it.** Treat an `otherInstances` entry as
+   *suspected stale* until confirmed live. Attempt a `figma_reconnect` (or re-read
+   `figma_get_status`) — stale ports typically drop out after a reconnect — or use a
+   liveness/heartbeat signal if the MCP exposes one.
+2. **Only the genuinely-live count blocks.** If exactly one live instance remains
+   after reaping stale entries, proceed. Only block when **two or more** instances
+   are confirmed live.
+3. **If you must block, be actionable.** Name the exact ports, state which are
+   suspected stale vs. live, and give a concrete clear path (run `figma_reconnect`,
+   reload the bridge plugin, or restart the MCP client) — never a bare "shut down
+   the others." If only stale entries remain and they won't clear, say so plainly
+   and let the user proceed rather than dead-ending them.
+
+This is the bridge-side application of the read-discipline principle (B4) in
+`${CLAUDE_PLUGIN_ROOT}/references/brownfield-retrofit.md`: don't assert "another
+instance is active" without confirming it's actually live.
+
+## Read discipline: never report "empty" without a verified read (B1/B2)
+
+Before reporting that a file has no variables, no text styles, or no effect styles,
+you MUST have run an explicit read **for that specific class** that returned empty —
+after the file is fully loaded. Two real bugs came from violating this:
+
+- **B1** — a first read returned `0` variables on a fully-populated file (stale/early
+  read) and was reported as fact. **Fix:** `await figma.loadAllPagesAsync()` before
+  counting; treat a `0` on first read as suspect and re-read before reporting; prefer
+  the dedicated `figma_get_variables` tool (handles `dynamic-page`, resolves aliases).
+- **B2** — "no text styles" was asserted because no text *variables* were found —
+  styles were never read. **Fix:** variables and styles are different surfaces. Read
+  each independently: variables (`figma_get_variables`), text styles
+  (`figma_get_text_styles`), effect/paint styles (`figma_get_styles`). Report "none"
+  only for the class whose own read came back empty.
+
+An unexpectedly-empty result is a possible read error, not ground truth. See the
+full principle in `${CLAUDE_PLUGIN_ROOT}/references/brownfield-retrofit.md`.
+
+- **Read-after-write: pass `refreshCache: true` on the verifying read.** A specific
+  trigger of the false-empty class — immediately after a write in the same session,
+  `figma_get_variables` (and similar reads) can return a **stale cached empty** with an
+  old timestamp. Creating 25 semantic variables and reading them straight back returned
+  `variables: []`; the same read with `refreshCache: true` returned all 25. After **any**
+  variable/style write, pass `refreshCache: true` on the read that confirms it.
+
+## `dynamic-page` mode: use the async APIs — reads **and** writes
+
+Synchronous document-wide getters *and several setters* throw under
+`dynamic-page` (the error reads `Cannot call with documentAccess: dynamic-page.
+Use figma.<x>Async instead.`). Use the async variants and `await` them:
+
+- **Node lookup:** `await figma.getNodeByIdAsync(id)` (**not** `figma.getNodeById(id)`).
+  This is the most common one in write-back scripts (finding a doc card / `Status`
+  chip by id) — default every node lookup to the async form.
+- **Reads:** `getLocalVariableCollectionsAsync`, `getVariableByIdAsync`,
+  `getVariablesByCollectionAsync`, `getStyleByIdAsync`, `loadAllPagesAsync`.
+- **Writes / setters:** `setCurrentPageAsync(page)` (**not** `figma.currentPage =`),
+  `setTextStyleIdAsync(id)` (**not** `node.textStyleId =`), and likewise
+  `setFillStyleIdAsync`, `setStrokeStyleIdAsync`, `setEffectStyleIdAsync`.
+
+Generate scripts with the async forms from the start — retrofitting after a sync
+setter throws mid-build is how partial writes happen. For a simple verification
+read, prefer the dedicated `figma_get_variables` tool (it handles `dynamic-page`
+correctly and resolves aliases with `resolveAliases: true`) over a hand-written
+script.
+
+## Set the text style *before* writing `.characters` (font-load order)
+
+`figma.createText()` starts every node as **Inter Regular** — so writing
+`.characters` first throws `Cannot write to node with unloaded font "Inter Regular"`
+even when you only loaded your brand fonts (e.g. Bricolage Grotesque + DM Mono).
+Applying the text style switches the node to a loaded family, so it must come **first**.
+This is the same call surface as the `setTextStyleIdAsync` (dynamic-page) note above —
+both bite in the same place.
+
+```js
+const t = figma.createText();
+await t.setTextStyleIdAsync(style.id);  // switches font to the loaded family FIRST
+t.characters = str;                     // now safe — no Inter load needed
+```
+
+## Binding an effect resets its geometry — re-assert `spread`/`radius`/`offset` after
+
+`figma.variables.setBoundVariableForEffect(effect, 'color', v)` returns a **new**
+effect object that drops every non-color field back to defaults — `spread → 0`,
+`radius → 0`, `offset → {0,0}`. A focus ring built as a drop-shadow (offset 0, blur 0,
+**spread 3**) therefore renders **invisible** after you bind its color: a read-back
+shows `spread: 0` even though the literal set `spread: 3`. Re-assert the geometry
+fields **after** binding, then assign:
+
+```js
+let eff = {type:'DROP_SHADOW', color:{r:0,g:0,b:0,a:1}, offset:{x:0,y:0}, radius:0, spread:3, visible:true, blendMode:'NORMAL'};
+eff = figma.variables.setBoundVariableForEffect(eff, 'color', ringVar);
+eff = {...eff, spread:3, radius:0, offset:{x:0,y:0}}; // REQUIRED — bind wiped these
+node.effects = [eff];
+```
+
+## A drop-shadow casts only from **opaque pixels** — transparent frames get no ring
+
+Unlike CSS `box-shadow` (which draws from the border-box), a Figma `DROP_SHADOW` is
+computed from the node's rendered **alpha**. A no-fill frame has nothing to cast, so a
+shadow-based focus ring (`0 0 0 3px`) shows on filled controls but is **completely
+absent** on transparent variants (outline / ghost / link). **`clipsContent` does NOT
+fix this** — it changes child clipping, not casting geometry (the commonly-cited
+"clip to make the shadow follow the radius" trick does nothing here). Verify by
+temporarily setting the ring to solid red: only filled frames will show it.
+
+**Pattern for a universal ring:**
+- **Filled control** → a drop-shadow effect (clean, no extra node).
+- **Transparent control** → an **absolutely-positioned ring child**: a `RECTANGLE`
+  with `layoutPositioning = "ABSOLUTE"`, `strokeAlign = "OUTSIDE"`, stroke weight = ring
+  width, sized to the parent with `STRETCH` constraints, parent `clipsContent = false`.
+  A **child, not a wrapper** — it doesn't inflate layout and coexists with an existing
+  border.
+
+Both map to the same `box-shadow: 0 0 0 3px var(--ring)` in code. See the build-side
+rules in `${CLAUDE_PLUGIN_ROOT}/references/figma-component-standards.md` ("State
+handling").
+
+## Give a bound paint a sensible placeholder color, and read the bind back
+
+A paint whose color you intend to bind can briefly render its **literal** color if the
+bind is late or doesn't stick — and a pure-black `{0,0,0}` placeholder then reads as an
+accidental **dark-mode** panel (seen once on a component-set background bound to
+`bg/default`; re-running the identical bind fixed it). Two safeguards:
+
+- Seed the paint with the token's **approximate value**, not pure black, so a
+  failed/late bind degrades gracefully.
+- **Read back `fills[0].boundVariables.color`** on container / component-set fills in
+  the post-build audit — a screenshot can't tell a stuck bind from a placeholder.
+
+## `resize()` locks the *opposite* auto-layout axis to FIXED
+
+Calling `node.resize(w, h)` on an auto-layout frame to set one dimension silently
+flips the **other** axis' sizing mode to `FIXED`, pinning it. The classic symptom
+is an auto-layout frame that **collapses to ~10px** on the pinned axis with content
+overlapping or clipped (seen on color grids, variant cells, whole component sets).
+A screenshot may not show it — only a sizing-mode/height read-back does.
+
+**Pattern — prefer the layout-sizing setters; if you must `resize()`, re-assert
+the modes immediately after:**
+
+```js
+// Preferred: express hug/fill intent directly (no axis gets pinned)
+frame.layoutSizingHorizontal = "FILL"   // or "HUG" / "FIXED"
+frame.layoutSizingVertical   = "HUG"
+
+// If resize() is unavoidable, restore the intended modes right after:
+frame.resize(width, frame.height)
+frame.primaryAxisSizingMode  = "AUTO"   // your intended mode
+frame.counterAxisSizingMode  = "AUTO"
+```
+
+Read back `primaryAxisSizingMode` / `counterAxisSizingMode` (or
+`layoutSizing*`) in the post-build audit — a collapsed axis is otherwise invisible
+until handoff.
+
+**The axis mapping is inverted for VERTICAL frames — this is the part that bites.**
+For a **VERTICAL** auto-layout frame, `primaryAxisSizingMode` controls **height** and
+`counterAxisSizingMode` controls **width** (the *opposite* of a HORIZONTAL frame, where
+primary = width). It's very easy to think "fixed width, hug height" and set the axes
+backwards, after which `resize()` pins the wrong dimension — the real symptoms were an
+Input variant collapsing to 10px tall (placeholders overlapping), a Card's *height*
+locking to 10px, and a parent layout frame's height pinned to a stale value.
+
+This is exactly why the **`layoutSizingHorizontal` / `layoutSizingVertical`** setters
+are safer: they name the dimension directly, so there's no primary/counter axis to get
+backwards.
+
+```js
+// VERTICAL frame, want fixed width + hug height:
+frame.layoutMode = "VERTICAL";
+frame.layoutSizingHorizontal = "FIXED";  // width  — unambiguous
+frame.layoutSizingVertical   = "HUG";    // height — unambiguous
+// Equivalent via axis modes (easy to invert): counter = width, primary = height
+// frame.counterAxisSizingMode = "FIXED"; frame.primaryAxisSizingMode = "AUTO";
+```
+
+## Pass an explicit `timeout` for batch / multi-node writes
+
+`figma_execute`'s default timeout (~5000ms) is too low for scripts that touch
+**many nodes in sequence** — especially anything that `await`s `loadFontAsync`
+per node (text edits, doc-card status write-backs). The call **times out mid-run
+with no partial-success signal**, leaving a half-applied write. For any batch
+operation, pass an explicit `timeout` sized to the work — a good rule is
+**`node_count * 3000` ms** (e.g. a 9-card status write-back → `timeout: 30000`).
+Load fonts once and reuse where possible rather than re-loading per node.
+
+**But `figma_execute` is effectively capped at ~30s regardless of the `timeout` you
+pass** — a bigger number is not honored past that ceiling. So `node_count * 3000` is
+only a guide *up to* the cap; a build that genuinely needs more than ~30s must be
+**chunked into multiple `figma_execute` calls**, not handed a larger timeout. Design
+large builds for the cap from the start — the 108-variant Button was built as **3× 36-
+variant passes**. (This is the same ceiling behind the WRAP-chunking rule below.)
+
+## Large wrapped auto-layout (`layoutWrap = "WRAP"`) is expensive — chunk it
+
+Building a large grid as a **single `layoutWrap = "WRAP"` frame in one
+`figma_execute` call** can exceed the execute budget (~30s) and roll back the
+*entire* call. WRAP relayout cost grows disproportionately with cell count. For
+large grids (e.g. a 30+ cell color or variant grid), build **manual rows** —
+nested horizontal auto-layout frames inside a vertical parent — instead of one
+WRAP frame, or split the build across **multiple `figma_execute` calls**. The
+identical content that times out as one WRAP frame builds fine as manual rows.
+
+## Binding-survival audit: count variable bindings before and after a rename
+
+A brownfield retrofit renames variables **in place** to preserve their Figma IDs
+(guardrail 3 in `${CLAUDE_PLUGIN_ROOT}/references/brownfield-retrofit.md` — a
+delete-and-recreate unbinds every consumer). The only way to *prove* a rename kept
+its bindings is to count consuming bindings before and after. Run this read with
+the dedicated tooling where possible (`figma_get_variables`), or via `figma_execute`
+when you need the raw consumer count.
+
+A variable's bindings are not enumerable directly, so count **consumers**: nodes and
+styles whose bound properties reference each variable id. The robust, `dynamic-page`-safe
+approach is to snapshot the total consumer count across the file before the rename,
+rename in place, then re-snapshot and assert equality.
+
+```js
+// dynamic-page safe: load everything, then walk consumers counting variable refs.
+await figma.loadAllPagesAsync();
+
+function countBoundVariableRefs(node, tally) {
+  const bv = node.boundVariables;
+  if (bv) {
+    for (const key of Object.keys(bv)) {
+      const entry = bv[key];
+      const refs = Array.isArray(entry) ? entry : [entry];
+      for (const r of refs) {
+        if (r && r.id) tally[r.id] = (tally[r.id] || 0) + 1;
+      }
+    }
+  }
+  if ('children' in node) {
+    for (const child of node.children) countBoundVariableRefs(child, tally);
+  }
+  return tally;
+}
+
+const tally = {};
+for (const page of figma.root.children) countBoundVariableRefs(page, tally);
+const totalBindings = Object.values(tally).reduce((a, b) => a + b, 0);
+// Report totalBindings (and tally per id) BEFORE the rename; re-run AFTER and
+// assert the total is unchanged. A drop means a binding was severed — STOP and
+// investigate (almost always a delete-and-recreate slipped in).
+```
+
+- **Pass an explicit `timeout`** (this walks every node — size it per the batch-timeout
+  rule above; a large file needs tens of seconds).
+- **Style bindings count too.** Text/effect/paint styles can bind variables; include a
+  pass over `getLocalTextStylesAsync()` / `getLocalPaintStylesAsync()` /
+  `getLocalEffectStylesAsync()` and their `boundVariables` if the file uses style-level
+  bindings.
+- **This is the number `design-system-audit` records** as
+  `audit.figmaInventory.bindings`, and the before/after gate the `token-builder`
+  brownfield branch runs around every rename.

package/references/manifest-schema.md

@@ -0,0 +1,341 @@
+# The `design-system.json` manifest
+
+This file is the single source of truth for **what has been set up** in a user's
+design system. It lives at the root of the user's working directory. It does NOT
+store token values (Figma owns those) — it stores decisions, progression state,
+and pointers.
+
+Every skill's first action is to read this file (creating it with defaults if
+absent). Every skill's last action is to update the fields it owns and report
+what changed. Gating decisions are made by reading this file: if a prerequisite
+field is unset, the skill **offers** to run the prerequisite skill rather than
+bailing or running silently.
+
+## Schema (schemaVersion 4)
+
+```json
+{
+  "schemaVersion": 4,
+  "user": {
+    "codingLevel": "new"
+  },
+  "project": {
+    "uiFramework": null
+  },
+  "workspace": {
+    "name": "my-design-system",
+    "localPath": ".",
+    "stage": "folder",
+    "origin": null,
+    "detectedLayers": {
+      "monorepo": null,
+      "storybook": null,
+      "tokens": null,
+      "syncLayer": null
+    }
+  },
+  "figma": {
+    "mechanism": null,
+    "fileKey": null,
+    "connected": false,
+    "lastVerified": null,
+    "coverPageBuilt": false,
+    "canPublish": null,
+    "libraryPublished": false,
+    "publishedAt": null
+  },
+  "tokens": {
+    "intakeMode": null,
+    "tiers": 2,
+    "primitivesBuilt": false,
+    "semanticBuilt": false,
+    "stylesBuilt": false,
+    "collections": [],
+    "styleGroups": [],
+    "lastSync": null
+  },
+  "sheets": { "built": false },
+  "icons": {
+    "library": null,
+    "version": null,
+    "built": false,
+    "packageInstalled": false,
+    "subset": []
+  },
+  "components": {
+    "built": [],
+    "meta": {},
+    "instanceSwapUpgradePending": []
+  },
+  "repo": {
+    "stage": "none",
+    "packageManager": "pnpm",
+    "monorepo": "turborepo",
+    "remote": null
+  },
+  "sync": {
+    "platforms": [],
+    "customAdapters": [],
+    "lastRun": null
+  },
+  "storybook": {
+    "initialized": false,
+    "chromatic": false,
+    "codeConnect": false
+  },
+  "audit": {
+    "ranAt": null,
+    "codeSurface": null,
+    "figmaInventory": null,
+    "percentSemantic": null
+  },
+  "tokenCrosswalk": {
+    "path": null,
+    "statusCounts": null,
+    "validatorPassing": null
+  },
+  "retrofit": {
+    "phase": null,
+    "startedAt": null,
+    "completedAt": null,
+    "journalScaffolded": false
+  },
+  "completedSkills": []
+}
+```
+
+## Field reference
+
+### `user`
+- `codingLevel` — `"new"`, `"some"`, or `"comfortable"`. Governs how much
+  code/git/terminal concepts are explained in the code-touching skills. Set in
+  `figma-environment-setup` via concrete anchoring questions; changeable
+  anytime. See `${CLAUDE_PLUGIN_ROOT}/references/coding-level.md`. Changes explanation only, never
+  capability. Default `"new"` (over-explaining is recoverable; under-explaining
+  strands beginners).
+
+### `project`
+- `uiFramework` — the target UI framework (e.g. `"shadcn"`, `"mui"`,
+  `"vanilla"`, or a generated target). Captured **lazily at first relevance** —
+  by whichever of `component-builder` or `token-sync-layer` runs first — and read
+  by both, so it's asked once. It does **not** affect tokens (framework-neutral)
+  and does **not** affect Figma component *structure* (also neutral); it informs
+  component **variant vocabulary and naming** so the Figma component API lines up
+  with the framework's code component API. For multi-framework targets, use a
+  neutral vocabulary and let each adapter map it.
+
+### `workspace`
+- `name` — human-friendly project name the user picked.
+- `localPath` — path to the working directory, relative to the manifest. Almost
+  always `"."` since the manifest lives in the working dir.
+- `stage` — the folder→git→github progression. One of:
+  - `"folder"` — a plain local folder, no version control. The default. The
+    entire Figma authoring phase (skills 0–4) is fully usable in this stage.
+  - `"local-git"` — `git init` has been run; local history exists, no remote.
+  - `"github"` — connected to a GitHub remote; PRs and CI are possible.
+
+  Advancing stages is the job of the repository-builder skill (5). Downstream
+  skills that need a later stage (e.g. token-sync wants at least `local-git`)
+  read this field and offer to advance it.
+
+- `origin` — how the user's project was configured at intake time. Set **once** by
+  `figma-environment-setup` Step 0 and never overwritten by any downstream skill.
+  Values:
+  - `"greenfield"` — empty or newly created folder; no repo or tooling detected
+  - `"existing-repo"` — `package.json` present but no monorepo config; user will need
+    to convert to monorepo before the code phase
+  - `"existing-monorepo"` — `detectedLayers.monorepo` is `true` (see detection criteria there); code
+    phase skills should adapt rather than scaffold from scratch
+  - `"unknown"` — scan was inconclusive; treat conservatively (prompt the user)
+  - `null` — intake has not yet run (default)
+
+- `detectedLayers` — snapshot of tooling found in the working directory at intake time.
+  Written by `figma-environment-setup` Step 0, read by downstream skills to adapt
+  behavior. `null` = not yet scanned. `false` = scanned, not found. `true` = found.
+  `detectedLayers` records pre-existing tooling found before any skill ran; it does not replace the canonical per-skill flags (`storybook.initialized`, `repo.monorepo`, etc.) which track whether this project's skills have set those layers up.
+  - `monorepo` — both `turbo.json` and `pnpm-workspace.yaml` are present
+  - `storybook` — `.storybook/` directory is present
+  - `tokens` — `tokens.json` or a `tokens/` directory is present
+  - `syncLayer` — `style-dictionary.config.js` or `*.style-dictionary.js` files present at the project root or within immediate subdirectories
+
+### `figma`
+- `mechanism` — which write mechanism is active. One of `"console-mcp"`
+  (default, recommended) or `"official-plugin"` (lower-setup fallback). Set by
+  skill 0. The adapter layer in every Figma skill reads this to know which tool
+  names to use.
+- `fileKey` — the Figma file key the system writes into (extracted from the
+  file URL). Lets skills target the right file without re-asking.
+- `connected` — whether setup completed successfully at least once. Note this is
+  a record of *setup completion*, not live connection state — connection is
+  verified live each run (see skill 0's liveness check).
+- `lastVerified` — ISO timestamp of the last successful liveness check.
+- `coverPageBuilt` — whether the branded **Cover** page has been generated in the
+  file (set by `token-sheet-builder`, *not* `figma-environment-setup` — the Cover
+  is built after tokens and styles exist so it can be on-brand). The plugin cannot
+  set the file thumbnail via the API, so "set as thumbnail" stays a one-time manual
+  user step.
+- `canPublish` — whether the user can publish a Figma **team library** (requires
+  a paid plan, Professional+). `true` / `false` / `null` (unknown / not yet
+  asked). Asked once and recorded; gates the typed instance-swap dropdown path.
+  See `${CLAUDE_PLUGIN_ROOT}/references/figma-publishing.md`.
+- `libraryPublished` — whether the user has published the file as a library at
+  least once (so local component keys resolve for `INSTANCE_SWAP`). User-driven
+  and manual; the plugin verifies, never publishes. **Treat the default `false`
+  as _unverified_, not "definitely not published" (bug B3): before asserting a
+  library is unpublished, attempt detection (`figma_get_library_components` /
+  `figma_get_library_variables`); if detection is inconclusive, ask the user once
+  and record the answer here. Never silently assume unpublished — see the read
+  discipline in `${CLAUDE_PLUGIN_ROOT}/references/brownfield-retrofit.md`.**
+- `publishedAt` — ISO timestamp the user last confirmed a publish, for "you may
+  need to re-publish after adding components" messaging.
+
+### `tokens`
+- `intakeMode` — how the user started: `"generative"` (seed expanded by AI),
+  `"descriptive"` (from aesthetic direction), `"import"` (existing set
+  organized), or `"retrofit"` (a mature codebase **and** a populated Figma file
+  reconciled onto tokens — the brownfield path; differs from `"import"` by having
+  existing code bindings to inspect and converge). Recorded so later runs know how
+  the system was built.
+- `tiers` — `2` (primitive + semantic, default) or `3` (adds a component tier,
+  multi-brand opt-in only).
+- `primitivesBuilt` / `semanticBuilt` / `stylesBuilt` — phase completion flags.
+  The primitive→semantic checkpoint seam depends on the first two; `stylesBuilt`
+  covers the text/effect/grid styles phase.
+- `collections` — names of the Figma variable collections created. With the
+  per-category structure this is several names per tier, e.g.
+  `["_Color/Primitive", "Spacing/Primitive", "_Typography/Primitive",
+  "_Radius/Primitive", "_Border/Primitive", "Color/Semantic", "Spacing/Semantic",
+  "Typography/Semantic", "Radius/Semantic", "Border/Semantic"]`.
+- `styleGroups` — names of Figma style groups created (e.g.
+  `["Text", "Elevation"]`). Styles are distinct from variables.
+- `lastSync` — ISO timestamp tokens were last extracted to code (set by skill 6,
+  not by the token builder).
+
+### `sheets`
+- `built` — whether the visual "Foundations" page has been generated. Swatches
+  live-bind to variables; labels/descriptions are snapshots refreshed by
+  re-running the token-sheet-builder.
+
+### `icons`
+- `library` — `"lucide"`, `"tabler"`, `"phosphor"`, `"material"`, or `"custom"`.
+  (`lucide`/`tabler`/`phosphor` share the official-SVG-fetch mechanism.)
+- `version` — the library version the Figma mirror was built from (e.g. Lucide
+  `"0.424.0"`). The drift check compares this against the installed npm package
+  so the Figma icons and code icons stay the same generation. `null` for custom.
+- `built` — whether the Figma Icons page has been populated.
+- `packageInstalled` — whether the code-side npm package (`lucide-react`,
+  `@tabler/icons-react`, `@phosphor-icons/react`, `@mui/icons-material`) has been
+  installed. Library icons reach code via install
+  + name mapping, never by generating component code; custom icons reach code via
+  the sync layer's SVGR pipeline instead.
+- `subset` — the curated list of icon names imported (most projects need a
+  subset, not the full library). Grows by re-running icon-system-builder.
+
+### `components`
+- `built` — array of component names created in Figma (e.g. `["Button",
+  "Input"]`). Each component's spec, including icon-slot contracts, is recorded
+  for the code side (via Code Connect when available, else the repo component
+  spec).
+- `meta` — object keyed by component name holding the values stamped onto each
+  component's documentation artboard (see
+  `${CLAUDE_PLUGIN_ROOT}/references/figma-component-standards.md`): `{ "Button":
+  { "status": "stable", "updatedAt": "<ISO>" } }`. `status` is one of
+  `"draft"` / `"beta"` / `"stable"` / `"deprecated"`. **Lifecycle:** a component
+  is created at `"draft"` by `component-builder` (Figma exists, no code yet) and
+  promoted to `"stable"` by `storybook-chromatic-builder` when its code + stories
+  are built and approved. That promotion also writes the new chip color +
+  last-updated date back into the Figma doc card (see "Promoting a component's
+  status" in `${CLAUDE_PLUGIN_ROOT}/references/figma-component-standards.md`) — so
+  the manifest and the artboard never disagree. Re-running a component refreshes
+  its `updatedAt`. Keep `built` (names) as the source of truth for "exists";
+  `meta` is supplementary doc metadata.
+- `instanceSwapUpgradePending` — array of component names whose icon/component
+  slots were built with the **toggle + manual-swap fallback** because the
+  library wasn't published yet, so the typed `INSTANCE_SWAP` dropdown is still
+  owed. A later run (after the user publishes) reads this, adds the typed
+  dropdowns, and clears the entry. See
+  `${CLAUDE_PLUGIN_ROOT}/references/figma-publishing.md`.
+
+### `repo`
+- `stage` — mirrors `workspace.stage` for the repo concern; kept here so repo
+  tooling reads one place. Keep in sync with `workspace.stage`.
+- `packageManager` / `monorepo` — defaults `pnpm` / `turborepo`. Recorded so
+  later skills don't re-ask.
+- `remote` — the GitHub remote URL once `stage` is `"github"`, else `null`.
+
+### `sync`
+- `platforms` — array of adapter targets configured, e.g.
+  `["shadcn", "ios-swift"]`. Curated adapters map to vetted presets; any other
+  name is a generated (Tier 2) adapter.
+- `customAdapters` — names of validated generated adapters saved to
+  `packages/tokens/adapters/` for reuse, so future syncs don't regenerate them.
+- `lastRun` — ISO timestamp the sync command last ran.
+
+### `storybook`
+- `initialized` / `chromatic` / `codeConnect` — setup flags. `codeConnect` stays
+  `false` when the user's Figma plan doesn't support it (the storybook skill
+  degrades gracefully).
+
+### `audit`
+Populated by the `design-system-audit` skill (brownfield front door). `null` in
+every field until that skill runs. Records the measured state of a pre-existing
+system so the retrofit can be right-sized.
+- `ranAt` — ISO timestamp the audit last ran.
+- `codeSurface` — object of counts sizing the code-side retrofit, e.g.
+  `{ "scssColorVars": 692, "tailwindColorClasses": 230, "jsColorsUsages": 74,
+  "rawHexRgba": 143, "svgFills": 430 }`. Keys vary by what the repo actually uses.
+- `figmaInventory` — object snapshot of the existing Figma file from explicit
+  per-class reads, e.g. `{ "variables": 0, "bindings": 0, "textStyles": 0,
+  "effectStyles": 0, "modes": [] }`. Each count comes from a verified read, never
+  an assumption (see `${CLAUDE_PLUGIN_ROOT}/references/brownfield-retrofit.md`).
+- `percentSemantic` — integer 0–100: how much of the existing system is already
+  semantic. The single number that decides rename+cleanup vs. rewrite — see
+  `${CLAUDE_PLUGIN_ROOT}/references/brownfield-retrofit.md` (safe sequence, `audit`
+  phase) for how it's used.
+
+### `tokenCrosswalk`
+Populated by the `token-crosswalk-builder` skill. Points at the backbone artifact
+that maps new token ↔ old Figma token ↔ code identifier.
+- `path` — repo-relative path to the crosswalk file (e.g. `"tokens/crosswalk.json"`),
+  or `null` if not yet built. The manifest stores the pointer, not the map.
+- `statusCounts` — object counting crosswalk rows by `status`, e.g.
+  `{ "aligned": 12, "renamed": 151, "driftFix": 2, "added": 42, "mappedNearest": 3 }`.
+- `validatorPassing` — `true`/`false`/`null`: whether the last crosswalk validator
+  run passed (`resolved value == new value` for every row).
+
+### `retrofit`
+Populated by the `retrofit-planner` orchestrator. Tracks where a multi-phase
+retrofit stands so a later session can resume.
+- `phase` — one of `"audit"`, `"refine"`, `"rebind"`, `"sync"`, `"baseline"`,
+  `"code"`, `"cleanup"`, `"done"`, or `null` (no retrofit in progress). Phases run
+  in that order; see the safe sequence in
+  `${CLAUDE_PLUGIN_ROOT}/references/brownfield-retrofit.md`.
+- `startedAt` / `completedAt` — ISO timestamps bounding the retrofit.
+- `journalScaffolded` — whether the `docs/design-system/` decision journal has been
+  created for this retrofit (offered default-on by `retrofit-planner`).
+
+### `completedSkills`
+- Append-only list of skill identifiers that have run to completion at least
+  once. Useful for the `/design-system-status` command and for friendly
+  "you've already done X" messaging. Never used as the *sole* gate — always
+  pair with the specific field (e.g. check `tokens.primitivesBuilt`, not just
+  presence in this list).
+
+## Rules for skills touching the manifest
+
+1. **Read first, create if absent.** If the file doesn't exist, create it with
+   the defaults above. Never assume it exists.
+2. **Migrate forward on `schemaVersion` mismatch.** If you read a lower
+   `schemaVersion` than you expect, add missing fields with defaults and bump
+   the version. Never delete fields you don't recognize (forward-compat).
+3. **Only write the fields you own.** The token builder doesn't touch
+   `storybook`; the storybook skill doesn't touch `tokens.primitivesBuilt`.
+4. **The manifest is human-readable on purpose.** A designer should be able to
+   open it (or run `/design-system-status`) and understand the state of their
+   system. Keep it tidy; don't dump opaque blobs into it.
+5. **Never store secrets.** No Figma tokens, no Chromatic tokens, no
+   credentials of any kind. The manifest is committed to the repo once
+   `workspace.stage` advances — treat it as public.
+6. **`workspace.origin` is immutable after intake.** Written once by
+   `figma-environment-setup` Step 0 and must not be overwritten by any downstream
+   skill. Skills read it to adapt behavior — they do not modify it.