---
name: build-component
description: >
  One-shot entry point for the full Figma-to-production component workflow:
  extract design tokens, scaffold the component with the correct adapter, run
  the accessibility gate, and optionally open a design review. Pass a Figma URL
  or work from the active Figma selection.
---

# /build-component

Build a production-ready, accessible, design-system-compliant component from a Figma design
in a single command. Orchestrates `design-token-extract`, `figma-component-scaffold`, and
`component-a11y-gate` in sequence.

## Syntax

```
/build-component [figma-url] [options]
```

## Options

| Option | Values | Default | Description |
|---|---|---|---|
| `--adapter` | `react`, `razor`, `astro`, `vue`, `sitecore`, `optimizely`, `umbraco` | `react` | Output rendering layer |
| `--tokens` | file path | auto-detect | Path to the project token file; extracted and updated if stale |
| `--css-strategy` | `modules`, `tailwind`, `custom-properties` | `modules` | CSS output (React/Astro) |
| `--story` | flag | off | Generate a Storybook story |
| `--output` | directory | `./src/components/` | Where to write generated component files |
| `--modes` | comma-separated | `light` | Figma Variable modes to sync during token extraction |
| `--skip-tokens` | flag | off | Skip token extraction; use existing token file as-is |
| `--skip-a11y` | flag | off | Skip the accessibility gate (not recommended) |
| `--review` | flag | off | Run the `component-reviewer` agent after generation |
| `--dry-run` | flag | off | Show what would be generated without writing files |

## Examples

```bash
# Default: React, CSS Modules, from current Figma selection
/build-component

# Sitecore component from Figma URL, with Storybook story
/build-component https://figma.com/file/DS123?node-id=42-88 --adapter sitecore --story

# Umbraco Razor component, dark-mode tokens included, design review on completion
/build-component https://figma.com/file/DS123?node-id=99-12 --adapter umbraco --modes light,dark --review

# Tailwind React component, skip token extraction (tokens already up to date)
/build-component --adapter react --css-strategy tailwind --skip-tokens

# Dry run to preview what would be generated
/build-component https://figma.com/file/DS123?node-id=42-88 --dry-run
```

## What this command does

### Step 1 — Token sync (unless --skip-tokens)

Runs `design-token-extract` to check the project token file against Figma Variables.
- If the token file is missing: extracts the full token set from Figma and writes it.
- If the token file exists: runs `design-system-sync` to check for drift and update stale values.
- Validates contrast for all semantic color pairs before proceeding.
- **Stops if contrast regressions are found** — reports them and asks whether to continue.

### Step 2 — Component scaffold

Runs `figma-component-scaffold` with the resolved `--adapter` and `--output` options:
- Reads design context and variable definitions from the Figma MCP
- Resolves all color/spacing/typography values to token references
- Generates the component file(s) in the target adapter's idiom
- Generates a Storybook story if `--story` is set

### Step 3 — Accessibility gate

Runs `component-a11y-gate` on the generated files:
- Validates contrast pairs using the project token file
- Checks ARIA roles, keyboard interaction model, focus styles
- Produces a PASS/FAIL verdict

If any **critical** findings are reported: marks the build as **failed** and lists the findings
that must be resolved. Does not write the component files to their final output path.

If only **advisory** findings: writes the files, lists the advisories inline, and suggests
running `/component-a11y-gate` again after addressing them.

### Step 4 — Design review (--review)

If `--review` is set, invokes the `component-reviewer` agent to compare the generated code
against the Figma specification and the project's design-system conventions.

## Output

```
## Build Component Summary

**Component:** <ComponentName>
**Figma source:** <url>
**Adapter:** <adapter>

### Files written
  - src/components/<ComponentName>/<ComponentName>.tsx
  - src/components/<ComponentName>/<ComponentName>.module.css
  - src/components/<ComponentName>/index.ts
  - src/components/<ComponentName>/<ComponentName>.stories.tsx (if --story)

### Token sync
  - Status: UP TO DATE / UPDATED (N changes applied) / SKIPPED
  - Contrast: PASS / BLOCKED (N regressions — see above)

### Accessibility gate
  - Verdict: PASS / APPROVED WITH ADVISORY / BLOCKED
  - Critical: N | Serious: N | Moderate: N | Minor: N

### Next steps
  - [ ] Resolve N advisory findings (listed above)
  - [ ] Import tokens/tokens.css in global stylesheet if not already done
  - [ ] Add component to the project's component index
  - [ ] Run /accessibility-wcag-scan on the rendered component in a browser
```

## First-time project setup

If this is the first time running `/build-component` in a project, the command will:

1. Detect missing token file and prompt for the Figma library URL
2. Run a full `design-token-extract` to bootstrap the token layer
3. Generate `tokens/tokens.css` — add an import to your global stylesheet:
   ```css
   @import 'tokens/tokens.css';
   ```
4. Generate `tokens/tokens.json` — commit this alongside your first component

## Platform notes

### Sitecore XM Cloud
The generated component uses Sitecore JSS field types. Register it in your Sitecore rendering
item and map fields in the content tree before testing in the Experience Editor.

### Optimizely Content Cloud
The generated component is a block component. Register the content type in your Startup.cs
`services.AddOptimizelyContentDefinition()` call.

### Umbraco
The generated ViewComponent must be registered. Add it to your `_ViewImports.cshtml` tag helper
registration and configure the Block Editor allowed block types in the backoffice.