Forge — Create Component

Prerequisite: forge.config.json exists at the repo root (run forge init once).

Scaffold a new component so it is indistinguishable from a hand-written senior-engineer component in this library's style, document it in the brain, and ship it as a PR into the base branch from forge.config.json git.prBase (defaults to main).

When this triggers

The user wants a component that isn't in the library yet. First confirm it's genuinely absent: check the brain's Component index and grep the repo for the export. If it already exists, stop — use edit-component.

Inputs to confirm (ask only what's genuinely ambiguous)

1. Name (and exported symbol — follow whatever naming convention the rules in forge.config.json + the standard at ${CLAUDE_PLUGIN_ROOT}/skills/_shared/references/component-standard.md prescribe, and match how siblings in the brain are named). Confirm the symbol if unclear.
2. What it does and its prop surface — variants, sizes, states, events.
3. Repo location if not already known.
4. Group — core or foundational (where it belongs in the brain index).

Workflow

1. Load the house style

• Read the rules in forge.config.json and ${CLAUDE_PLUGIN_ROOT}/skills/_shared/references/component-standard.md first — the enforceable spec the new component must satisfy from line one (naming convention, <Name>Props, variant/color axes, size scale, className last, ARIA + keyboard, files, barrel export).
• Read the brain's Foundations + Conventions: ${CLAUDE_PLUGIN_ROOT}/skills/_shared/DESIGN-SYSTEM.md.
• Read ${CLAUDE_PLUGIN_ROOT}/skills/_shared/references/conventions.md and .../standing-guidance.md (corrections override defaults).
• MANDATORY — read 2–3 sibling components closest in shape (Toast→Alert/Notification; Modal→Dialog; Stepper→Tabs/Progress) and state in your output which sibling(s) you mirrored. Copy their exact tokens (the same --text-*, --surface-*, --radius-*, --space-* they use), their class-naming, their structure. Do not anchor to generic foundation tokens when a sibling shows the house choice — that's what causes visual clashes.
• Compose existing primitives — never re-implement them. If the component needs a button, import the library's Button/IconButton; an input, its InputField; a checkbox, its Checkbox. Hand-rolling a button/input inside a new component is a defect. Run use-component mentally: what does the library already give you?

2. Scaffold the component

Create, under src/components/<Name>/:

• <Name>.tsx — function component, forwardRef when it renders a focusable DOM element. Naming per the rules in forge.config.json + the standard at ${CLAUDE_PLUGIN_ROOT}/skills/_shared/references/component-standard.md. Named interface <Name>Props (required first, optional next, handlers last). Variants as string-literal unions, with the visual-style and semantic-color axes / size scale defined by the standard. className override hook appended last. ARIA + keyboard support. Maximally prop-driven, zero-config where possible.
• <Name>.css — co-located. Reference token CSS variables only; never hardcode hex/px when a token exists. Theming works automatically via data-theme — don't special-case themes.
• <Name>.stories.tsx — stories covering each variant/size/state.
• <Name>.test.tsx — render + key behavior + a11y smoke test.
• Export the symbol from the package root barrel (match how siblings are exported).

3. Add the section to the brain (self-documentation)

Generate the new ## <Name> section from the scaffolded source:

python3 "${CLAUDE_PLUGIN_ROOT}/skills/_shared/scripts/sync_design_system.py" \
  --repo <repo-path> --component <Name> \
  --brain "<repo-path>/DESIGN-SYSTEM.md" \
  --create --group <core|foundational>

--create appends the section under the chosen group when it doesn't exist yet. Props come straight from the source you just wrote, so the section is verified. Then add the component's row to the Component index table near the top of the brain (name, category, import symbol, "table"). Read the script output to confirm.

Write the canonical brain at <repo-path>/DESIGN-SYSTEM.md (committed in this PR). The plugin's ${CLAUDE_PLUGIN_ROOT}/skills/_shared/DESIGN-SYSTEM.md stays in sync via the consuming workflow — never target it on writes. Tokens for any follow-on rebuild_brain.py --brain "<repo-path>/DESIGN-SYSTEM.md" come from <repo-path>/forge.config.json repo.tokensCss (passed as --tokens-css).

4. Capture corrections

If the user corrects a house pattern while reviewing, record it durably:

python3 "${CLAUDE_PLUGIN_ROOT}/skills/_shared/scripts/record_guidance.py" \
  --rule "<generalized rule>" --scope components \
  --store "${CLAUDE_PLUGIN_ROOT}/skills/_shared/references/standing-guidance.md"

5. Open the PR (into the configured base branch)

bash "${CLAUDE_PLUGIN_ROOT}/skills/_shared/scripts/open_pr.sh" \
  --repo <repo-path> --component <Name> --action create \
  --summary "Add <Name> component" \
  --paths "src/components/<Name>/ src/index.ts DESIGN-SYSTEM.md"

Always pass --paths with exactly the files you created (the component dir, the barrel, the brain) — open_pr.sh stages only those, never git add -A, so no stray working-tree file (a local .env, secrets, WIP) is swept into the PR. Use --no-push to commit without pushing.

Branch forge/create/<name>-<slug>, single commit (component + stories + test + brain section), PR into the base branch from forge.config.json git.prBase (defaults to main). If gh is absent it prints the exact commands.

After the PR opens, offer to run design:accessibility-review, design:design-critique, and design:design-handoff against the new component.

Output to the user

Report: the new component's API (prop signature), the files created, that the brain section + index row were added (verified), and the PR link (or branch + command). Don't paste the whole component — link the PR.

Prop completeness & a11y (before the PR)

• Cover the baseline props (§2.1) and the type-specific prop set (§2.2) of the standard — a new Button without loading/disabled/size, or a Select without value/onChange/multiple, is not ready.
• Event handlers pass the native event ((e) => void), never bare values.
• Implement the required ARIA for the type (§4.1): overlays get a real focus trap + restore (not a comment claiming it), alerts get aria-live, menus/tabs/sliders get roles + keyboard nav, icon-only buttons get aria-label.
• Text → canonical --text-*; sizes/spacing/radius → tokens. No raw hex/px.

Guardrails

• Never create a component that already exists — use edit-component.
• Reuse library primitives (Button/Input/etc.); never hand-roll them inside a new component.
• Match the sibling's exact tokens; never introduce a new color/type vocabulary.
• Output must match house style: prop-driven, token-referencing, typed unions, className override, ARIA + keyboard. A reviewer shouldn't be able to tell it was generated.
• Never hardcode colors/spacing when a token exists.
• Brain section + index row ship in the same commit as the code.