@radicool/throughline 0.12.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jordan Pease
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,214 @@
+<div align="center">
+
+<img src="docs/assets/hero.png" alt="ThroughLine" width="100%" />
+
+# ThroughLine
+
+### Your agentic design team
+
+**Every skill you need to launch and manage a production-grade design system in hours — not months. Built for Claude Code, and installable into Cursor, Codex, or any AGENTS.md agent.**
+
+[![npm](https://img.shields.io/npm/v/%40radicool%2Fthroughline?color=6366f1&label=npm)](https://www.npmjs.com/package/@radicool/throughline)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Built for Claude Code](https://img.shields.io/badge/built%20for-Claude%20Code-d97757)](https://docs.claude.com/en/docs/claude-code)
+[![Also on Cursor · Codex · AGENTS.md](https://img.shields.io/badge/also%20on-Cursor%20·%20Codex%20·%20AGENTS.md-22c55e)](#install)
+[![See it live — Storybook](https://img.shields.io/badge/See%20it%20live-Storybook-FF4785?logo=storybook&logoColor=white)](https://main--6a1ee089ae3a37b70a6e4559.chromatic.com)
+[![Public Figma file](https://img.shields.io/badge/Public-Figma%20file-F24E1E?logo=figma&logoColor=white)](https://www.figma.com/design/OCiZiGpsJ4ncPD8r205BjC/Throughline-Plugin-Test?node-id=0-1&t=5ERihD6fMqMuTEXD-1)
+
+</div>
+
+Whether you're starting from scratch or retrofitting an existing design system, ThroughLine puts you in the driver's seat — you make the high-level decisions while your agentic team powers through the production work. You stay in control of the *what*; it handles the *how*.
+
+**No code experience required.**
+
+---
+
+## What ThroughLine builds
+
+### In Figma
+
+1. **A robust primitive + semantic token system** — color ramps, spacing, type scale, radius, and elevation, with light/dark and multi-brand modes.
+2. **Automatic generation of all text and effect styles** — every type and shadow style, derived from your tokens.
+3. **A visual style sheet** of every token and style for full team transparency — synced to your tokens on demand.
+4. **A full icon component system** — Lucide, Material, or your own SVGs, imported as clean, scalable components.
+5. **A foundational component library** — buttons, inputs, badges, cards, and more, built as proper variant matrices bound to your tokens.
+
+### In code
+
+1. **A pnpm + Turborepo monorepo** on GitHub, scaffolded for you.
+2. **A sync adapter** that syncs your Figma tokens and components to the code framework of your choice.
+3. **Storybook** configured to house all synced components and their documentation.
+4. **CI via Chromatic** for visual regression testing on every push.
+
+### Daily workflow
+
+1. **`/sync-figma-tokens`** — resync changes from Figma to code, landed as a reviewable PR.
+2. **`/new-component`** — ship a new component in Figma, then sync and publish it to code.
+
+## Already have a design system? Retrofit it.
+
+Most teams aren't starting from a blank file — they have a mature codebase with hundreds of hard-coded colors and a Figma file that's drifted from it over the years. ThroughLine treats that as a first-class path, not an afterthought, and it moves *carefully*: it never asserts what's in your files without reading them first, and it never deletes an old token until it's proven nothing still uses it.
+
+1. **Audit before anything changes.** `design-system-audit` sizes both sides of your system — it greps your codebase to measure the real color surface and inventories your Figma file with verified, per-class reads — then tells you how big the migration actually is and how semantic your system already is.
+2. **A crosswalk that guarantees nothing shifts.** `token-crosswalk-builder` maps every new token to its old Figma variable and old code value, then installs a `tokens:validate` gate that fails unless every resolved new value matches the old one (N/N). A zero-reference guard blocks removing an old token while any code still references it.
+3. **A gated, reversible migration.** `retrofit-planner` walks the safe seven-phase sequence — audit → refine variables in place → rebind → sync → capture a visual baseline → retrofit the code → remove the old tokens — pausing for your confirmation between every phase, with an optional decision journal recording each call.
+
+The payoff: your live product looks identical at every step, and you can prove it with a Chromatic baseline captured before the first change.
+
+## See a real end-to-end system built with it
+
+<img src="docs/assets/case-study.png" alt="A complete ThroughLine design system — Foundations, Button variants, Icons, and Figma variables" width="100%" />
+
+| | |
+|---|---|
+| 🧩 **[Sample repo](https://github.com/jrpease/throughline-sample)** | The full monorepo — tokens, 14 components, Storybook, CI |
+| 📚 **[Live Storybook](https://main--6a1ee089ae3a37b70a6e4559.chromatic.com)** | Every component, all props, auto-generated docs |
+| 🎨 **[Public Figma file](https://www.figma.com/design/OCiZiGpsJ4ncPD8r205BjC/Throughline-Plugin-Test?node-id=0-1&t=5ERihD6fMqMuTEXD-1)** | The design source of truth it was generated from |
+
+Everything above was created during a single working session and synced directly from Figma to a production-ready codebase.
+
+## Getting started
+
+### Requirements
+
+| | |
+|---|---|
+| **A supported agent** | Required — [Claude Code](https://docs.claude.com/en/docs/claude-code) (native plugin), or **Cursor**, **Codex**, or any **AGENTS.md**-aware agent via `npx @radicool/throughline init`. |
+| **Figma** | Required, **desktop app** (the browser version causes connection errors). **Professional plan or higher recommended** — multi-mode variables (Light/Dark, brand themes) need it. |
+| **Figma access token** | Required — read/write your file. The setup skill walks you through it; your token stays yours and is never shared in chat. |
+| **GitHub** (or similar) | Optional — only when you're ready to graduate to a real remote repo with PRs and CI. |
+
+### Install
+
+ThroughLine is authored as a Claude Code plugin and generated into adapters for other agents. Pick your tool:
+
+#### Claude Code
+
+Install from this repo's plugin marketplace:
+
+```
+/plugin marketplace add jrpease/throughline
+/plugin install throughline@throughline-marketplace
+```
+
+Then start with:
+
+```
+/throughline:start
+```
+
+This is the reliable entry point — it runs environment setup first, ahead of anything else. (You can also just say *"let's set up my design system"*, but if you have other plugins installed that grab "let's build…" style phrases, the slash command guarantees ThroughLine takes the wheel.)
+
+Update anytime with `/plugin marketplace update throughline-marketplace`.
+
+#### Cursor, Codex, or a generic AGENTS.md agent
+
+Run the installer in your project — it stamps in the skills, the reference docs, the scripts, and the Figma MCP config for your tool:
+
+```
+npx @radicool/throughline init --target=cursor    # → .cursor/rules + .cursor/mcp.json
+npx @radicool/throughline init --target=codex      # → prompts/ + AGENTS.md index + codex-mcp.toml
+npx @radicool/throughline init --target=generic    # → skills/ + AGENTS.md index
+```
+
+It's safe to re-run (it merges `AGENTS.md` and `.cursor/mcp.json` non-destructively) and stages everything the skills read into `.throughline/`. Then open the `figma-environment-setup` skill/rule/prompt for your tool to begin. For Codex, add the printed `codex-mcp.toml` block to your Codex config to enable Figma access.
+
+## Architecture
+
+ThroughLine is more than a pile of skills — it's a small system designed to stay consistent across dozens of generation steps. Four layers work together:
+
+**🛠 Twelve skills — the steps.** Each owns one stage of the journey, from connecting Figma to retrofitting an existing system to standing up CI. They're sequenced, and each knows its prerequisites.
+
+**📐 Ten reference docs — the constitution.** Shared standards every skill obeys: Figma component rules (auto-layout-on-everything, slot contracts, naming-as-contract, a required post-build audit), the brainstorm-before-build protocol, the sync-adapter specs, the manifest schema, coding-level adaptivity, the publishing flow, and the brownfield-retrofit discipline (read-before-assert, the safe migration sequence, the crosswalk contract). This is *why* two different runs produce the same structure — the rules live in one place, not scattered per skill.
+
+**🧭 An orchestration layer — the memory.** A `design-system.json` manifest in your project records exactly what's set up, with a versioned schema and immutability rules. Every skill reads it, tells you what it's about to do, and offers to run anything missing first. Run **`/design-system-status`** anytime for a plain-language picture of where you stand.
+
+**🔌 An adapter layer — the bridge.** A Style Dictionary pipeline that translates your Figma variables into whatever code framework you target — and re-translates on every change, so design and code never drift.
+
+### The skills
+
+| Skill | What it does |
+|---|---|
+| **figma-environment-setup** | Create your working folder, connect Claude to Figma, scan what already exists. **Start here.** |
+| **design-system-audit** | Measure an existing system *before* retrofitting — size the code-side color surface and inventory the Figma file with verified reads. The brownfield front door. |
+| **token-builder** | A two-tier (primitive + semantic) token system as Figma variables, plus text/effect styles. Generative, descriptive, or import-your-own. |
+| **token-sheet-builder** | A beautiful, on-brand **Foundations** page visualizing every token, live-bound to the variables. |
+| **icon-system-builder** | An **Icons** page with your chosen library (Lucide, Material, or custom) as clean components — the cheap, fast way. |
+| **component-builder** | Your foundational components (button, input, card, modal…) with full variant matrices, slots, and token bindings. |
+| **repository-builder** | Graduate your folder into a pnpm + Turborepo monorepo — folder → local git → GitHub, one gentle step at a time. |
+| **token-sync-layer** | Sync Figma variables to framework-specific code via Style Dictionary, landed as a reviewable PR. Installs `/sync-figma-tokens`. |
+| **token-crosswalk-builder** | Map new tokens to their old Figma variables and old code values, and install the `tokens:validate` gate that proves no value changed during a retrofit. |
+| **storybook-chromatic-builder** | Storybook, component stories, Chromatic visual testing, and Code Connect (where your Figma plan supports it). |
+| **component-pipeline** | Add one new component end to end: Figma → tokens → code + stories. Installs `/new-component`. |
+| **retrofit-planner** | Orchestrate a full retrofit through the safe, gated seven-phase sequence — with a human checkpoint at every phase. |
+
+## The nitty gritty
+
+For the technically curious — how the machine actually runs.
+
+**The sync layer.** Figma variables are extracted to **DTCG-format** JSON (the W3C design-tokens standard), run through **Style Dictionary**, and shaped by a framework **adapter** into the exact output your stack expects — shadcn CSS variables, a Tailwind theme, MUI theme objects, Swift/Kotlin constants, or plain CSS. Because the code is *generated* from the extract, design and code can't drift: you never hand-edit outputs, you change Figma and re-run. The sync lands as a **pull request**, so every design change is reviewable, diffable, and CI-checked before it merges.
+
+**The monorepo.** A **pnpm + Turborepo** workspace: `packages/` holds the generated tokens and the component library; `apps/` is where you build the actual product against your own design system. ThroughLine grows it in stages — plain folder → local git → GitHub remote with PRs and CI — introducing each concept only when its payoff is concrete, so you're never dropped into the deep end.
+
+**The manifest.** `design-system.json` is the single source of truth for *state*: a versioned schema, canonical per-skill flags, an immutable record of how your project began (greenfield vs. existing repo), and a snapshot of tooling detected at setup. Skills read it to know what's done and what's safe to do next — which is how the system stays coherent across many sessions.
+
+**Modes, within Figma's limits.** Light/Dark lives on the semantic collections; brand variants live on the primitive palette. Splitting the two axes across two collections keeps each one under Figma's 4-modes-per-collection cap on the Professional plan while still resolving correctly (`bg/default` → `{gray/50}` → the active brand's gray).
+
+**Model routing.** Setup runs on **Haiku** automatically to keep first-run costs low. Everyday work runs on whatever model your session is set to — **Sonnet** is a sensible default. For the heaviest authoring (large token systems, intricate variant matrices), **Opus** gives the best results: `/model opus`, then back to `/model sonnet`. Nothing forces an expensive model on you.
+
+## Who it's for
+
+1. **Solo designers** who spend a lot of time building and managing design systems.
+2. **Agencies** consistently spinning up new design systems for clients.
+3. **Design teams** constantly fighting to keep their Figma and code systems in sync.
+4. **Non-designer vibe coders** who want a stronger design-system backbone on their projects.
+5. **Engineers** looking to bridge their code and design ecosystems.
+
+## Why I built it
+
+I'm a designer who got tired of the handoff. Design systems live in two places that never quite agree — the Figma file and the codebase — and keeping them in sync is a full-time job nobody wants. ThroughLine is the tool I wished existed: it lets a designer drive the whole pipeline, learn the engineering one concept at a time, and end up with a real, shippable system instead of a pile of redlines. If you're a designer who's becoming a developer, this was built for you.
+
+## Works well with
+
+**[Superpowers](https://github.com/obra/superpowers)** — a great planning and engineering partner for the moments that grow bigger than a single skill. ThroughLine owns the design-system line; Superpowers owns the heavier, open-ended engineering work — and the two hand off cleanly.
+
+- **Big, ambiguous changes mid-build.** When a step turns into a real project, ThroughLine lays out the risks and major pieces and switches into brainstorm-and-plan mode before building — handing off to Superpowers when it's installed, or planning natively when it isn't (the recognition is ThroughLine's; Superpowers is an upgrade, not a requirement). Real example: on [radicool.studio](https://radicool.studio), an existing vanilla-React app with a full custom motion layer — custom cursors, magnetic buttons — was retrofitted onto shadcn to make it formal and ready to scale.
+- **Building the app itself.** Once your system is synced to code and you're building in `apps/`, Superpowers' subagent-driven development methodology is a natural next step.
+
+It's never required to use ThroughLine.
+
+## Show it off
+
+Built your own system with ThroughLine? Add the badge so others can find it:
+
+```markdown
+[![Built with ThroughLine](https://img.shields.io/badge/Built%20with-ThroughLine-6366f1)](https://github.com/jrpease/throughline)
+```
+
+[![Built with ThroughLine](https://img.shields.io/badge/Built%20with-ThroughLine-6366f1)](https://github.com/jrpease/throughline)
+
+## Contributing
+
+ThroughLine is open source and contributions are welcome. Found a bug or have an idea? **[Open an issue](https://github.com/jrpease/throughline/issues)**. Want to improve a skill or reference doc? PRs are encouraged — the skills are Markdown, so they're approachable to edit.
+
+A couple of ground rules:
+- **Figma is the source of truth.** Generated code files are build artifacts — never hand-edited; change things in Figma and re-sync.
+- **Secrets stay yours.** Tokens and keys are never sent through chat or committed to code.
+- **The plugin validates itself.** Every PR runs CI (`.github/workflows/ci.yml`) — the full test suite plus zero-dependency structural validators that check `plugin.json`, the marketplace manifest, and every skill/command's frontmatter. Run them locally with `node --test` and `node ci/validate-plugin.mjs` / `node ci/validate-skills.mjs`.
+
+## Roadmap
+
+Future improvements and planned capabilities. Have a request? **[Open an issue](https://github.com/jrpease/throughline/issues)** — the roadmap is shaped by what people actually build.
+
+- **More framework adapters** — broaden the Style Dictionary output targets beyond the current set.
+- **Deeper Code Connect coverage** — richer Figma-to-code mappings as more plans support it.
+- **Expanded component starters** — a larger foundational kit out of the box.
+- **Richer status & auditing** — more from `/design-system-status`, including drift detection between Figma and code.
+- **Built-in accessibility checks** — automatic a11y validation when tokens and components are created, so modes can't be built with poor color contrast and components can't ship with accessibility gaps. Catches issues at creation time rather than in review.
+- **One library, many platforms** — support a single Figma token library that syncs to multiple platforms at once (React, Android, iOS), with a component lifecycle flexible enough to target per platform — every platform, or native-only components that don't need a React counterpart.
+
+Versioning follows [Semantic Versioning](https://semver.org). The current version lives in [`.claude-plugin/plugin.json`](.claude-plugin/plugin.json); every release is recorded in [`CHANGELOG.md`](CHANGELOG.md).
+
+## License
+
+[MIT](LICENSE) © Jordan Pease

package/adapters/codex/AGENTS.md

@@ -0,0 +1,29 @@
+# ThroughLine (Codex adapter)
+
+ThroughLine builds a design system end to end. Load the matching prompt 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. → load `prompts/component-builder.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. → load `prompts/component-pipeline.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. → load `prompts/design-system-audit.md`.
+- `figma-environment-setup` — Set up the local working folder and connect Codex to Figma so the design-system skills can read and write variables, styles, and components. → load `prompts/figma-environment-setup.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. → load `prompts/icon-system-builder.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. → load `prompts/repository-builder.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. → load `prompts/retrofit-planner.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. → load `prompts/storybook-chromatic-builder.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. → load `prompts/token-builder.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. → load `prompts/token-crosswalk-builder.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. → load `prompts/token-sheet-builder.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). → load `prompts/token-sync-layer.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. → load `prompts/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. → load `prompts/new-component.md`.
+- `start` — Start building your design system — the deterministic entry point. → load `prompts/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. → load `prompts/sync-figma-tokens.md`.
+
+## MCP servers
+
+Figma access is provided by the `figma-console` MCP server. See `codex-mcp.toml` for the config to add to your Codex `mcp_servers`.

package/adapters/codex/codex-mcp.toml

@@ -0,0 +1,4 @@
+[mcp_servers.figma-console]
+command = "npx"
+args = ["-y", "figma-console-mcp@latest"]
+env = { FIGMA_ACCESS_TOKEN = "${FIGMA_ACCESS_TOKEN}" }

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

@@ -0,0 +1,272 @@
+# Component builder
+
+Creates the foundational component set in Figma: well-structured components with
+variant matrices, bound to the system's tokens/styles, with slots typed so they
+translate cleanly to code later.
+
+## Prerequisites
+
+Needs tokens (`tokens.semanticBuilt` true) — offer to run `token-builder` if
+missing. Needs a live Figma connection (offer `figma-environment-setup` if not).
+Use the mechanism in `figma.mechanism`.
+
+**Before scripting any `figma_execute`, read
+`.throughline/references/figma-scripting.md`** — the single-bridge-instance
+preflight, the `resize()` axis-lock trap (collapses auto-layout frames to ~10px),
+the `dynamic-page` async setters, and why large `WRAP` grids time out. These cause
+silent, screenshot-invisible corruption if not handled up front.
+
+**Recommend icons first (soft gate).** Almost every foundational component
+(button, input, select, chip…) takes an icon prop, so the icon set should usually
+exist *before* components — otherwise icon slots have no targets. If
+`icons.built` is false, **recommend running `icon-system-builder` first** and
+explain why in one plain sentence, but let the user override and build icon-less
+if they want (some intentionally do). This is a recommendation, not a hard block.
+
+> **Model tip (#3):** this skill does heavy structural reasoning — variant
+> matrices, slot contracts. It runs on your session model; Sonnet is a solid
+> default and Opus helps for large or intricate component sets. See the model
+> guide in the ThroughLine README.
+
+## Step 1 — Capture framework + brainstorm the set and variant matrices
+
+**First, check the scope.** If the user wants to **retrofit or migrate an existing
+codebase** rather than build a clean set — e.g. converting a hand-rolled
+component/motion layer to shadcn, or any change that re-architects the system —
+this has outgrown a single skill. Follow
+`.throughline/references/scaling-up-handoff.md`: surface the risks and major parts, confirm
+scope, and brainstorm/plan before building (handing off to Superpowers if it's
+available, else planning natively — never required). For a normal from-the-system
+build, continue here.
+
+**Framework (capture lazily, here if not already set).** Read
+`project.uiFramework` from the manifest. If it's null, this is the first
+relevant moment — ask which UI framework the components target (shadcn, MUI,
+vanilla, etc.; reuse the same value the sync adapter will use) and record it.
+If sync already set it, reuse it — don't re-ask. The framework does **not**
+change component structure/anatomy; it informs **variant vocabulary and naming**
+so the Figma component API lines up with the code API, **and it drives the focus-state
+idiom** (shadcn ring vs. MUI per-component vs. vanilla-css outline — see "State
+handling" in `.throughline/references/figma-component-standards.md`). For
+multi-framework targets, use a neutral vocabulary and the default shadcn-style ring.
+
+**Recommended core set (editable).** Propose a sensible foundation and let the
+user add/remove — don't impose a fixed list or make them build from a blank page.
+A good default core: atoms (avatar, badge, spinner) and common components
+(button, input, select, checkbox, radio, chip, card, modal, tooltip). Explain
+why these are the foundation. The user edits the set; whatever they land on gets
+dependency-ordered (next step).
+
+**Variant matrices.** Run `.throughline/references/brainstorm-before-build.md`. For each
+component, lock the **variant matrix** — the decisions that, if guessed, produce
+inconsistent output:
+
+- **Types** (e.g. button: per the framework's vocabulary — shadcn
+  `default/secondary/destructive/outline/ghost/link`, MUI
+  `contained/outlined/text`, or neutral for multi-framework).
+- **Sizes** (sm, md, lg). Each size is its **own variant row**, not a state — see
+  the layout law below.
+- **States** — **include the full relevant set, don't trim it.** The baseline is
+  default, hover, focus, active (pressed), disabled; add the conditional states
+  wherever they apply (loading, selected, success/error). Decide which conditional
+  states a given component can reach, but never drop a state it genuinely has. See
+  "State handling" in `.throughline/references/figma-component-standards.md`
+  for the per-component checklist.
+- **Slots** — leading/trailing icons, avatars, adornments (see slot types below).
+
+Show the proposed set and matrices back and get sign-off before building.
+
+## Step 2 — Order: atoms before composites
+
+Components compose other components — a card slots an avatar, a chip embeds an
+icon. So build in **dependency order, atoms first**, the component-tier analog
+of the primitive→semantic token seam:
+
+1. **Atoms** — avatar, badge, spinner, (icons already exist). No DS-component
+   slots, or only icon slots.
+2. **Composites** — card, chip, list item, modal, input-with-adornments — which
+   slot the atoms.
+
+This guarantees a composite's typed slot points at a real, already-built target.
+Build bottom-up; checkpoint after each component (sequential — this is Figma
+authoring, no subagents).
+
+## Step 3 — Build each component, bound to tokens/styles
+
+For each component, using the active write mechanism (scripted where helpful),
+following `.throughline/references/figma-component-standards.md` (auto layout on everything,
+variants vs. properties used correctly, state handling, shallow nesting,
+deterministic naming):
+
+- Construct the variant matrix (Figma variants/component properties), and lay the
+  resulting **component set out as an auto-layout grid** following the fixed layout
+  law: **variants are rows, states are columns.** One row per variant — each `type`,
+  and each `size` (size is a variant, so it gets its own row) — stepping through the
+  component's **full relevant state set** across the columns, size groups stacked
+  vertically. Per "Component set arrangement" and "State handling" in the standards
+  doc.
+- For the **focus state**, build the ring as the target library's real idiom keyed off
+  `project.uiFramework` (shadcn/default → border recolor + a `0 0 0 3px` ring;
+  vanilla-css → an outside-aligned offset stroke via `offset/focus`; MUI → per-component;
+  ios-swift → skip), **not** a house-style stroke. Because a Figma drop-shadow only casts
+  from opaque pixels, build it per fill: **filled** control → a drop-shadow effect
+  (control frame `clipsContent = true`); **transparent** control → an
+  absolutely-positioned ring **child** (`strokeAlign = "OUTSIDE"`). **Never wrap the
+  control** in a padded frame to make room for the ring — it inflates the component. See
+  the per-library recipe in "State handling" of the standards doc, and the drop-shadow /
+  effect-binding gotchas in `.throughline/references/figma-scripting.md`.
+- **Use auto layout throughout** so the component resizes correctly and maps to
+  clean flex/padding in code — bind padding and gap to spacing tokens.
+- **Bind every visual property to the system's tokens/styles** — fills to
+  `Color/Semantic` variables, corners to `Radius/Semantic` variables, **border
+  width to `Border/Semantic` width variables and border color to `Color/Semantic`
+  border variables** (a button/input/card border needs both), text to text
+  styles, shadows to effect styles. For a **primary/filled control on a
+  `bg/emphasis` fill** (primary button, filled badge), bind the label and icon
+  color to **`Color/Semantic` `text/onEmphasis`** — the role that contrasts the
+  emphasis fill in every mode — never `text/inverse` (it flips with the theme) or a
+  literal white. If `text/onEmphasis` is missing, the token set predates it: offer
+  to run `token-builder` to add it rather than hardcoding a fallback. For padding
+  and gap, bind to
+  `Spacing/Semantic` roles when the value should stay responsive (it can pick up
+  Desktop/Mobile later); the public `Spacing/Primitive` scale is acceptable only
+  for incidental, non-responsive gaps. A component must *consume* the design
+  system, never hardcode values. This is what makes the token cascade reach
+  components.
+- Implement slots per the slot-contract model below.
+- **Wrap each component in its own documentation card** — a token-styled frame
+  with the component name, a short description, a status chip
+  (`draft`/`beta`/`stable`/`deprecated`), and a last-updated date, with a
+  **division element between the header and the component area** (a
+  `Border/Semantic`-bound divider line, or a header container on a distinct surface
+  fill — see "Always separate the header from the component area" in the standards
+  doc) — and arrange the cards in an orderly grid 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), never floating on bare canvas. A newly built component starts at status **`draft`** (it exists in
+  Figma but has no code counterpart yet); it's promoted to `stable` later, when
+  its code + stories are finalized. Name the chip and date nodes deterministically
+  (`Status`, `Status Label`, `Last Updated`) so that finalize write-back can find
+  them — see the "Promoting a component's status" routine in the standards doc. Follow the "Documentation artboards & canvas layout" rules in
+  `.throughline/references/figma-component-standards.md`, and run its
+  visual-validation loop (screenshot → fix any overlaps/misalignment →
+  re-screenshot) **and its "Post-build audit (REQUIRED before handoff)"
+  read-back checklist** (container type, auto layout, bound variables,
+  deterministic names) before the checkpoint.
+
+Checkpoint after each component: show all variants, confirm before the next.
+
+## Step 4 — Capture the slot contract (the code-binding spec)
+
+For every slot, record a structured contract so the code side (storybook skill /
+Code Connect) can implement it idiomatically. Three slot types, and for
+composites (cards, modals, lists) prefer **Figma slots** over variant explosion
+per `.throughline/references/figma-component-standards.md`:
+
+- **Icon-set slot** — accepts any icon from the Icons page. → code: a prop typed
+  to the icon set (e.g. `leadingIcon`), optional, with a canonical default icon
+  name if any. Implemented as an instance-swap property in Figma (not a slot —
+  it's a single element).
+- **Typed-component slot** — accepts a specific DS component (e.g. an Avatar in a
+  Card). → code: a prop typed to that component (e.g. `avatar`), optional. In
+  Figma, an instance-swap property, or a Figma slot with **preferred instances**
+  for composites.
+- **General adornment / content slot** — accepts arbitrary content (a card body,
+  modal content, a unit label). → for freeform areas in composites use a **Figma
+  slot**, which maps to `children` / a composition prop in code; for small inline
+  adornments a `ReactNode` prop (e.g. `endAdornment`).
+
+**Typed dropdown vs. fallback (publishing-gated).** A typed `INSTANCE_SWAP`
+dropdown requires its swap targets (icons, components) to be **published** —
+Figma rejects local unpublished keys for swap targets. Before adding the dropdown,
+check publish state per `.throughline/references/figma-publishing.md`:
+
+- **Resolve publish state first (detect-or-ask, bug B3):** a default/`false`
+  `figma.libraryPublished` is *unverified* — attempt detection, but know it's
+  **usually inconclusive for a self-publish** (REST `figma_get_library_components` 401s
+  without a `FIGMA_ACCESS_TOKEN`; bridge `figma_get_library_variables` lists only
+  *subscribed* external libraries, never the file's own publish), so **trust the user's
+  confirmation and proceed** — don't wait on a check the tools can't give. Never treat a
+  `false` as a final "not published". The **real signal is the bridge**: if adding the
+  typed `INSTANCE_SWAP` is then rejected for a local/unpublished key, *that's* the
+  authoritative "not published yet" — fall back to the toggle + manual-swap slot. See
+  `.throughline/references/figma-publishing.md`.
+- **Confirmed published (`figma.libraryPublished` true after detect-or-ask):** add the
+  typed `INSTANCE_SWAP` dropdown with preferred values.
+- **Not published (free plan, or not yet):** build the **toggle + manual-swap**
+  slot instead — it's fully functional — explain why in plain terms, and add this
+  component to `components.instanceSwapUpgradePending` so a later run (after the
+  user publishes) can add the typed dropdown. Never present this as a failure.
+
+Two rules for every slot:
+
+- **Show/hide collapses into prop optionality.** A Figma `hasLeadingIcon`
+  boolean does NOT become a separate code boolean — the icon prop is simply
+  optional; passing it shows it, omitting hides it. Don't generate a redundant
+  boolean prop alongside the slot prop.
+- **The contract syncs; per-instance choices don't.** The slot's existence,
+  type, and default sync to code. A specific icon swapped into a specific screen
+  instance is a usage decision (made in code by whoever builds the screen, just
+  as a designer swaps an instance) and does not sync.
+
+Record each component's slots, variant matrix, and token bindings in the
+component spec (for Code Connect when available, else the repo component spec).
+
+## Step 5 — Naming as contract
+
+Name components deterministically so Figma↔code mapping is automatic: `Button` ↔
+`Button`, `Avatar` ↔ `Avatar`. This is what lets typed-component slots and the
+storybook build resolve the right imports. Same discipline as icon naming —
+without it, components silently diverge between Figma and code.
+
+## Step 6 — Checkpoint and hand off
+
+Update the manifest: add each built component to `components.built`, and record
+its `components.meta[name]` (`status: "draft"`, `updatedAt`) to match the doc
+card. (Finalize to `stable` happens later, in storybook-chromatic-builder.) Ensure
+any component built with the toggle + manual-swap fallback is listed in
+`components.instanceSwapUpgradePending`. Append `component-builder` to
+`completedSkills`.
+
+**Upgrade pass:** if `components.instanceSwapUpgradePending` is non-empty, re-resolve
+publish state (detect-or-ask per `.throughline/references/figma-publishing.md`);
+only when it is **confirmed published** (`figma.libraryPublished` true via a verified
+detect-or-ask, not a stale default) offer to add the typed `INSTANCE_SWAP` dropdowns to
+those components and clear each from the list.
+
+Offer next steps: build the code counterparts and stories
+(storybook-chromatic-builder), or build a single new component end-to-end later
+(the component-pipeline orchestrator).
+
+## What this skill must NOT do
+
+- Never hardcode values that should be token/style bindings — components consume
+  the system.
+- Never generate a redundant show/hide boolean alongside an optional slot prop.
+- Never build a composite before its atomic slot targets exist.
+- Never guess variant matrices — brainstorm and confirm them first.
+- Never claim to publish a Figma library — publishing is a manual user step;
+  instruct and verify only.
+- Never leave components floating on bare canvas — each goes on a token-styled
+  doc card arranged in an auto-layout Frame placed directly on the page (never a
+  Section), with the layout visually validated.
+- Never lay out a component set as scattered variants — the `ComponentSet` is an
+  auto-layout grid where **variants are rows and states are columns**: one row per
+  variant (each `type`, and each `size`, since size is a variant) stepping through
+  states across the columns, size groups stacked vertically (see the standards doc).
+- Never ship a component with only its `default` state — include the full relevant
+  state set (default/hover/focus/active/disabled plus applicable
+  loading/selected/success/error).
+- Never run the component header and the component area together with no division —
+  every doc card segments the header from the component area with a divider line or
+  a distinct header surface.
+- Never invent a house-style focus ring or wrap the control in a padded frame to make
+  room for one — derive the focus state from `project.uiFramework`'s real idiom, built
+  as a drop-shadow effect (filled controls) or an absolutely-positioned ring **child**
+  (transparent controls), per "State handling" in the standards doc.
+- Never rebuild a published/consumed component set with a delete-and-recreate without
+  re-instancing downstream — deleting and recreating a set (e.g. to change the Button's
+  internal architecture) **detaches every instance** that referenced its variants (the
+  Card's footer buttons, etc.). Record which components consume which, warn before an
+  architectural rebuild, and re-instance the affected consumers afterward.
+

package/adapters/codex/prompts/component-pipeline.md

@@ -0,0 +1,81 @@
+# Component pipeline (orchestrator)
+
+Sequences a single new component through the whole flow: Figma → tokens →
+code/stories. This skill holds **zero domain logic of its own** — it is a
+sequencer that invokes the real skills and gates each stage on a human
+confirmation. All the actual work lives in the skills it calls; this keeps it
+from rotting when those skills improve.
+
+## When to use vs. the individual skills
+
+Use this for **one new component, end to end**, on a system that already has
+foundations (tokens, repo, sync, Storybook). For initial setup, the individual
+skills run directly. This is the "I have a system; add a Tooltip and take it all
+the way to a tested story" flow.
+
+## Prerequisites
+
+Read the manifest. The pipeline assumes foundations exist: tokens built, a repo
+at least `local-git`, sync configured, Storybook initialized. For any missing
+piece, offer to run the relevant skill — but note that if a lot is missing, the
+user probably wants the individual setup skills first, not this orchestrator.
+
+## The sequence (confirm between every stage)
+
+Confirm the goal first: "New `Tooltip` component, right? I'll build it in Figma,
+sync any new tokens, then build the code component and its stories — checking
+with you between each step." Then:
+
+### Stage 1 — Build in Figma (invoke component-builder)
+
+Invoke the `component-builder` prompt for this one component: brainstorm its
+variant matrix and slots, build it bound to tokens following the component
+standards, capture its slot contract. **Checkpoint:** show the finished Figma
+component. Get explicit confirmation before continuing.
+
+If the build fails or the user wants changes, stop here — they still have a
+valid (or fixable) Figma component and a clean place to resume. Never push a
+half-built component down the pipeline.
+
+### Stage 2 — Sync new tokens (offer token-sync-layer)
+
+The new component may have introduced new tokens (a new semantic role, a new
+spacing step). Offer: "This component added a couple of new tokens — want me to
+sync them to code now?" If yes, invoke `token-sync-layer` (which lands a
+reviewable PR per its own rules). If the component introduced no new tokens, say
+so and skip. **Checkpoint:** confirm the sync PR before continuing.
+
+### Stage 3 — Build code component + stories (offer storybook-chromatic-builder)
+
+Offer: "Tokens are synced. Build the code component and its stories now?" If yes,
+invoke `storybook-chromatic-builder` for this one component: build the code
+counterpart implementing the captured slot contract, generate its stories
+(subagent-driven), wire Code Connect if available. **Checkpoint:** confirm the
+component renders and stories build. On approval, that skill **finalizes** the
+component — promoting its status from `draft` to `stable` and writing the new
+chip color + last-updated date back into its Figma doc card (its Step 6). Since
+Figma is still connected from stage 1, the card updates live; the chip should no
+longer read `draft` once the pipeline finishes.
+
+## Resumability
+
+Because each stage is gated and invokes a real skill, a failure at any stage
+leaves a clean resume point: the Figma component exists after stage 1, the token
+PR after stage 2, the code/stories after stage 3. The user can stop after any
+stage and pick up later — the manifest reflects what's done.
+
+## After completion
+
+Confirm the component went all the way through. Update nothing the sub-skills
+didn't already update (they own their manifest fields). Note the ongoing loops:
+more components via this pipeline, token changes via `/sync-figma-tokens`.
+
+## What this skill must NOT do
+
+- Never reimplement what the sub-skills do — only sequence them. If you find
+  yourself writing component-building or sync logic here, stop and invoke the
+  real skill instead.
+- Never skip a confirmation between stages — the gates are what make it
+  resumable and prevent half-updated state.
+- Never push a half-built or unconfirmed component to the next stage.
+