@radicool/throughline 0.12.0

package/adapters/cursor/.cursor/rules/token-crosswalk-builder.mdc

@@ -0,0 +1,124 @@
+---
+description: "Build the brownfield token crosswalk — a persistent three-way map between each new token, the old Figma variable, and the old code identifier(s) — as crosswalk.json, then install the vetted validator/reverse-index scripts into the monorepo and wire the tokens:validate CI gate. Use this when retrofitting a design system onto a mature codebase, when the user wants to map old tokens to new ones, build a crosswalk, set up tokens:validate, or generate a reverse index for SCSS/Tailwind swaps. Also trigger when retrofit-planner reaches the crosswalk stage, or after design-system-audit has sized the retrofit. Make sure to use this whenever someone needs the machine-readable backbone that drives a brownfield code retrofit and its validation gate."
+alwaysApply: false
+---
+# Token crosswalk builder
+
+Builds the **backbone artifact** of a brownfield retrofit: `crosswalk.json`, a
+persistent three-way map of **new token ↔ old Figma variable ↔ old code identifier**.
+It drives the code retrofit and the `tokens:validate` CI gate. This skill also
+installs the canonical scripts into the user's repo and wires the gate.
+
+This is a brownfield skill. **Before doing anything, read**
+`.throughline/references/brownfield-retrofit.md` (read discipline, the 7
+guardrails, the safe sequence) and
+`.throughline/references/crosswalk-schema.md` (the exact contract). Greenfield
+builds don't need this skill.
+
+## Calibrate
+
+Read `user.codingLevel` (`.throughline/references/coding-level.md`) and scale
+explanation accordingly. The crosswalk involves JSON, npm scripts, and a CI gate — for
+`new` users explain each plainly the first time; for `comfortable` users be terse.
+Actions are identical across levels.
+
+## Prerequisites (offer to run them, don't bail)
+
+Read the manifest. This skill needs:
+
+1. **A DTCG token source** at `packages/tokens/dtcg/tokens.json` — the validator
+   resolves against it. If it doesn't exist, offer to run `token-sync-layer` first
+   (it emits this file). Apply the read discipline: confirm the file exists by
+   reading it, never assume it's absent without looking.
+2. **The audit inputs** — ideally the `audit` manifest section (code surface,
+   Figma inventory, `percentSemantic`) populated by `design-system-audit`. If
+   `audit` is present, use it to seed the rows. If it is `null` (audit hasn't run —
+   it lands in Plan 3), don't block: ask the user for the old→new mapping inputs
+   directly (which old Figma variables and code symbols map to which new tokens),
+   and proceed. Note plainly that running `design-system-audit` first would
+   pre-fill this.
+3. **A repo at `local-git` or `github`** (`workspace.stage`) so the installed
+   scripts and `package.json` changes land as a reviewable diff/PR. If still
+   `folder`, offer `repository-builder`.
+
+## Step 1 — Build `crosswalk.json`
+
+Write `packages/tokens/crosswalk.json` per the contract in
+`.throughline/references/crosswalk-schema.md`. One row per new token:
+
+- `newToken` — the DTCG dot-path exactly as it appears in
+  `packages/tokens/dtcg/tokens.json` (e.g. `color.text.primary`).
+- `newValue` — the **resolved** leaf value (follow `{…}` aliases to the literal).
+- `tier` — `primitive` or `semantic`.
+- `figmaOld` — the old Figma variable name/path, or `null` if newly added.
+- `codeTokens[]` — the old code identifiers this token replaces (`$primary-red`,
+  `bg-primary-red`, `Colors.primaryRed`, `--primary-red`). May be `[]`.
+- `status` — `aligned | renamed | drift-fix | added | mapped-nearest`. Assign by:
+  same name & value → `aligned`; same value, new name → `renamed`; value
+  intentionally changed → `drift-fix`; brand-new token → `added`; no exact old
+  equivalent, mapped to nearest → `mapped-nearest`.
+- `recommendedSemantic` — optional semantic target for a raw/primitive usage, else
+  `null`.
+
+Do not guess values. Every `newValue` comes from a read of the DTCG source, not an
+assumption (read discipline).
+
+## Step 2 — Install the vetted scripts + wire `tokens:validate`
+
+Copy these from `.throughline/scripts/` into the user's repo **verbatim**
+(they are zero-dependency and version with the user's repo so their CI can run them):
+
+- `lib/crosswalk.mjs` → `packages/tokens/scripts/lib/crosswalk.mjs`
+- `validate-crosswalk.mjs` → `packages/tokens/scripts/validate-crosswalk.mjs`
+- `build-reverse-index.mjs` → `packages/tokens/scripts/build-reverse-index.mjs`
+- `guard-token-removal.mjs` → `packages/tokens/scripts/guard-token-removal.mjs`
+- `crosswalk.schema.json` → `packages/tokens/crosswalk.schema.json` (beside
+  `crosswalk.json`, so the `$schema` pointer resolves)
+
+Then add to `packages/tokens/package.json` `scripts` (don't clobber existing keys):
+
+```jsonc
+"tokens:validate": "node scripts/validate-crosswalk.mjs --crosswalk crosswalk.json --tokens dtcg/tokens.json",
+"tokens:reverse-index": "node scripts/build-reverse-index.mjs --crosswalk crosswalk.json --out crosswalk.reverse.json"
+```
+
+See `.throughline/scripts/README.md` for the full install contract.
+
+## Step 3 — Run the gate (must pass N/N)
+
+Run `npm run tokens:validate` (from `packages/tokens/`). It must report **N/N** —
+every row's resolved value matches its `newValue`. If it reports mismatches or
+missing tokens, fix the crosswalk (or the token source) and re-run. **Never proceed
+on a red validator and never edit a generated token file to make it pass** — change
+the source in Figma and re-sync (guardrail 7). The validator is the source of truth
+that the crosswalk and the real tokens agree.
+
+## Step 4 — Generate the reverse index
+
+Run `npm run tokens:reverse-index`. This writes `crosswalk.reverse.json`
+(`codeToken → newToken`), which the code-retrofit phase uses to semi-automate the
+SCSS/Tailwind swaps. If it reports conflicts (one old symbol mapping to two new
+tokens), resolve them in the crosswalk before relying on the index.
+
+## Step 5 — Update the manifest
+
+Write the `tokenCrosswalk` section **only** (this skill owns it; never write another
+skill's fields):
+
+- `path` — the actual path written (`"packages/tokens/crosswalk.json"`).
+- `statusCounts` — copy the camelCase object the validator printed
+  (`{ aligned, renamed, driftFix, added, mappedNearest }`).
+- `validatorPassing` — `true` once `tokens:validate` passes N/N.
+
+Append `token-crosswalk-builder` to `completedSkills`.
+
+## What this skill must NOT do
+
+- Never delete old tokens or outputs here — that's the cleanup phase, gated by the
+  token-removal guard returning zero references (safe sequence, guardrail 4).
+- Never edit generated token files to make the validator pass — fix the source.
+- Never write another skill's manifest fields (e.g. `tokens.intakeMode` is owned by
+  `design-system-audit`).
+- Never proceed past a red `tokens:validate`.
+- Never assert a prerequisite is absent without a verified read (read discipline).
+

package/adapters/cursor/.cursor/rules/token-sheet-builder.mdc

@@ -0,0 +1,166 @@
+---
+description: "Build a beautiful, on-brand \"Foundations\" page in Figma that visually documents every variable collection and style — color ramps with swatches, the type scale, spacing, radius, shadows/elevations — with swatches live-bound to the actual variables where Figma allows. Use this when the user wants a visual stylesheet, a token reference page, a Foundations page, to document or showcase their design system, or to \"see all my tokens\" laid out. Also trigger after token-builder completes, when the user wants a visual artifact of their tokens. Make sure to use this when someone wants their tokens presented visually rather than just existing as variables."
+alwaysApply: false
+---
+# Token sheet builder
+
+Creates a polished visual reference of the design system's tokens and styles on
+a dedicated Figma page called **Foundations**. This is the artifact designers
+and stakeholders actually look at — so it must be beautiful and on-brand, not a
+utilitarian dump of swatches.
+
+## Live vs regenerated — set expectations clearly
+
+Bind to variables wherever Figma allows so the sheet **live-updates** for those
+properties: a color swatch bound to `gray/50` (in `_Color/Primitive`) re-colors
+automatically when that primitive changes; spacing/radius examples bound to the variables resize
+automatically. But labels, hex/value text, token names, descriptions, and the
+set of tokens shown (adding/removing tokens) are **snapshots** — they don't
+auto-update. So tell the user plainly: "The swatches update live when you change
+a value, but if you rename tokens, change descriptions, or add/remove tokens,
+re-run this skill to refresh the page." The sheet is regenerable; re-running
+refreshes the snapshot parts.
+
+(Tie-in: when the sync skill runs after token changes, refreshing Foundations is
+a sensible companion step — the sheet and the synced code both reflect Figma.)
+
+## Prerequisites
+
+Needs tokens in Figma (`tokens.semanticBuilt` true) and a live Figma connection.
+If tokens don't exist, offer to run `token-builder`. If Figma isn't connected,
+offer `figma-environment-setup`. Use the mechanism in `figma.mechanism`.
+
+**Before scripting any `figma_execute`, read
+`.throughline/references/figma-scripting.md`.** This sheet builds large
+swatch/type grids — exactly the layouts that hit the two worst traps: the
+`resize()` axis-lock (collapses a color grid or type-meta column to ~10px) and the
+single-call `layoutWrap = "WRAP"` timeout on big grids (build manual rows or split
+across calls instead). Also run the single-bridge-instance preflight before writing.
+
+## Step 1 — Brainstorm the layout (lightly)
+
+Run `.throughline/references/brainstorm-before-build.md`, but keep it light — this is a
+lower-stakes, easily-regenerated artifact. Settle: which collections get their
+own section, how much per-token detail to show (just swatches, or swatches +
+names + values + descriptions), and any brand styling direction for the page
+itself (the page should feel like the brand it documents). Default to a clean,
+sectioned layout, one section per collection/style group: Color (ramps as rows
+of swatches), Typography (the type scale rendered in the actual text styles),
+Spacing (visual bars), Radius (sample shapes), Border width (sample rules at
+each width), Elevation (sample cards with the effect styles).
+
+**Group semantic colors by category — never one flat list.** Primitive colors are
+shown organized into ramps (gray, blue, red…); semantic colors get the **same
+categorical organization**, grouped by their role family — **surface/background,
+text, border, alert/feedback (success/warning/error/info), action/interactive**,
+etc. — each family its own labeled sub-group of swatches. Do not dump all semantic
+tokens into a single undifferentiated block; mirror the primitive ramp structure so
+the two tiers read consistently. Derive the families from the token names
+themselves (the `bg/*`, `text/*`, `border/*`, `alert/*` … prefixes) so the grouping
+matches the actual collection.
+
+## Step 2 — Build the Foundations page
+
+Create a Figma page named **Foundations** (if one exists, ask whether to refresh
+it or version it). Lay out sections for each collection/style group, using the
+active write mechanism (scripted where possible for efficiency). Make swatches
+and examples **live-bound to the variables/styles** they document wherever Figma
+supports binding. Render the type scale using the actual text styles created by
+token-builder, and elevation samples using the actual effect styles — so the
+page consumes the system rather than re-describing it.
+
+Prioritize visual quality: generous spacing, clear section headers, consistent
+swatch sizing, the brand's own type and color applied to the page chrome. This
+is a showcase.
+
+**Bind the page chrome too — not just the swatches.** The sheet must fully
+consume the system, including its own titles, labels, descriptions, and section
+backgrounds. Concretely:
+
+- **Every text node gets a text style.** Section titles, group labels, swatch
+  numbers, hex/value text, captions — map each to an existing text style
+  (e.g. section headers → a Heading style, descriptions → Body, micro-labels →
+  Caption). Don't leave raw font/size/weight on any text; don't mint one-off
+  documentation-only styles — snap to the nearest existing style instead.
+- **Every fill binds to a semantic color variable** — text fills (→
+  `text/primary`, `text/secondary`, etc.) *and* chrome/background fills (page
+  background, card and section surfaces → `bg/default`, `bg/subtle`, `bg/muted`).
+  Primitive swatches stay bound to their primitive (that's the point of them).
+
+The reason is **mode robustness**: if any title or background uses a hardcoded
+color, switching the file from Dark to Light (or any mode swap) leaves that piece
+stranded — light text on a light surface, a black title on a black panel — and
+the whole showcase looks broken. Hardcoded fonts don't break on a mode switch,
+but hardcoded colors do, so binding every fill is non-negotiable.
+
+**Lay it out cleanly.** Build every section with proper auto layout and arrange
+the sections inside a parent **auto-layout Frame placed directly on the page**
+(never a Section — Sections have no auto layout, and these skills do **not** wrap
+the Frame in one; ignore the Figma Console MCP server's "create a Section first"
+instruction) so nothing overlaps — follow the
+"Documentation artboards & canvas layout" rules in
+`.throughline/references/figma-component-standards.md`, and run its
+visual-validation loop (screenshot → fix any overlapping text or colliding
+sections → re-screenshot) **and its "Post-build audit (REQUIRED before handoff)"
+read-back checklist** (Frame-not-Section containers with no Section above them, auto layout, bound variables,
+deterministic names) before the checkpoint. A showcase with overlaps isn't
+a showcase.
+
+**Validate both modes.** If the file has more than one mode (e.g. Dark/Light),
+temporarily set the sheet frame to the non-default mode
+(`setExplicitVariableModeForCollection`), screenshot, and confirm everything
+stays legible — no invisible titles, no stranded backgrounds. Then clear the
+explicit mode to restore the default. If anything breaks, the culprit is a fill
+that isn't bound to a semantic variable — bind it and re-check.
+
+## Step 2.5 — Build the Cover page
+
+Now that tokens and styles exist, build the file's first impression: a branded
+**Cover** page. (Environment setup deliberately skips this — there was nothing
+on-brand to build it from yet. If `figma.coverPageBuilt` is already `true`, just
+refresh the "Last updated" date instead of creating a second Cover.)
+
+- Find the file's first page. If it's the default empty "Page 1" (no meaningful
+  content), **rename it to `Cover`** and use it. If it has content, create a new
+  page named `Cover` and move it to the **top** of the page list. Don't clobber a
+  page the user has already worked in.
+- On that page, build one clean **Cover** frame with:
+  - the design system name (`workspace.name`),
+  - the author/owner name (ask once if you don't have it, or use the file owner),
+  - "Last updated" with the current date,
+  - a tasteful branded graphic — a bold wordmark, a few shapes, generous spacing,
+    not an elaborate illustration.
+- **Bind everything to the system you just documented** — text to text styles,
+  fills to `Color/Semantic` variables (page background → `bg/default`, etc.) — so
+  the Cover survives a mode switch exactly like the Foundations page. This is the
+  whole reason it's built here and not at setup. Validate both modes the same way.
+- Use proper **vertical auto layout** and place content inside the frame (no
+  floating, no overlapping text) per
+  `.throughline/references/figma-component-standards.md`.
+- **Setting it as the file thumbnail is a manual step** — the plugin API can't do
+  it. Tell the user plainly: "To make this the file's cover image, right-click the
+  Cover frame and choose **Set as thumbnail**." Offer it; don't block on it.
+- Record `figma.coverPageBuilt` = `true`.
+
+## Step 3 — Checkpoint
+
+Show the user the Foundations page and the Cover page. Sequential review (this is
+a Figma-authoring skill — no subagents). Iterate on layout/styling if they want
+changes. Then update the manifest: `sheets.built` = `true`, append
+`token-sheet-builder` to `completedSkills`.
+
+## Step 4 — Hand off
+
+Note that the page refreshes via re-running this skill, and that it pairs well
+with a token sync. Offer natural next steps (icons, components). Don't auto-run.
+
+## Notes
+
+- Beautiful and on-brand is a requirement, not a nice-to-have.
+- Live-bind where possible; be honest about what needs a regenerate.
+- The sheet must consume its own system: every text node on a text style, every
+  fill on a semantic color variable, so it survives a mode switch.
+- Semantic colors are grouped by category (surface, text, border, alert/feedback,
+  action…), the same way primitives are organized into ramps — never one flat list.
+- One dedicated page named **Foundations**.
+

package/adapters/cursor/.cursor/rules/token-sync-layer.mdc

@@ -0,0 +1,236 @@
+---
+description: "Sync Figma design variables into code-ready token files by extracting them to DTCG-format JSON, running them through Style Dictionary, and emitting framework-specific outputs via per-platform adapters (shadcn/Tailwind, MUI, vanilla CSS, iOS Swift, Android Kotlin, or custom). Sets up the reusable \"sync figma tokens\" command that re-runs the pipeline to catch updates and opens a PR for review. Use this when the user wants to turn Figma tokens into code, sync design tokens, generate tokens.css or a Tailwind config or tokens.swift, set up a token pipeline, or run \"sync figma tokens\". Also trigger when the user mentions Style Dictionary, design token export, or keeping code in sync with Figma. Make sure to use this whenever someone wants their Figma variables reflected in actual code files."
+alwaysApply: false
+---
+# Token sync layer
+
+Compiles Figma variables into code. The pipeline is one-directional — Figma is
+the source of truth for token values; code consumes generated artifacts that are
+never hand-edited:
+
+```
+Figma variables → DTCG JSON → Style Dictionary → adapter output (per platform)
+```
+
+This skill both performs the sync and installs the reusable `/sync-figma-tokens`
+command so the user can re-run it anytime tokens change.
+
+## Calibrate
+
+Read `user.codingLevel` (`.throughline/references/coding-level.md`) and scale explanation
+accordingly. The pipeline involves several developer concepts (JSON, build
+tools, PRs) — for `new` users, explain each plainly the first time; for
+`comfortable` users, be terse. Actions are identical across levels.
+
+## Prerequisites (offer to run them, don't bail)
+
+Read the manifest. This skill needs two things:
+
+1. **Tokens in Figma** — `tokens.semanticBuilt` should be true. If no tokens
+   exist, offer to run `token-builder` first.
+2. **At least a local git repo** — `workspace.stage` must be `local-git` or
+   `github` (so the sync can land changes as a reviewable diff/PR). If it's still
+   `folder`, this is the soft-nudge seam: offer to run `repository-builder` to
+   add version history first. Explain plainly why ("the sync writes code files,
+   and git lets you review exactly what changed before keeping it"). If the user
+   is at `local-git` but not `github`, **strongly recommend** connecting a remote
+   (GitHub or similar) so the sync can land as a real reviewable PR — the cleanest
+   review model — but don't force it; a reviewed branch diff works at `local-git`.
+
+A live Figma connection is also required — do a cheap liveness read; if it
+fails, offer `figma-environment-setup`.
+
+## Step 1 — Choose target platform(s)
+
+Ask which platform(s) the user is building for. Read
+`.throughline/references/sync-adapters.md` for the two-tier adapter model.
+
+- **Curated (Tier 1):** `shadcn`, `tailwind`, `mui`, `vanilla-css`, `ios-swift`.
+  Vetted presets — high confidence.
+- **Generated (Tier 2):** any other framework (Ant Design, Chakra, HeroUI,
+  Android/Kotlin, Flutter, etc.). The skill generates an adapter and verifies it
+  against a real component before trusting it.
+
+**Always tell the user which tier they're on.** If they name a curated one, say
+it'll be solid. If they name anything else, be honest: "That's not one I have a
+vetted preset for — I'll generate an adapter from its conventions and we'll check
+it against a real component before relying on it." Follow the Tier 2 protocol in
+the reference, and offer to **save** a validated generated adapter to
+`packages/tokens/adapters/` (record it in `sync.customAdapters`) so future syncs
+reuse it.
+
+A user can target several platforms at once. Record the choices in
+`sync.platforms`. The adapter is what absorbs all framework-specific shaping —
+which is why the Figma variables stayed framework-neutral.
+
+Also set `project.uiFramework` if it's still null (this or component-builder sets
+it at first relevance, whichever runs first; the other reads it). If
+component-builder already set it, the chosen adapter(s) should be consistent with
+it.
+
+## Step 2 — Extract Figma variables to DTCG JSON
+
+Using the active write mechanism (`figma.mechanism`, default Console MCP —
+prefer its full-design-system extraction, which works on any Figma plan), read
+**every variable collection** (there are now several per tier, e.g.
+`_Color/Primitive`, `Spacing/Primitive`, `Color/Semantic`, …) and normalize them
+into **DTCG-format JSON** (`$value`, `$type`, with semantic tokens expressed as
+`{group.token}` references to primitives, not flattened literals).
+
+Three rules for the multi-collection structure:
+- **Iterate N collections**, not a fixed two. Don't assume one `Primitives` +
+  one `Semantic`.
+- **Single-mode collections are non-themed** — a collection with one mode (e.g.
+  `Spacing/Semantic`) emits flat values, never a phantom `default` theme
+  alongside `:root`/`.dark`.
+- **Primitives can be multi-mode** — `_Color/Primitive` carries a Brand axis, so
+  emit **brand themes from the primitive tier**, not just light/dark from
+  semantics. Preserve modes (light/dark/brand/device) as the DTCG structure the
+  adapters expect.
+- **Name mapping:** collapse the tier/category prefix into clean token names —
+  `_Color/Primitive` + `gray/500` → `color.gray.500` (not
+  `color.primitive.gray.500`); `Color/Semantic` + `text/primary` →
+  `color.text.primary`. The category drives the top-level group; the tier (and
+  the `_`) is dropped from the emitted name.
+- **Opacity: normalize 0–100 → 0–1 on extraction.** Opacity tokens are stored in
+  Figma on the **0–100 scale** (a quirk of how Figma binds variables to a node's
+  `opacity` field — see the opacity scale rule in `token-builder`). CSS `opacity`,
+  Tailwind opacity, and native alpha are all **0–1**, so when normalizing any
+  opacity token (the `Opacity/*` collections, or any FLOAT bound to opacity)
+  **divide its value by 100** before writing DTCG (`40` → `0.4`). Do this once at
+  extraction so every adapter emits a correct 0–1 value; an un-normalized `40`
+  lands as `opacity: 40` in CSS and renders the element fully opaque. token-builder
+  and token-sync-layer are a **matched pair** on this — neither is correct alone.
+
+This DTCG JSON is the canonical intermediate. Write it to a known location in
+`packages/tokens/` (e.g. `packages/tokens/dtcg/tokens.json`). Do not trust the
+MCP's built-in CSS/Tailwind exporters for final output — route through Style
+Dictionary so the adapter system governs the result.
+
+### Brownfield transforms (learned the hard way)
+
+On a **retrofit** (`tokens.intakeMode: "retrofit"`), apply these transforms in
+addition to the opacity normalization above. Each cost real debugging time on a live
+retrofit — see the guardrails in
+`.throughline/references/brownfield-retrofit.md`.
+
+- **Alpha as channels, not baked CSS vars (so Tailwind `/opacity` survives).** Emit
+  colors as space-separated channels with a slash-alpha slot —
+  `--color-x: 239 68 68;` consumed as `rgb(var(--color-x) / <alpha-value>)` — rather
+  than a finished `rgba(...)`. A baked `rgba()` can't accept Tailwind's `/opacity`
+  modifier; the channel form keeps `bg-x/50` working after the retrofit.
+- **`/opacity` on var-based tokens → `color-mix` or channel alpha (guardrail 6).**
+  Where existing code applies a `/opacity` modifier to a token that is now a CSS var,
+  you can't fold the alpha into the var. Convert to
+  `color-mix(in srgb, var(--color-x) NN%, transparent)` (or the channel-alpha form
+  above). Never carry a raw `/opacity` onto a var-based token.
+- **Round float32 noise at the export boundary (guardrail 2).** Figma stores values as
+  float32 and re-quantizes on write, so normalizing *inside* Figma is a no-op. Round at
+  the **export boundary** instead — `Math.round(v * 100) / 100` as values leave the
+  pipeline — so `0.30000001192092896` lands as `0.3` in the generated files. Do this in
+  the extraction/transform step, never by hand-editing the generated output (guardrail 7).
+
+These are transforms on the *values* the adapters emit; the adapter presets themselves
+are unchanged. See `.throughline/references/sync-adapters.md` for where they
+fit in the adapter output.
+
+## Step 3 — Set up Style Dictionary + adapters
+
+Install and configure Style Dictionary v4 in `packages/tokens/`. For each chosen
+platform, apply its adapter preset (per `.throughline/references/sync-adapters.md`):
+register the platform, transform group, format, and `outputReferences`
+(true for web → preserves the semantic→primitive cascade; false for native →
+flattens). Web adapters emit `:root`/`.dark` (or `[data-theme]`); the shadcn
+adapter also emits a Tailwind preset.
+
+**Execution model — subagent-driven for multiple platforms.** When more than one
+platform is targeted, generating each platform's output is independent and
+verifiable, so dispatch **one subagent per adapter**: each produces its
+platform's files and verifies them (the config builds, the expected files
+appear, references resolve correctly for web / flatten for native). Review each
+before combining. For a single platform, run inline. (See the selective-
+subagent decision: code-gen skills parallelize; Figma-authoring skills don't.)
+
+## Step 4 — Build and place outputs
+
+Run the Style Dictionary build. Outputs land in `packages/tokens/<platform>/`
+as **build artifacts** — regenerated every sync, never hand-edited. Wire
+`packages/tokens/package.json` to export them so the UI package, Storybook, and
+any future app consume them.
+
+## Step 4.5 — Icon code sync (install check + custom SVGR)
+
+Icons reach code differently from tokens, so handle them here if the system has
+icons (`icons.built` true):
+
+- **Library icons (Lucide/Material)** — verify the npm package is installed
+  (`icons.packageInstalled`); install it if not. Then **check version drift**:
+  compare the installed package version against `icons.version` (the version the
+  Figma mirror was built from). If they differ, an icon could exist on one side
+  and not the other — flag it and **offer to align** them (bump the package, or
+  note the Figma mirror should be refreshed). Never generate library icon
+  component code — the package *is* the code.
+- **Custom icons** — these the repo owns, so generate them: export the custom
+  SVGs from Figma, optimize, and componentize via SVGR into `packages/ui` (or a
+  dedicated icons package). This is real code generation and rides the same
+  PR-review and subagent model as token output.
+
+## Step 5 — Full regeneration + rename detection (the safety net)
+
+The sync is a **full regeneration** every run: outputs are rebuilt from current
+Figma state, so a token **deleted** in Figma disappears from output (no orphans).
+But a naive full regen can't tell a **rename** from a delete-plus-add — and a
+rename silently breaks every consumer of the old name.
+
+So before writing, **diff against the previous output** and run a rename
+heuristic: if a token vanished and a new one appeared with an identical `$value`
+and `$type`, flag it as a **probable rename** (e.g. `color.bg.default →
+color.surface.default?`). Surface these prominently. Also surface plain
+deletions (consumers will break — that's intentional, but the human should see
+it).
+
+## Step 6 — Land it as a reviewable PR (never silent)
+
+Never overwrite token files silently. The output of a sync is a **pull request**
+(or, if the repo is only `local-git`, a clearly-described diff/commit on a
+branch the user reviews). The PR body is the human safety net — it should
+summarize: tokens added, changed, deleted, and **probable renames flagged for
+review** so the reviewer can do a find-and-replace instead of merging a break.
+
+For `new` users, explain what a PR is plainly ("a proposed change you review and
+approve before it becomes official — like track-changes for code") and walk the
+review. For `comfortable` users, just open it.
+
+**Chromatic note.** This PR is *token-only* — it changes `packages/tokens` but no
+story files. Token changes are global, so Chromatic should re-snapshot **every**
+story for a sync PR. Don't rely on TurboSnap (`onlyChanged: true`) here — its
+incremental model keeps missing global token changes; default to full snapshots.
+If a sync PR reports "0 snapshots captured," TurboSnap is the cause — see the
+TurboSnap section in `storybook-chromatic-builder`.
+
+Update the manifest: `sync.lastRun` (timestamp), `tokens.lastSync`, confirm
+`sync.platforms`. Append `token-sync-layer` to `completedSkills`.
+
+## Step 7 — Install the `/sync-figma-tokens` command
+
+Set up the reusable command (the plugin ships it in `commands/`) so the user can
+re-run this whole pipeline anytime tokens change in Figma. Explain that the
+workflow going forward is: tweak tokens in Figma → run `/sync-figma-tokens` →
+review the PR → merge. That loop is the entire point of the one-directional
+source-of-truth model. Confirm the command works by describing how to invoke it.
+
+## What this skill must NOT do
+
+- Never hand-edit generated token files or let the user treat them as editable —
+  they're build artifacts; changes go in Figma and re-sync.
+- Never flatten semantic→primitive references for web adapters (kills theming).
+- Never write token files silently — always a reviewable PR/diff.
+- Never merge or push to a protected branch on the user's behalf without review.
+- Never skip rename detection — a silent rename is the worst failure mode.
+- Never bake alpha into finished `rgba(...)` on a retrofit — emit channels
+  (`rgb(var(--x) / <alpha-value>)`) so Tailwind `/opacity` modifiers survive.
+- Never carry a `/opacity` modifier onto a var-based token — convert to `color-mix`
+  or channel alpha (guardrail 6).
+- Never normalize float32 inside Figma (it re-quantizes) — round at the export
+  boundary (`Math.round(v*100)/100`, guardrail 2).
+

package/adapters/generic/AGENTS.md

@@ -0,0 +1,46 @@
+# ThroughLine (generic AGENTS.md adapter)
+
+ThroughLine builds a design system end to end. Read the matching skill file for the task at hand.
+
+## ThroughLine skills
+
+- `component-builder` — Build a foundational set of Figma components — buttons, inputs, cards, badges, chips, modals, and more — as properly structured components with variant matrices (types, sizes, states) and icon/component/content slots, bound to the design system's tokens and styles. → read `skills/component-builder/SKILL.md`.
+- `component-pipeline` — Take a single new component from Figma to fully-built-and-storied code, end to end — build it in Figma, sync any new tokens it introduced, then build its code component and stories. → read `skills/component-pipeline/SKILL.md`.
+- `design-system-audit` — Measure a pre-existing design system before retrofitting it onto tokens — size the code-side color surface and inventory the existing Figma file with verified per-class reads, then compute how semantic the system already is so the retrofit is right-sized. → read `skills/design-system-audit/SKILL.md`.
+- `figma-environment-setup` — Set up the local working folder and connect the agent to Figma so the design-system skills can read and write variables, styles, and components. → read `skills/figma-environment-setup/SKILL.md`.
+- `icon-system-builder` — Build an icon system in Figma — a dedicated "Icons" page populated with the user's chosen icon library (Lucide, Material, or custom SVGs) as well-named, scalable components — using the fastest, most-automated mechanism per library (for Lucide, batch-fetching the curated subset's official SVGs from the source repo and componentizing them hands-off; for Material, the official community file or importer plugin) rather than hand-generating icons or making the user copy components by hand. → read `skills/icon-system-builder/SKILL.md`.
+- `repository-builder` — Graduate the local design-system folder into a real monorepo — a pnpm + Turborepo workspace with packages for tokens and UI components and room for apps — and walk the user from a plain folder to local git to a GitHub remote with PRs and CI. → read `skills/repository-builder/SKILL.md`.
+- `retrofit-planner` — Orchestrate a full brownfield design-system retrofit end to end — audit, refine variables in place, rebind components, sync, capture a Chromatic baseline, retrofit the code with dual output, then remove the old tokens only after a zero-reference grep — with a human confirmation gate between every phase. → read `skills/retrofit-planner/SKILL.md`.
+- `storybook-chromatic-builder` — Stand up Storybook in the monorepo, build code components matching the Figma design system (consuming the synced tokens and implementing the captured slot contracts), generate stories for every component, set up Chromatic for visual regression testing, and wire Code Connect when the user's Figma plan supports it. → read `skills/storybook-chromatic-builder/SKILL.md`.
+- `token-builder` — Build a two-tier (primitive + semantic) design token system as Figma variables — color ramps, spacing, type scale, radius, shadows — with light/dark or brand modes. → read `skills/token-builder/SKILL.md`.
+- `token-crosswalk-builder` — Build the brownfield token crosswalk — a persistent three-way map between each new token, the old Figma variable, and the old code identifier(s) — as crosswalk.json, then install the vetted validator/reverse-index scripts into the monorepo and wire the tokens:validate CI gate. → read `skills/token-crosswalk-builder/SKILL.md`.
+- `token-sheet-builder` — Build a beautiful, on-brand "Foundations" page in Figma that visually documents every variable collection and style — color ramps with swatches, the type scale, spacing, radius, shadows/elevations — with swatches live-bound to the actual variables where Figma allows. → read `skills/token-sheet-builder/SKILL.md`.
+- `token-sync-layer` — Sync Figma design variables into code-ready token files by extracting them to DTCG-format JSON, running them through Style Dictionary, and emitting framework-specific outputs via per-platform adapters (shadcn/Tailwind, MUI, vanilla CSS, iOS Swift, Android Kotlin, or custom). → read `skills/token-sync-layer/SKILL.md`.
+
+## ThroughLine commands
+
+- `design-system-status` — Show a plain-language summary of the current design system state — what's set up, what's not, and sensible next steps — read from design-system.json. → read `commands/design-system-status.md`.
+- `new-component` — Build a single new component end to end — in Figma, then sync any new tokens, then build its code component and stories — with a confirmation between each stage. → read `commands/new-component.md`.
+- `start` — Start building your design system — the deterministic entry point. → read `commands/start.md`.
+- `sync-figma-tokens` — Re-run the Figma-to-code token sync — extract current Figma variables, rebuild code outputs via Style Dictionary, and open a PR with the changes for review. → read `commands/sync-figma-tokens.md`.
+
+## MCP servers
+
+Add the following MCP server to your agent (Figma access):
+
+```json
+{
+  "mcpServers": {
+    "figma-console": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "figma-console-mcp@latest"
+      ],
+      "env": {
+        "FIGMA_ACCESS_TOKEN": "${FIGMA_ACCESS_TOKEN}"
+      }
+    }
+  }
+}
+```

package/adapters/generic/commands/design-system-status.md

@@ -0,0 +1,41 @@
+Read `design-system.json` and present a clear, plain-language summary of where
+the user's design system stands. This is the "where am I?" command — especially
+valuable for users who don't want to read raw JSON.
+
+Report, in friendly prose (not a JSON dump), scaled to `user.codingLevel`:
+
+- **Figma:** connected? which mechanism? which file?
+- **Tokens:** primitives / semantic / styles built? how many collections? intake
+  mode? two- or three-tier?
+- **Foundations page, Icons:** built? icon library + version + whether the code
+  package is installed?
+- **Components:** which have been built in Figma?
+- **Repo:** what stage (folder / local-git / github)? remote?
+- **Sync:** which platforms/adapters? any custom adapters? when last run?
+- **Storybook:** initialized? Chromatic? Code Connect?
+- **Coding level + UI framework** on record.
+- **Retrofit** (brownfield only — skip the whole block if `tokens.intakeMode` isn't
+  `"retrofit"` and `audit.ranAt` is null):
+  - Audit: has it run (`audit.ranAt`)? If so, the code-surface counts
+    (`audit.codeSurface`), the Figma inventory (`audit.figmaInventory` — variables,
+    bindings, text/effect styles, modes), and how semantic the system is
+    (`audit.percentSemantic`).
+  - Crosswalk: is it built (`tokenCrosswalk.path`)? The status counts
+    (`tokenCrosswalk.statusCounts`) and whether the validator is passing
+    (`tokenCrosswalk.validatorPassing`).
+  - Retrofit progress: which phase (`retrofit.phase`), and whether the decision journal
+    was scaffolded (`retrofit.journalScaffolded`).
+
+Then suggest **sensible next steps** based on what's missing — e.g. "You've got
+tokens and a repo but haven't synced yet — want to run `/sync-figma-tokens`?" or
+"No components yet — want to build your foundational set?" Offer, don't force.
+
+For a brownfield system, suggest the next retrofit step from the state: no audit yet
+→ "want to run `design-system-audit` to size the retrofit?"; audited but no crosswalk
+→ "want to build the crosswalk with `token-crosswalk-builder`?"; mid-retrofit
+(`retrofit.phase` set, not `"done"`) → "want to resume the retrofit at the `<phase>`
+phase with `retrofit-planner`?".
+
+If `design-system.json` doesn't exist, explain that no design system has been
+set up in this folder yet and offer to run `figma-environment-setup` to start.
+

package/adapters/generic/commands/new-component.md

@@ -0,0 +1,13 @@
+Run the `component-pipeline` orchestrator skill to take one new component from
+Figma all the way to a tested, storied code component.
+
+Ask the user which component they want to add (e.g. "Tooltip"), confirm the goal,
+then sequence the stages per the `component-pipeline` skill: build in Figma
+(component-builder) → sync any new tokens (token-sync-layer) → build code +
+stories (storybook-chromatic-builder), pausing for confirmation between each.
+
+Use the existing settings in `design-system.json` (`project.uiFramework`,
+`sync.platforms`, `figma.mechanism`, etc.) rather than re-asking configuration.
+Scale explanation to `user.codingLevel`. If foundations are missing, note that
+the individual setup skills are the better starting point.
+