@radicool/throughline 0.12.0

package/adapters/generic/skills/token-crosswalk-builder/SKILL.md

@@ -0,0 +1,120 @@
+# 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/generic/skills/token-sheet-builder/SKILL.md

@@ -0,0 +1,162 @@
+# 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/generic/skills/token-sync-layer/SKILL.md

@@ -0,0 +1,232 @@
+# 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/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@radicool/throughline",
+  "version": "0.12.0",
+  "description": "Build a complete design system end to end — author in Figma, sync tokens to code, generate Storybook. Usable from Claude Code, Cursor, Codex, or any AGENTS.md agent.",
+  "type": "module",
+  "bin": {
+    "throughline": "scripts/install.mjs"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "adapters/",
+    "references/",
+    "scripts/",
+    "!scripts/**/*.test.mjs",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT",
+  "author": "Jordan Pease",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jrpease/throughline.git"
+  }
+}