@radicool/throughline 0.12.0

package/references/brainstorm-before-build.md

@@ -0,0 +1,139 @@
+# Brainstorm before build
+
+A shared protocol that every Figma **authoring** skill (token-builder,
+token-sheet-builder, icon-system-builder, component-builder) runs *before*
+generating anything in Figma. Its job is to lock the spec with the user while
+changes are still free — i.e. in conversation, not in the Figma file after
+tokens have been burned creating the wrong thing.
+
+This is distinct from the checkpoint gates that come *after* generation
+("here's what I built, approve it?"). Brainstorming happens *before*: "what are
+we even building?" For a design-fluent, code-unsure user, this is where their
+expertise drives the machine — they can't read the generation script, but they
+can absolutely answer "should buttons have a loading state?"
+
+## The protocol
+
+1. **Don't jump to generating.** When the user asks for something ("build my
+   tokens", "make a button"), resist producing Figma output immediately. First
+   surface the decisions that shape it.
+
+2. **Ask in small, readable chunks.** Present choices a few at a time, in plain
+   language, with a recommended default for each so the user has something to
+   react to rather than a blank page. Prefer concrete either/or framings over
+   open questions. Use the question-asking UI (tappable options) when available
+   — it's much easier for the user than typing.
+
+3. **Show the proposed spec back before building.** Once decisions are made,
+   restate the full spec in a short, digestible form the user can sign off on:
+   "Here's what I'll create: [the spec]. Good to go?" This is the gate between
+   brainstorm and generation.
+
+4. **Only then generate.** After explicit sign-off, proceed to the skill's
+   generation step (and its own post-generation checkpoints).
+
+## Intake mode (token-builder runs this FIRST)
+
+Before brainstorming structure, the token-builder must establish **which
+starting point the user is at**, because the three modes are genuinely different
+behaviors. Ask this first, route accordingly:
+
+- **Generative** — the user gives a seed (e.g. one brand color, one font) and
+  wants AI to expand it into a full system: a complete tonal ramp from the brand
+  color, supporting/semantic color families (success/warning/danger derived to
+  harmonize), complementary font pairings, and full spacing/type/radius scales.
+  Here you generate the most; confirm the seed and the aesthetic direction, then
+  propose the expanded system for sign-off.
+- **Descriptive** — the user gives aesthetic direction (words like simple,
+  rounded, modern, dense, comfortable) and/or a reference image/URL, but not
+  exact values. Derive concrete scales and ramps from the description, mapping
+  adjectives to decisions (e.g. "rounded" → larger radius scale, "dense" →
+  tighter spacing base). Propose values back for sign-off.
+- **Import** — the user already has a token set (a JSON file, a list, an
+  existing system, or source like a marketing site + brand guide) and wants it
+  ingested and organized into the per-category Figma structure. Import has **two
+  distinct responsibilities — keep them separate so they don't fight each other**:
+  *(1)* preserve and organize what they gave, and *(2)* run a completeness pass
+  that recommends what a fuller system adds. Preserve their actual values and
+  names exactly — never overwrite or silently invent values **in place**. But do
+  not stop at a 1:1 transcription: a brand guide or website is almost always a
+  *partial* system (a few brand colors, two fonts, ad-hoc paddings), so a faithful
+  import alone produces a thin, rigid token set. The completeness pass below is
+  what turns it into a flexible one.
+
+  **Completeness pass (gap analysis — the high-value step).** After organizing,
+  diff what they gave against the reference model of a full, flexible system (the
+  checklist below). Then **proactively propose the missing pieces, derived from
+  their existing values so they harmonize** — e.g. extend a single brand color
+  into a full 50–900 tonal ramp, add a neutral/gray ramp, derive success/warning/
+  danger/info families tuned to their palette, add dark-mode values, an elevation/
+  shadow scale, a radius scale, and the semantic role layer (bg/surface/text/
+  border roles). This is **preserve-first and opt-in**, which is how it coexists
+  with "don't invent values": you are not overwriting their brand or inventing
+  silently — you surface a derived, clearly-labeled upgrade menu and let them
+  choose. Present it grouped by category: *"Here's what you have (kept as-is).
+  Here's what a fuller system adds, and what I'd derive for each — accept all, pick
+  some, or skip."* Nothing recommended is created until the user accepts. Keep it
+  proportional (see "Keep it proportional" below): lead with the high-impact gaps
+  (tonal ramps, neutral ramp, state colors, dark mode, semantic roles), offer the
+  rest lightly.
+
+  **What a full, flexible system includes (the reference model to diff against):**
+  - **Color** — a neutral/gray ramp (~10 steps); each brand/accent as a full
+    tonal ramp (50–900), not just its base; state families (success, warning,
+    danger, info) as ramps; a semantic role layer (bg/surface layers, text
+    hierarchy: primary/secondary/muted/disabled, border/divider, interactive
+    states: hover/active/focus/selected/disabled); **dark mode** values.
+  - **Typography** — a full size ramp with line-heights, weights, and
+    letter-spacing; semantic roles (display, heading h1–h6, body, label, caption,
+    code); responsive (Desktop/Mobile) sizing where relevant.
+  - **Spacing** — a consistent base-unit scale (replacing ad-hoc one-off
+    paddings), spanning tight insets up to large layout steps.
+  - **Radius / border-width / elevation(shadow)** — each a real scale
+    (none→full, hairline→thick, sm→xl) rather than one hardcoded value;
+    elevation should be dark-mode-aware.
+  - **Often-absent optional layers** — opacity scale, z-index/layer tokens,
+    motion (duration + easing). Mention these exist; don't force them.
+  - **Modes** — note which axes are missing (dark mode, density, brand) since
+    a partial import usually has none.
+
+  **Organize into per-category collections.** While ingesting, map their values
+  onto the structural-consistency model (see token-builder Step 1): one
+  primitive and one semantic collection per category, split so each category owns
+  its own mode axis. Passthrough dimensional semantics (e.g. border-width
+  semantics that alias a single primitive) are **expected and kept** — they exist
+  to carry a future mode axis — so do not collapse them. The only thing to flag
+  is a genuine naming problem: a "semantic" token that's just a renamed primitive
+  step with no real role (`space-12` rather than `inset/md`). Surface those:
+  "A few of your semantic names mirror primitive steps rather than naming a role
+  — want me to rename them to usage roles, or keep them as-is?" Let the user
+  choose. Keep structure; fix only fake roles.
+
+Many users are a blend (e.g. "here's my 2 brand colors and a font, fill in the
+rest" is generative with seeds). Identify the dominant mode, confirm it, and
+proceed. The rest of the token brainstorm (below) then runs within that mode.
+
+## What each skill brainstorms
+
+- **token-builder** — after intake mode, the structure of the scales: which
+  color ramps and how many steps, the spacing scale, the type scale,
+  radius/border/shadow scales, and which modes exist (light/dark, brand
+  variants, density). Critically, the primitive naming convention, since the
+  semantic tier aliases onto it. Also: whether a third (component) tier is
+  warranted — default two-tier; only raise three-tier if the user signals
+  multi-brand, white-labeling, or a very large component library.
+- **token-sheet-builder** — layout and grouping of the visual stylesheets; which
+  collections get their own artboard; how much per-token detail to show.
+- **icon-system-builder** — which icon library (lucide / material / custom),
+  which subset of icons, the naming convention, and sizing/grid conventions.
+- **component-builder** — the variant matrix for each component: types, sizes,
+  states (hover/focus/disabled/loading), icon slots, and which tokens each
+  variant binds to.
+
+## Keep it proportional
+
+Brainstorming should be thorough for high-impact, hard-to-undo decisions (the
+primitive naming convention, the mode structure) and light for low-stakes ones.
+Don't interrogate the user about trivia — the goal is to prevent expensive
+regeneration, not to slow them down. If a decision is cheap to change later, note
+the default and move on.

package/references/brownfield-retrofit.md

@@ -0,0 +1,93 @@
+# Brownfield retrofit — read discipline, guardrails, safe sequence
+
+Canonical reference for retrofitting a design system onto a **mature codebase and
+an already-populated Figma file** (the brownfield path), as opposed to building
+greenfield. Read this before running `design-system-audit`, `token-crosswalk-builder`,
+`retrofit-planner`, or any brownfield branch of `token-builder`, `token-sync-layer`,
+or `storybook-chromatic-builder`.
+
+## The read-discipline principle (fixes bugs B1–B4)
+
+**Never assert that something is absent, empty, unpublished, or stale without an
+explicit, completed read that returned that result.** "I didn't find X" must mean
+"I queried for X and the result was empty (after the file and all pages fully
+loaded)," never "I assumed X from Y." When a result is genuinely undetectable, ask
+the user once and persist the answer in the manifest — never guess.
+
+Concrete applications:
+
+- **Variables (B1).** Before counting variables, `await figma.loadAllPagesAsync()`.
+  Treat a `0` count on a first read as suspect — re-read before reporting. An
+  unexpectedly-empty result is a possible read/cache error, not ground truth. Prefer
+  the dedicated `figma_get_variables` tool over a hand-written probe.
+- **Styles vs. variables (B2).** Text styles, effect/paint styles, and variables are
+  **different surfaces**. Absence of variables says nothing about styles. Query each
+  independently — variables (`figma_get_variables`), text styles
+  (`figma_get_text_styles`), effect/paint styles (`figma_get_styles`) — and only
+  report "none" for the specific class whose own read returned empty.
+- **Publish state (B3).** Treat a default/`false` `figma.libraryPublished` as
+  _unverified_. Attempt detection first (`figma_get_library_components` /
+  `figma_get_library_variables`, library component keys). If inconclusive, ask once
+  ("Is this library published to a team library?") and persist to
+  `figma.libraryPublished` / `figma.canPublish`. Frame the unpublished path as a
+  graceful choice, not a failure.
+- **Bridge ports (B4).** Distinguish *live* concurrent bridge instances from
+  *dead/stale* entries. Only block on genuinely live ones; reap or offer one-click
+  cleanup for stale ones. See the bridge-instance preflight in
+  `${CLAUDE_PLUGIN_ROOT}/references/figma-scripting.md`.
+
+## The 7 guardrails (hard "DON'T" rules)
+
+Each cost real debugging time on a live retrofit. Treat each as a hard rule.
+
+1. **Don't bind line-height / letter-spacing variables to text styles.** Figma stores
+   them as PERCENT; a unitless ratio var (`1.6`) rebinds as `1.6px` — catastrophic.
+   **Font-size binding only** (px→px is safe).
+2. **Don't normalize float32 in Figma** — it is a no-op (Figma re-quantizes to float32
+   on store). Normalize at the export boundary instead (`Math.round(v*100)/100`).
+3. **Don't delete-and-recreate variables to rename** — it unbinds everything. Rename
+   in place to preserve Figma IDs (and therefore every existing binding).
+4. **Don't trust `tsc` / build to catch Tailwind color-utility removal** — deleted
+   utilities become *silent no-ops*. Guard repo-wide across all `.tsx`/`.ts` files
+   except generated and test files, and let Chromatic be the net.
+5. **Don't assume `build-storybook` exercises all SCSS** — story-unreachable modules
+   (and a dead `@import` of a deleted partial) only fail when the real app renders.
+   Run the app and spot-check 5–7 routes before declaring an SCSS change done.
+6. **Don't carry `/opacity` modifiers onto var-based tokens** — convert to
+   `color-mix(in srgb, var(--…) NN%, transparent)` or channel-based alpha.
+7. **Don't hand-edit generated files** — change the source and re-run `tokens:sync`.
+
+## The safe retrofit sequence
+
+Run these phases in order; `retrofit-planner` gates each one with a human
+confirmation. The ordering rules are not arbitrary — each prevents a specific class
+of damage.
+
+1. **audit** — measure both sides (`design-system-audit`). Size the code surface and
+   inventory the Figma file with verified per-class reads. Compute `percentSemantic`
+   (manifest `audit.percentSemantic`): a system that is already largely semantic is a
+   **rename-in-place + cleanup** job; a low-semantic one is closer to a **rewrite**.
+   The higher the percentage, the lighter the retrofit — let it right-size the effort.
+2. **refine** — rename/realign variables **in place** (`token-builder` brownfield
+   branch). Never delete-and-recreate (guardrail 3); run a binding-survival audit.
+3. **rebind** — reconcile components onto the refined variables, preserving IDs. No
+   dedicated tool — the `retrofit-planner` orchestrator drives this step directly.
+4. **sync** — run the sync layer with the brownfield transforms (alpha channels,
+   opacity 0–100→0–1, float32 rounding at the export boundary).
+5. **baseline** — capture a Chromatic baseline **before** any code retrofit, so
+   intended drift-fixes are distinguishable from regressions.
+6. **code** — retrofit the codebase with **dual output**: new and old tokens coexist
+   during the transition.
+7. **cleanup** — remove old outputs **only** after a zero-reference grep passes (the
+   repo-wide token-removal guard).
+
+## The verification triad
+
+No single check catches everything; all three are necessary on every retrofit:
+
+1. **`check-types`** (TypeScript) — blind to Tailwind silent no-ops.
+2. **`build-storybook` + Chromatic snapshots** — the visual-regression net; blind to
+   story-unreachable code. **Chromatic, not `tsc`/build, is the source of truth** for
+   color-utility removal.
+3. **Run the actual app** + spot-check real routes — the only thing that exercises
+   story-unreachable SCSS.

package/references/coding-level.md

@@ -0,0 +1,70 @@
+# Coding level — calibrating how much to explain
+
+The user has a `user.codingLevel` recorded in the manifest. It governs **how
+much code/git/terminal concepts are explained** in the code-touching skills
+(repository-builder, token-sync-layer, storybook-chromatic-builder, and the
+orchestrator). It is set once in `figma-environment-setup` (skill 0) and can be
+changed anytime the user asks.
+
+## Critical principle: level changes EXPLANATION, never CAPABILITY
+
+A `new` user and a `comfortable` user get the **exact same repo, the exact same
+secrets setup, the exact same outputs.** The only thing that changes is how much
+the skill narrates concepts along the way. Never give a beginner a lesser
+system; never withhold a step. Same destination, different amount of teaching.
+
+The **hard safety rules never scale** with level. Regardless of level:
+- A secret value (token, key, password) never passes through the chat.
+- Secrets never get committed to code; env files holding them are gitignored.
+- Claude never enters credentials into web forms or creates secrets on the
+  user's behalf — it tells the user exactly where to put them.
+
+Only the *explanation* of these rules scales, not the rules themselves.
+
+## The three levels
+
+- **`new`** — has never set up a GitHub repo, made an env file, or used a
+  terminal much. **Default if unsure.** Explain every concept the first time it
+  appears, in one plain sentence: what a repo is, what an env file is, why
+  secrets are gitignored, what a "secrets vault" / GitHub Actions secret is.
+  Give exact click paths for anything outside the chat. Verify each step worked
+  before moving on (e.g. confirm CI went green after they add a secret). Be warm
+  and patient; assume zero terminal fluency beyond what you walk them through.
+
+- **`some`** — has used git/GitHub and run commands, but isn't an expert. Brief
+  reminders, not full lessons. Skip "what is a token" but still confirm the
+  specific click path or command, and still verify the important steps. Assume
+  they can run a command you give them without hand-holding, but don't assume
+  they remember exactly where GitHub's secrets settings live.
+
+- **`comfortable`** — fluent with git, env files, CI, and secrets. Terse and
+  direct. Name the action and move on: "Scaffold pnpm+Turborepo, add
+  `.env.example`, gitignore `.env`. Put `CHROMATIC_PROJECT_TOKEN` in `.env` and
+  as a repo Actions secret." No concept-teaching, no click paths unless asked.
+  Assume terminal fluency.
+
+## How to determine the level (skill 0)
+
+Don't ask "are you technical?" — self-assessment is unreliable and people
+over- or under-claim. Anchor to **concrete, recognizable experiences** and infer
+the level from the answers:
+
+- "Have you set up a GitHub repository before?"
+- "Have you used a command line / terminal before?"
+- "Have you worked with environment variables or `.env` files?"
+
+Map roughly: no to most → `new`; yes to some, hesitant on others → `some`; yes
+and casual about all → `comfortable`. Confirm the inferred level in plain terms
+("Sounds like you're comfortable with the code side — I'll keep things brief and
+skip the basics. Tell me if you want more detail anytime.") and record it.
+
+When in doubt, choose the **lower** level — over-explaining is recoverable
+(the user says "you can skip that"), under-explaining can strand a beginner.
+
+## Applying it
+
+Every code-touching skill reads `user.codingLevel` at the start and calibrates
+its prose accordingly. The skill's *actions* are identical across levels; only
+the surrounding explanation differs. If the user seems mismatched to their
+recorded level mid-task (a `comfortable` user asking what an env file is, or a
+`new` user breezing ahead), gently offer to adjust it.

package/references/crosswalk-schema.md

@@ -0,0 +1,113 @@
+# Crosswalk schema — `crosswalk.json`
+
+The crosswalk is the backbone artifact of a brownfield retrofit: a persistent,
+machine-readable **three-way map** between the new token, the old Figma variable,
+and the old code identifier(s). It drives the code retrofit and the
+`tokens:validate` CI gate. Built by the `token-crosswalk-builder` skill; consumed
+by the validator and reverse-index scripts (`scripts/`). The machine contract is
+`${CLAUDE_PLUGIN_ROOT}/scripts/crosswalk.schema.json`; this doc is its prose home.
+
+## Where it lives
+
+`packages/tokens/crosswalk.json`, beside the DTCG intermediate
+`packages/tokens/dtcg/tokens.json` that `token-sync-layer` emits. The manifest's
+`tokenCrosswalk.path` records the actual path. (Spec §8 shows `tokens/crosswalk.json`
+illustratively; the standard monorepo path is `packages/tokens/crosswalk.json`.)
+
+## Top-level shape
+
+```jsonc
+{
+  "$schema": "./crosswalk.schema.json",
+  "version": 1,
+  "tokens": [ /* rows */ ]
+}
+```
+
+`$schema` is optional but recommended — editors use it to validate the file against `crosswalk.schema.json` inline.
+
+## Row columns
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `newToken` | string | DTCG dot-path, exactly as `token-sync-layer` emits it (`color.text.primary`). This is the key the validator resolves against the DTCG tokens. |
+| `newValue` | string | The **resolved leaf value** — aliases followed to a literal. For a semantic token whose `$value` is `{color.gray.900}`, this is the primitive literal (`#111827`), never the `{…}` reference. |
+| `tier` | `"primitive"` \| `"semantic"` | Which tier the new token belongs to. |
+| `figmaOld` | string \| null | The old Figma variable name/path being reconciled, or `null` for an `added` token with no prior Figma variable. |
+| `codeTokens` | string[] | Old code identifiers this token replaces (`$primary-red`, `bg-primary-red`, `Colors.primaryRed`, `--primary-red`). May be `[]`. Drives the reverse index. |
+| `status` | enum | The reconciliation status — see below. |
+| `recommendedSemantic` | string \| null | An optional suggested semantic token to migrate a raw/primitive usage toward. |
+
+## `status` enum
+
+Kebab-case, from the Sweet case study (151 renamed, 42 added, 12 aligned,
+3 mapped-nearest, 2 drift-fix):
+
+| `status` | Meaning |
+| --- | --- |
+| `aligned` | New token already matches the old one in name and value — no change needed. |
+| `renamed` | Same value, new name. The bulk of a ~90%-semantic retrofit. |
+| `drift-fix` | The old value was wrong/inconsistent; the new value intentionally differs (a deliberate fix, distinguishable from a regression via the Chromatic baseline). |
+| `added` | A new token with no prior Figma variable (`figmaOld: null`). |
+| `mapped-nearest` | No exact old equivalent; mapped to the nearest new token (a judgment call worth review). |
+
+## Status-count rollup (kebab → camelCase)
+
+The manifest's `tokenCrosswalk.statusCounts` uses camelCase keys. The validator
+emits the rollup in this shape so the skill can copy it straight into the manifest:
+
+| Row `status` | `statusCounts` key |
+| --- | --- |
+| `aligned` | `aligned` |
+| `renamed` | `renamed` |
+| `drift-fix` | `driftFix` |
+| `added` | `added` |
+| `mapped-nearest` | `mappedNearest` |
+
+## The validation gate
+
+`tokens:validate` resolves every `newToken` against `packages/tokens/dtcg/tokens.json`
+(following `{…}` alias chains to a leaf) and asserts the resolved value equals the
+row's `newValue`, for **every** row (the N/N gate — Sweet passed 210/210). Value
+comparison is case-insensitive and trimmed, so `#EF4444` and `#ef4444` are equal. A
+token present in the crosswalk but absent from the DTCG source is a failure
+(reported as *missing*), never silently skipped — this honors the read-discipline
+principle in `${CLAUDE_PLUGIN_ROOT}/references/brownfield-retrofit.md`.
+
+## Worked example
+
+```jsonc
+{
+  "$schema": "./crosswalk.schema.json",
+  "version": 1,
+  "tokens": [
+    {
+      "newToken": "color.gray.900",
+      "newValue": "#111827",
+      "tier": "primitive",
+      "figmaOld": "grey/900",
+      "codeTokens": ["$grey-900"],
+      "status": "renamed",
+      "recommendedSemantic": "color.text.primary"
+    },
+    {
+      "newToken": "color.text.primary",
+      "newValue": "#111827",
+      "tier": "semantic",
+      "figmaOld": "Text/Default",
+      "codeTokens": ["$text-default", "text-grey-900"],
+      "status": "renamed",
+      "recommendedSemantic": null
+    },
+    {
+      "newToken": "color.surface.raised",
+      "newValue": "#ffffff",
+      "tier": "semantic",
+      "figmaOld": null,
+      "codeTokens": [],
+      "status": "added",
+      "recommendedSemantic": null
+    }
+  ]
+}
+```