jrpease/throughline/component-builder

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). The plugin writes to Figma through Console MCP. If figma.mechanism holds anything other than console-mcp, say that value is no longer supported and offer figma-environment-setup to reset it.

Before scripting any `figma_execute`, read `${CLAUDE_PLUGIN_ROOT}/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 plugin 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 ${CLAUDE_PLUGIN_ROOT}/references/scaling-up-handoff.md: surface the risks and major parts, confirm scope, and brainstorm/plan before building. 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 ${CLAUDE_PLUGIN_ROOT}/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 ${CLAUDE_PLUGIN_ROOT}/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

the set ${CLAUDE_PLUGIN_ROOT}/references/state-baseline.md owes that component (default included); add the conditional states wherever they apply (loading, success/error). Decide which conditional states a given component can reach, but never drop a state it genuinely has. See "State handling" in ${CLAUDE_PLUGIN_ROOT}/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.

1. 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 in dependency order.

Execution model — sequential subagents with model routing. If your host supports subagent dispatch, plan the whole set once with one architect dispatch (deep tier) — it reads existing Figma state and emits a transcription-grade spec in stable identifiers — then build each component with one figma-executor dispatch (fast→balanced), strictly sequentially: preflight figma_get_status and never run two Figma-touching subagents at once (the single bridge is concurrency-1). Each executor builds into a WIP: frame and finalizes by build-verify-then-replace (see ${CLAUDE_PLUGIN_ROOT}/references/figma-scripting.md); gate each finished component with a reviewer visual pass. Route per ${CLAUDE_PLUGIN_ROOT}/references/agent-routing.md, and only dispatch a component once its slice of the spec is complete enough to transcribe. Keep the human checkpoint between components — subagents run continuously within a component, but you pause for the human between them. If your host has no subagent dispatch, build and verify each component inline, sequentially, as before. Inline, run the active-file preflight in ${CLAUDE_PLUGIN_ROOT}/references/figma-scripting.md before the first write and again before replacing anything — the executor's file check does not come with you.

Step 3 — Build each component, bound to tokens/styles

For each component, using the active write mechanism (scripted where helpful), following ${CLAUDE_PLUGIN_ROOT}/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 ${CLAUDE_PLUGIN_ROOT}/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. The renderer adds the _Doc/Header kit instance (its Status variant starts from the manifest status) — don't hand-build the header or name its chip; finalize sets the variant later, per the "Promoting a component's status" routine in the standards doc. Follow the "Documentation artboards & canvas layout" rules in ${CLAUDE_PLUGIN_ROOT}/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. When you build inline, with no figma-executor, run ${CLAUDE_PLUGIN_ROOT}/references/figma-checks.md the way the executor does: 'spec' mode before the first write and 'built' mode in the self-verify loop, with EXPECT built from your own matrix. You are the architect here, so you name controlLayer yourself for a wrapped control (an Input with a label or helper text), and surfaces yourself: the colour-variable names of the page surfaces the component sits on. A fail on the focus-indicator check stops the build, as it would for the executor. A fail on focus-contrast stops it too, naming its detail. A ring below 3:1 is fixed by a token value, so don't change a variable or swap the ring to another one to make it pass; a surface the file doesn't have is a wrong name in surfaces.