@radicool/throughline 0.12.0

package/adapters/codex/prompts/storybook-chromatic-builder.md

@@ -0,0 +1,261 @@
+# Storybook + Chromatic builder
+
+Builds the code half of the component library: real components consuming the
+synced tokens, stories documenting them, Chromatic for visual regression, and
+Code Connect tying Figma to code when available.
+
+## Calibrate + prerequisites
+
+Read `user.codingLevel` (`.throughline/references/coding-level.md`) and scale explanation.
+This skill needs:
+
+- A repo with the monorepo scaffold (`repository-builder`, at least
+  `local-git`). Offer to run it if missing.
+- Synced tokens in `packages/tokens` (`token-sync-layer`) so components consume
+  real token files. Offer to run sync if missing.
+- Figma components (`components.built`) with their slot contracts, so stories
+  reflect the real component APIs.
+
+Strongly recommend `github` stage so Chromatic's CI integration works; it can be
+set up locally first and wired to CI when the remote exists.
+
+## Step 1 — Stand up Storybook
+
+Initialize Storybook in `packages/ui` (or the components package), configured for
+the framework the tokens were synced for (e.g. React + Vite for a shadcn/Tailwind
+system). Wire it to consume `packages/tokens` output so stories render with the
+real design tokens (import the generated CSS/theme). Checkpoint: confirm
+Storybook runs and shows the token-themed canvas.
+
+**pnpm build-script allowlist (first-run gotcha).** On pnpm workspaces, the
+`@storybook/react-vite` install pulls `esbuild`, whose postinstall is blocked by
+pnpm's default `onlyBuiltDependencies` policy — Storybook then fails to start with a
+binary-not-found error. When installing Storybook in a pnpm workspace, add `esbuild`
+(and any other native postinstall dep Storybook pulls) to root `package.json`
+`"pnpm": { "onlyBuiltDependencies": [...] }` as part of setup, so first run works.
+
+**Don't duplicate the app's CSS — share it.** Storybook needs the same Tailwind v4
+`@utility` typography rules the app uses to render correctly. **Before adding any,
+check whether the app's global stylesheet (e.g. `apps/web/app/globals.css`) already
+defines them.** If it does, extract the shared `@utility` blocks into a single
+source — e.g. `packages/ui/src/typography.css`, added to the UI package's `exports`
+(`"./typography.css"`) — and replace the inline copies in *both* the app and the UI
+package with one `@import`. If they don't exist yet, create that shared file from
+the start. Copying the rules inline into a second file starts immediate drift (one
+side ends up on the wrong `--font-*` var and nobody notices). Keep Storybook-only
+concerns (Google Fonts `@import`, `:root` font-var fallbacks) in a *separate*
+`styles.css` layer so the shared typography file stays clean and app-shareable.
+
+## Step 2 — Build code components from the Figma spec + slot contracts
+
+For each Figma component (`components.built`), build its code counterpart
+consuming tokens and implementing the **slot contracts** captured by
+component-builder:
+
+- **Icon-set slots** → a prop typed to the icon set (`leadingIcon?`), defaulting
+  to the canonical icon name if specified, imported from the installed icon
+  package (`lucide-react` etc.).
+- **Typed-component slots** → a prop typed to the DS component (`avatar?`),
+  resolved via deterministic naming.
+- **General adornment slots** → a `ReactNode` prop (`endAdornment?`); **Figma
+  slots on composites** (card body, modal content) → `children` / a composition
+  prop, since a Figma slot is the design-tool expression of React composition.
+- **Show/hide** is prop optionality, never a redundant boolean.
+- Variant matrices (type/size/state) become the component's props/variants.
+
+Match the deterministic naming so `Button` (Figma) ↔ `Button` (code).
+
+## Step 3 — Generate stories (subagent-driven, parallel)
+
+Story generation is independent and verifiable per component, so use the
+**subagent-driven model** (code-gen skills parallelize; this is the opposite of
+the sequential Figma-authoring skills): dispatch one subagent per component to
+write its stories — a story per meaningful variant, controls wired to props,
+slot props demonstrated. Each subagent verifies its work (the story builds and
+renders). Two-stage review (does it match the component spec; is it quality
+code) before combining.
+
+**Controls must actually drive the component (args-through render).** A `render`
+that ignores its args silently breaks the Controls panel — the toggle writes to
+`args` but nothing re-renders. So:
+
+- Always thread args through: **`render: (args) => <Component {...args} />`**, never
+  `render: () => <Component variant="..." />` (hardcoded props make the variant
+  radio and other controls dead). Add fixed children/body *after* the spread:
+  `render: (args) => <Card {...args}>{body}</Card>`.
+- **`ReactElement` slot props** (e.g. `avatar?: React.ReactElement`) can't be driven
+  by an auto-generated object control — the panel renders a broken `[object Object]`
+  input. Suppress it (`avatar: { control: false, table: { disable: true } }`) and
+  add a **boolean helper arg** under a `Slots` category that the render function maps
+  to a concrete element — e.g. a `showAvatar` toggle → `avatar={showAvatar ? <Avatar
+  … /> : undefined}`. This gives a real, working slot toggle without asking the user
+  to type JSX into the panel.
+
+**Icon gallery story** — don't write a story per library icon. Generate ONE
+searchable gallery story that imports the icon package and renders the grid
+(optionally with click-to-copy import names). This mirrors the Figma Icons page.
+Custom icons (SVGR-generated, owned by the repo) get normal individual stories
+like any component.
+
+## Step 4 — Set up Chromatic
+
+Set up Chromatic for visual regression testing. Generate the config and the CI
+workflow that runs Chromatic on PRs. This needs a `CHROMATIC_PROJECT_TOKEN`:
+- Following the secrets discipline (`.throughline/references/coding-level.md`), the token
+  value never passes through chat. Tell the user where to get it (Chromatic's
+  project setup page after signing in) and where it goes — `.env` locally
+  (gitignored) and the GitHub Actions secrets vault for CI. The user places it.
+- This is the moment a previously-taught env-file concept becomes concrete
+  (repository-builder taught it; here they actually set the value, because
+  they've now decided to use Chromatic).
+- Verify: after they add the secret, confirm CI runs Chromatic and goes green.
+
+Scale all of this to `codingLevel` — full teaching for `new`, terse for
+`comfortable`.
+
+### TurboSnap vs. design tokens — default to full snapshots
+
+**Recommendation: leave TurboSnap OFF for a design system.** Snapshot every story
+on every run. TurboSnap (`onlyChanged: true`) only re-snapshots stories whose
+changed files it can trace incrementally — and for a token-driven system that
+model is fundamentally fragile, because **token changes are global**: one token
+edit can restyle every component, the opposite of the localized change TurboSnap
+is built for.
+
+Concretely, TurboSnap keeps missing token changes in two independent ways:
+
+- **It doesn't trace changes inside a linked workspace package** resolved under
+  `node_modules` (e.g. `@<scope>/tokens` → `packages/tokens` build output), so a
+  token-only PR — the everyday `/sync-figma-tokens` loop — traces nothing and
+  reports "Capturing 0 snapshots." False green.
+- **Its diffing is incremental against the previous build on the branch.** Once a
+  build has "consumed" a token change, a later commit (a workflow tweak, say)
+  won't re-snapshot it either. The `externals` option is only a partial
+  mitigation and, given the incremental model, is easy to defeat in practice.
+
+So for a design system the robust default is: **snapshot all stories, always.** At
+typical counts (dozens of stories) this is cheap and can *never* miss a global
+token change. Only consider TurboSnap if the story count grows large enough that
+full-run cost genuinely matters — and even then, treat any token change as
+requiring a full run.
+
+Configure Chromatic to snapshot everything (do **not** set `onlyChanged`), and
+verify a token-only PR re-snapshots all stories — they should flip orange against
+the green baseline.
+
+## Step 5 — Code Connect (plan-gated, skip gracefully)
+
+Code Connect ties Figma components to their code counterparts so Figma's dev
+mode shows the real code. It's plan-gated (Figma Organization/Enterprise).
+
+- Detect or ask whether the user's plan supports Code Connect.
+- **If yes:** wire it up — map each Figma component to its code component,
+  including the slot contracts (this is the formal home of the icon/component
+  slot bindings). Record `storybook.codeConnect` = `true`.
+- **If no:** skip gracefully and say why in plain terms ("Code Connect needs a
+  Figma Organization plan — we'll skip it; everything else works, and your
+  component spec in the repo still records the Figma↔code mapping"). Don't block
+  the rest of the setup.
+- **Publishing & pending swap upgrades:** Code Connect and typed slot mappings
+  line up best once the Figma library is published (see
+  `.throughline/references/figma-publishing.md`). If
+  `components.instanceSwapUpgradePending` is non-empty, those components still owe
+  a *typed instance-swap dropdown in Figma* — added by a later component-builder
+  run after the user publishes. This does **not** block the code side: implement
+  each slot prop from the recorded slot contract regardless of the Figma dropdown.
+
+## Step 6 — Finalize component status (Figma write-back)
+
+A component built and storied here is now **done** — but its Figma doc card was
+stamped `draft` by component-builder and won't change on its own. Once the code
+component renders and its stories build (and the user has approved the result),
+**promote each finalized component to `stable`** so the design system tells the
+truth in both places.
+
+**Confirm the write-back once, up front.** Before touching Figma, state the batched
+change in one line and get a yes — *"I'll update the N doc cards in Figma: flip the
+status chips amber → green and set Last Updated to today. Confirm?"* The user
+approved the *components*, but writing to their Figma file is a separate external-
+system action that needs explicit consent (and an unannounced write trips the safety
+classifier, forcing the round-trip anyway). One confirmation covers all cards.
+
+For every component you finalized in this run, follow the **"Promoting a
+component's status (write-back on finalize)"** routine in
+`.throughline/references/figma-component-standards.md` (which also covers
+the `figma_execute` scripting gotchas — `getNodeByIdAsync` and an explicit
+`timeout` for the multi-card write):
+
+- Set `components.meta[name].status` = `"stable"` and refresh
+  `components.meta[name].updatedAt` to today.
+- If Figma is connected (per `figma.mechanism`), open the component's doc card and
+  update the `Status Label` text to `stable`, re-bind the `Status` chip fill to
+  the **success** semantic color variable (mode-aware, not a hardcoded hex), and
+  set `Last Updated` to today's date — then screenshot to confirm the chip
+  recolored and the date changed.
+- If Figma isn't connected, still update the manifest and tell the user the card
+  will reconcile next Figma session (or offer to reconnect and fix it now).
+
+Once confirmed, do the whole batch in one pass as part of finishing — don't make
+the user re-approve each chip. (`stable` is the finalized status; if a component is
+intentionally still experimental, leave it at `beta` and say so.)
+
+## Step 7 — Update manifest + hand off
+
+Set `storybook.initialized` = `true`, `storybook.chromatic` accordingly,
+`storybook.codeConnect` accordingly. Append `storybook-chromatic-builder` to
+`completedSkills`. (Per-component `status`/`updatedAt` were already updated in
+Step 6.) Note the ongoing loop: new components flow through the
+component-pipeline orchestrator; token changes flow through `/sync-figma-tokens`.
+
+## Brownfield: baseline before retrofit + the verification triad
+
+On a **retrofit** (`tokens.intakeMode: "retrofit"`), the order of operations and the
+verification bar are stricter than greenfield. **Read
+`.throughline/references/brownfield-retrofit.md`** — the safe sequence and the
+verification triad live there.
+
+**Capture the Chromatic baseline BEFORE the code retrofit.** Run `build-storybook` +
+Chromatic to establish a green baseline *before* any token/color code is changed. Then,
+when the retrofit lands, every diff is either an **intended drift-fix** (a color the
+audit flagged as wrong) or a **regression** — and the baseline is the only thing that
+tells them apart. Baseline *after* the retrofit and you've thrown away that signal.
+
+**The verification triad — all three are necessary; no single check catches everything:**
+1. **`check-types` (TypeScript)** — catches type errors, but is **blind to Tailwind
+   silent no-ops**: a deleted color utility just stops applying, with no type error
+   (guardrail 4).
+2. **`build-storybook` + Chromatic snapshots** — the visual-regression net, but **blind
+   to story-unreachable code**. `build-storybook` only compiles SCSS that some story
+   actually imports; a dead `@import` of a deleted partial, or a route's styles no story
+   renders, compiles "fine" here and breaks only in the app. **Chromatic — not
+   `tsc`/build — is the source of truth** for whether a color-utility removal was safe.
+3. **Run the actual app + spot-check 5–7 real routes** — the only thing that exercises
+   story-unreachable SCSS (guardrail 5). Don't declare an SCSS/color change done on the
+   strength of a green build alone.
+
+**Don't assume the stack (§11).** This triad names Chromatic + `build-storybook`
+because that's the case-study tooling. Detect what the repo actually uses — read its
+`package.json` scripts for the real type-check / build / visual-test commands — and map
+the triad onto them (or degrade gracefully and say so) rather than asserting commands
+that may not exist.
+
+## What this skill must NOT do
+
+- Never finish a finalized component while leaving its Figma doc card on `draft`
+  — promote the status and write it back (Step 6).
+- Never write a story per library icon — one gallery story.
+- Never put a secret value through chat or commit it — user places it, scaled to
+  level.
+- Never block setup when Code Connect is unavailable — skip gracefully.
+- Never hardcode token values in components — consume `packages/tokens`.
+- Never rely on TurboSnap (`onlyChanged: true`) for a token-driven design system
+  — its incremental model keeps missing global token changes. Default to full
+  snapshots (every story, every run); revisit only at large story counts.
+- Never use the sequential model for story-gen — parallelize via subagents.
+- Never capture the Chromatic baseline *after* a code retrofit — baseline before, so
+  intended drift-fixes are distinguishable from regressions.
+- Never trust `tsc`/build to catch Tailwind color-utility removal — it's a silent
+  no-op; Chromatic is the source of truth (guardrail 4).
+- Never declare an SCSS/color change done on a green build alone — run the app and
+  spot-check 5–7 real routes (guardrail 5).
+

package/adapters/codex/prompts/sync-figma-tokens.md

@@ -0,0 +1,22 @@
+Re-run the token sync pipeline to catch any updates made in Figma.
+
+Follow the `token-sync-layer` prompt's pipeline using the settings already
+recorded in `design-system.json` (`sync.platforms`, `figma.mechanism`,
+`figma.fileKey`) — don't re-ask configuration that's already set. Specifically:
+
+1. Verify Figma is connected (cheap liveness read); if not, offer
+   `figma-environment-setup`.
+2. Re-extract Figma variables to DTCG JSON.
+3. Rebuild outputs through Style Dictionary for every platform in
+   `sync.platforms`.
+4. Run full-regeneration with **rename detection** — diff against the previous
+   output, flag probable renames (vanished + reappeared with identical
+   `$value`/`$type`) and plain deletions.
+5. Open a **reviewable PR** (or a reviewed branch diff if the repo is only
+   `local-git`) summarizing added / changed / deleted / probable-renames. Never
+   write silently.
+6. Update `sync.lastRun` and `tokens.lastSync` in the manifest.
+
+Scale explanation to `user.codingLevel`. This is the recurring loop of the whole
+system: tokens change in Figma → `/sync-figma-tokens` → review PR → merge.
+

package/adapters/codex/prompts/token-builder.md

@@ -0,0 +1,361 @@
+# Token builder
+
+> **Critical collection rule:** this system uses **one collection per category per tier** — never one giant `Primitives` + one giant `Semantic`. Color, spacing, typography, radius, and border each get their own primitive collection and their own semantic collection. This is non-negotiable: modes (Light/Dark, Desktop/Mobile) belong to a collection, so mixing categories in one collection forces unrelated variables to share the same mode axis.
+
+> **Model tip (#3):** building a coherent token system (ramps, type scale, modes,
+> primitive→semantic aliasing) is reasoning-heavy. It runs on your session model —
+> Sonnet is a solid default; Opus helps for large or multi-mode systems. See the
+> model guide in the ThroughLine README.
+
+Creates a two-tier design token system as Figma variables. Each tier is split
+into **one collection per category** (color, spacing, type, radius, border) so
+every category owns its own modes — see Step 1 for why. Within a collection,
+Figma variables are grouped with `/` and omit the category prefix (the
+collection already carries it); the sync layer later derives the dotted logical
+name (`color.gray.50`) by prefixing the collection's category.
+
+- **Primitives** — raw values with no meaning attached: `gray/50`, `space/4`
+  in their category's primitive collection. The full palette of possible values.
+- **Semantic** — meaning-bearing tokens that **alias onto primitives**:
+  `bg/default` → `{gray/50}`, `text/primary` → `{gray/900}`. This is the layer
+  the rest of the system consumes.
+
+The power of two tiers: change a primitive once and every semantic token
+referencing it updates automatically, which cascades through sheets, components,
+and synced code. Preserving these aliases (not flattening them) is what makes
+runtime theming work later, so **always create semantic tokens as references to
+primitives, never as copied literal values.**
+
+## Prerequisites
+
+This skill needs a live Figma connection. Read the manifest
+(`.throughline/references/manifest-schema.md` for the schema) and check `figma.connected`.
+Then do a cheap liveness read to confirm the connection is actually live right
+now. If it isn't, say so plainly and offer to run the `figma-environment-setup`
+skill first: "Figma isn't connected yet — want me to set that up? It's a
+one-time thing." Don't proceed until Figma is reachable.
+
+Use the write mechanism recorded in `figma.mechanism` (default `console-mcp`).
+With Console MCP, prefer `figma_execute` to create variables in scripted loops
+rather than one tool call per variable — this is dramatically more
+token-efficient for the potentially hundreds of primitives across modes.
+
+**Scripting via `figma_execute`:** see
+`.throughline/references/figma-scripting.md` for the shared gotchas —
+the single-bridge-instance preflight (concurrent writes corrupt the file), the
+`dynamic-page` async APIs (synchronous document-wide getters like
+`getLocalVariableCollections` **and** setters like `figma.currentPage =` /
+`node.textStyleId =` throw — use `getLocalVariableCollectionsAsync`,
+`setCurrentPageAsync`, `setTextStyleIdAsync`, …), the `resize()` axis-lock trap,
+and why large `WRAP` grids time out. 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.
+
+## Step 1 — Brainstorm the structure (before building anything)
+
+Run the protocol in `.throughline/references/brainstorm-before-build.md`. **First establish
+the intake mode** (generative / descriptive / import) per that reference — it
+changes how much you generate versus preserve. **In import mode, do not stop at a
+1:1 transcription of what the user fed you** (a brand guide or marketing site is
+almost always a partial system): after preserving and organizing their values,
+run the **completeness pass** from that reference — diff against the full-system
+model and proactively propose the missing pieces (tonal ramps, neutral ramp,
+state colors, dark mode, semantic roles, elevation/radius scales) as a
+preserve-first, opt-in menu derived from their existing values. Then lock the
+structure with the user, in readable chunks:
+
+- **Seeds and direction** — capture what the user actually has: brand color(s),
+  font(s), aesthetic words (modern, rounded, dense, comfortable), reference
+  images/URLs, or an existing token set to import. In generative mode, this is
+  the seed you expand from; in import mode, this is the set you organize.
+- **Color ramps** — which hues (e.g. gray, brand primary, success, warning,
+  danger), and how many steps each (a 50–900 ramp of ~10 steps is a sensible
+  default). In generative mode, derive a full tonal ramp and harmonized
+  supporting families from the user's seed color(s).
+- **Modes** — does the system need light + dark? Brand variants? Density? This
+  is high-impact and shapes everything downstream (it determines how many values
+  each variable holds and how the sync layer emits themes), so brainstorm it
+  carefully. Default: light + dark.
+- **Spacing scale** — base unit and steps (e.g. 4px base: 0, 1, 2, 3, 4, 6, 8,
+  12, 16, 24...). Default to a 4px-based scale; "dense" pulls it tighter,
+  "comfortable" looser.
+- **Type scale** — font families, the size ramp, weights, line-heights. In
+  generative mode, propose complementary font pairings from the user's seed
+  font. Default to a modular scale.
+- **Radius / border / shadow** scales as needed. "Rounded" → larger radius
+  scale.
+- **Primitive naming convention** — the single most important decision, because
+  the semantic tier aliases onto these names and renaming later breaks every
+  alias. Lock it explicitly. In Figma, name variables **without the category
+  prefix** (the collection supplies it) and group with `/`: e.g. `gray/50`,
+  `space/4`, `radius/md` inside their category's primitive collection. The sync
+  layer derives the dotted logical identity (e.g. `color.gray.50`) by prefixing
+  the collection's category. Keep names **neutral and semantic — never
+  framework-specific** (don't name a token `--background` to match shadcn; the
+  adapter renames per framework later). Figma is framework-agnostic; the adapter
+  absorbs all framework-specific shaping.
+- **Tiers** — default to **two-tier** (primitive + semantic). Only raise the
+  option of a third **component** tier if the user signals multi-brand,
+  white-labeling, or a very large/robust component library — for a single-brand
+  project it adds complexity without payoff, so don't even surface it. If the
+  user opts in, component tokens alias onto semantic tokens (e.g.
+  `bg/primary` → `{bg/emphasis}`).
+- **Collection structure** — two *tiers*, but **one collection per category per
+  tier**, never one giant `Primitives` + one giant `Semantic`. In Figma a mode
+  axis (Light/Dark, Desktop/Mobile, Brand) belongs to the *collection*, so every
+  variable in a collection is forced to share its modes. Putting `space` in the
+  same collection as `color` drags spacing into Light/Dark, which is meaningless.
+  Default layout (single-brand): private primitive collections `_Color/Primitive`,
+  `_Typography/Primitive`, `_Radius/Primitive`, `_Border/Primitive`, and a
+  **public** `Spacing/Primitive`; published semantic collections `Color/Semantic`
+  (Light/Dark), `Spacing/Semantic`, `Typography/Semantic`, `Radius/Semantic`,
+  `Border/Semantic`. Privacy is the leading-`_` prefix. `size/icon/*` lives in
+  `Spacing/Primitive`; don't create a `Sizing` collection unless control
+  heights/avatars become real tokens.
+- **Multi-brand** — keep two axes in two collections so they don't multiply.
+  Brand lives on `_Color/Primitive` (modes = Brand A, Brand B = raw palettes);
+  Theme lives on `Color/Semantic` (modes = Light, Dark). A frame sets both
+  independently and Figma resolves `bg/default`(Light) → `{gray/50}` → Brand A's
+  gray. This keeps each collection ≤2 modes — under the Figma **Professional cap
+  of 4 modes/collection**. (Brand-on-primitive assumes brands differ in raw
+  palette, same role mapping; if a brand needs a *different* mapping, it also
+  becomes a mode on `Color/Semantic`.)
+
+Show the proposed full structure back to the user and get sign-off before
+creating anything.
+
+### The structural-consistency rule (prevents the "different every time" problem)
+
+Every token concern gets **both** a primitive and a semantic collection, even
+when the semantic tier is a 1:1 passthrough today. A dimensional semantic tier
+(`Spacing/Semantic`, `Radius/Semantic`, `Border/Semantic`) is justified by a
+**plausible future mode axis** — e.g. adding Desktop/Mobile to spacing later —
+which only works if the semantic collection already exists to carry that axis.
+Building every concern the same way is also what makes the output consistent
+run-to-run instead of an arbitrary guess about which categories to duplicate.
+
+The one guardrail: **consistency does not license invented roles.** Semantic
+names must be real usage roles (`inset/md`, `width/focus`, `text/primary`),
+never just renamed primitive steps (`space/12`, `width/1`). A passthrough role
+with a meaningful name is fine; a fake role nobody applies is not. If you can't
+name a genuine role for a category, give it semantic roles that map to actual
+usage rather than mirroring the primitive scale step-for-step.
+
+## Step 1.5 — Brownfield: refine existing variables in place (don't rebuild)
+
+If this is a **retrofit** (`tokens.intakeMode: "retrofit"`, or the file already has
+variables), do **not** create a fresh set on top of the old one. Refine what exists,
+in place. **Read `.throughline/references/brownfield-retrofit.md` first** —
+guardrail 3 is the whole point of this branch.
+
+**The hard rule (guardrail 3):** rename and realign variables **in place** to preserve
+their Figma IDs. **Never delete-and-recreate** — every binding (a populated file can
+have thousands) references the variable *id*, so recreating under the same name still
+unbinds everything. A rename keeps the id; a delete+create does not.
+
+**The refine loop:**
+
+1. **Read what exists** (read discipline). Use `figma_get_variables` after
+   `await figma.loadAllPagesAsync()`. List the existing collections, variables, and
+   values. Treat a `0`/empty first read as suspect — re-read before concluding the file
+   is empty.
+2. **Snapshot bindings before.** Run the binding-survival audit in
+   `.throughline/references/figma-scripting.md` to record the total consuming
+   binding count *before* any change. This is your guardrail-3 tripwire.
+3. **Rename / realign in place.** Use the rename operation that keeps the id (e.g.
+   `figma_rename_variable` / setting `variable.name`), and update values in place. Map
+   old names to the new two-tier scheme; record each old→new mapping (the crosswalk
+   consumes it later via `token-crosswalk-builder`).
+4. **Snapshot bindings after, and assert equality.** Re-run the binding-survival audit.
+   The total **must be unchanged**. A drop means a binding was severed — STOP, find the
+   delete-and-recreate that slipped in, and restore from the baseline.
+5. **Add genuinely-new variables** (the `added` rows) as normal creates — only the
+   *existing* ones must be renamed rather than recreated.
+
+After the refine loop, continue with the normal tiers below for any net-new structure,
+but **skip recreating anything that already exists**. The primitive/semantic checkpoint
+(Step 2's PAUSE) still applies: lock names before building dependent semantics.
+
+## Step 2 — Build the PRIMITIVE tier, then PAUSE
+
+Create the **per-category primitive collections** and their variables via a
+scripted loop on the active write mechanism. Default set:
+
+- `_Color/Primitive` — color ramps (`gray/50…900`, `brand/50…900`,
+  `success`/`warning`/`danger`, `white`, `black`).
+- `Spacing/Primitive` — the spacing scale (`space/0,2,4,8,12,16,24,32,48,64`)
+  **plus** `size/icon/{sm,md,lg}`.
+- `_Typography/Primitive` — `family/*`, `size/*`, `weight/*`, `lineHeight/*`,
+  `letterSpacing/*`.
+- `_Radius/Primitive` — `radius/{none,sm,md,lg,xl,full}`.
+- `_Border/Primitive` — `width/{0,1,2,4}`. **Do not skip border width** — borders
+  need a width primitive, not only a color.
+
+**Privacy:** the leading-`_` prefix hides a collection from the published
+library. Keep color/type/radius/border primitives private (they're always
+consumed through semantics or styles). Make **`Spacing/Primitive` public** (no
+underscore) — spacing semantics are intentionally minimal, so designers will grab
+raw `space/*` for one-off gaps. Note the trade-off in your checkpoint summary: a
+value applied directly from `Spacing/Primitive` is *frozen across device modes*;
+only `Spacing/Semantic` carries future Desktop/Mobile responsiveness.
+
+**Modes at the primitive tier:** primitives are usually mode-free (a single
+*Value* mode). The exception is multi-brand: give `_Color/Primitive` a Brand mode
+axis (Brand A, Brand B) holding each brand's raw palette. All other primitive
+collections stay single-mode.
+
+Then **stop and checkpoint.** This is the critical seam: semantic tokens are
+about to alias onto these primitives, so the primitive names and values must be
+right *before* you build on them. Show the user the created collections —
+summarize the ramps and scales, note which are public vs private, and if helpful
+mention the token-sheet-builder skill can render them visually later. Ask for
+explicit confirmation: "Here are your primitives. Once you're happy, I'll build
+the semantic layer on top — and after that, renaming primitives gets disruptive,
+so this is the moment to adjust names or values."
+
+Update the manifest: `tokens.primitivesBuilt` = `true`, add every created
+collection name to `tokens.collections`.
+
+Do not proceed to the semantic tier until the user confirms.
+
+## Step 3 — Build the SEMANTIC tier as aliases
+
+Create the **per-category semantic collections**, where every variable
+**references a primitive**, not a literal value. Bind each semantic variable to
+its primitive so the alias is live. Default set and modes:
+
+- `Color/Semantic` — modes **Light, Dark** (+ a Brand mode only if a brand needs
+  a different *mapping*, not just a different palette). Roles: `bg/{default,
+  subtle,muted,emphasis,inverse}`, `text/{primary,secondary,disabled,inverse,
+  link,onEmphasis}`, `border/{default,subtle,focus,emphasis}`,
+  `status/{success,warning,danger}/{bg,text,border}`,
+  `shadow/{ambient,key}`. The **`shadow/*`** roles are the colors the elevation
+  effect styles consume (Step 4) — they carry alpha and are **mode-aware**: a
+  low-alpha near-black in Light, and a darker/higher-alpha value in Dark, so
+  toggling modes recolors every elevation. They live here in `Color/Semantic`
+  (rather than as part of the effect style) precisely so the Light/Dark switch
+  reaches them; alias a near-black primitive where the alpha allows, otherwise
+  set the rgba per mode directly. **`text/onEmphasis`** is the
+  label/icon color that sits **on** `bg/emphasis` (a primary button's text, a
+  filled badge) — it must contrast with the emphasis fill in *every* mode, so it's
+  a distinct role, **not** `text/inverse` (which flips with the theme and won't
+  reliably contrast a brand-colored emphasis fill). Component-builder binds primary/
+  filled control labels to this role; without it, builds fall back to literals and
+  break the "everything bound" audit.
+- `Spacing/Semantic` — single *Default* mode now, structured so Desktop/Mobile
+  can be added later. Roles: `inset/{xs,sm,md,lg,xl}`, `stack/*`, `inline/*`.
+- `Typography/Semantic` — single *Default* mode (room for Desktop/Mobile). Roles:
+  `size/{body,bodyLg,heading/sm…xl,caption}` and role line-heights; these feed
+  the text styles built in Step 4.
+- `Radius/Semantic` — single mode. Roles: `control`, `card`, `pill`, `field`.
+- `Border/Semantic` — single mode. Roles: `width/{default,focus,emphasis}`
+  aliasing `_Border/Primitive` widths, plus **`offset/focus`** (the gap between a
+  control's edge and its focus ring, the `outline-offset` equivalent) aliasing the
+  `2` width primitive. It's used by the **outline-style** focus recipe (e.g.
+  `vanilla-css`) to keep the ring clear of the edge for accessibility; library idioms
+  that render focus as a spread-shadow ring don't need it — see "State handling" in the
+  component standards for the per-library recipes.
+- `Opacity/Semantic` (when the system needs disabled/overlay states) — single
+  mode. Roles: `disabled`, `muted`, `overlay/scrim`, `hover`, aliasing
+  `_Opacity/Primitive`. See the **opacity scale rule** below — this is the one
+  category where the Figma value scale is a trap.
+
+> **⚠️ Opacity is stored 0–100, NOT 0–1 (critical).** When a variable is bound to
+> a node's **`opacity`** field, Figma treats the value as a **0–100 percentage and
+> divides by 100**. So an opacity primitive must be created on the **0–100 scale**:
+> `_Opacity/Primitive` `40` has the value **`40`** (which renders as 0.4), never
+> `0.4` (which would render as 0.004 — effectively invisible). Name and value must
+> match (`40` = `40`), and a bound `disabled`/`overlay` element renders correctly.
+> The sync layer is responsible for the inverse: CSS `opacity` is 0–1, so it
+> **÷100 on emit** — token-builder and token-sync-layer are a **matched pair** here.
+
+These dimensional semantic tiers are often passthroughs today — that's expected
+under the structural-consistency rule; keep the role names real (`inset/md`, not
+`space/16`).
+
+The **color** semantic tier is where the Light/Dark switch lives:
+`bg/default` → `{gray/50}` in Light and `{gray/900}` in Dark. Primitives
+stay fixed; the semantic aliases differ per mode. This is exactly what lets the
+sync layer emit `:root`/`.dark` for web later.
+
+**Mode-application reality (state this to the user):** a frame can now carry up
+to three independent modes — Brand (`_Color/Primitive`), Theme (`Color/Semantic`),
+and later Device (`Spacing`/`Typography`). That's the cost of independent axes.
+
+Verify the aliases resolve — use `figma_get_variables` (filtered to the new
+semantic collection, `resolveAliases: true`) to confirm semantic tokens point at
+primitives, not literals; if you read via a `figma_execute` script instead, use
+the async APIs (see the dynamic-page note in Prerequisites). Then checkpoint:
+show the semantic layer and demonstrate the cascade if useful ("change `gray/50`
+and `bg/default` follows").
+
+Update the manifest: `tokens.semanticBuilt` = `true`, add every semantic
+collection to `tokens.collections`.
+
+## Step 4 — Build Figma STYLES (the third phase)
+
+Figma variables can't express everything a design system needs. Composed
+**styles** must be created as a distinct phase *after* the variables exist, so
+they can **bind to the tokens you just built** rather than duplicating values:
+
+- **Text styles** — a full type scale needs one text style per role/size
+  (e.g. `Heading/XL`, `Body/Default`, `Caption`), each composing family + size +
+  weight + line-height + letter-spacing. Bind size and family to the
+  corresponding `font.*` variables where Figma supports it, so changing a font
+  primitive updates the text styles. A type scale is NOT just variables — these
+  composed text styles are what designers actually apply to text layers.
+- **Effect styles** — drop shadows and elevation levels (e.g. `Elevation/1`
+  through `Elevation/5`), driven by the shadow scale from the brainstorm. The
+  *composition* (offset, blur, spread) is what makes this a style rather than a
+  variable — but the shadow **color must be bound to the `shadow/*`
+  `Color/Semantic` variables**, never hardcoded. Figma supports binding the color
+  of a drop shadow inside an effect style to a color variable; do that for every
+  shadow in every elevation level. This is what makes elevations **mode-aware**:
+  because the bound `shadow/*` variable carries different values per mode, toggling
+  Light/Dark recolors all elevations automatically. A style with a literal shadow
+  color is the bug — it stays the same color in dark mode. (Heavier elevations may
+  layer two shadows, e.g. an ambient + a key shadow; bind each to `shadow/ambient`
+  and `shadow/key` respectively.)
+- **Grid styles** — layout grids if the user wants them (column/row grids for
+  their breakpoints). Optional; only if requested.
+
+Generate styles via the active write mechanism (scripted where possible). Bind
+to variables wherever Figma allows so styles consume tokens rather than
+duplicating them. Checkpoint with the user: show the created styles.
+
+Update the manifest: set `tokens.stylesBuilt` = `true` and record which style
+groups were created in `tokens.styleGroups`. Append `token-builder` to
+`completedSkills`.
+
+## Step 5 — Hand off
+
+Tell the user what's unlocked and offer natural next steps without forcing them:
+generate a visual stylesheet of all tokens (token-sheet-builder), build an icon
+system (icon-system-builder), or start on components (component-builder). If
+they're heading toward code, mention that the token-sync skill will later turn
+these exact variables into code files — but only when they have a repo, which
+comes later.
+
+## Notes that matter
+
+- **Never flatten semantic into literals.** Aliases are the whole point.
+- **One collection per category per tier.** Modes belong to the collection, so
+  splitting by category is what keeps color's Light/Dark from infecting spacing.
+- **Privacy is the `_` prefix.** Only `Spacing/Primitive` is public by default;
+  all other primitives are private.
+- **Primitives can be multi-mode.** Brand lives on `_Color/Primitive`; the sync
+  layer must emit brand themes from the primitive tier, not just light/dark from
+  semantics.
+- **Lock primitive names before building semantics.** The checkpoint between
+  tiers exists precisely to prevent rename cascades.
+- **Think in DTCG terms even though you're writing Figma variables.** Each token
+  has a value and a type (color, dimension, fontFamily, etc.). The sync layer
+  will later normalize these Figma variables into DTCG-format JSON, so keep
+  types clean and consistent — it makes the downstream sync trivial.
+- **Token-efficiency:** scripted loops via `figma_execute`, batched per tier —
+  not per-variable tool calls.
+- **Brownfield: never delete-and-recreate to rename (guardrail 3).** On a retrofit,
+  rename variables in place to preserve their Figma IDs and every binding. Snapshot the
+  binding count before and after each rename and assert it's unchanged — see Step 1.5
+  and `.throughline/references/figma-scripting.md`.
+