---
description: Scaffold and build a new component following FA conventions and the full component lifecycle.
---

# Build Component

Create a new component following the FA design system conventions and the
component lifecycle defined in `docs/reference/component-lifecycle.md`.

## Arguments

Provide the tier and component name (e.g., `atom Button`, `molecule PriceCard`).

## Pre-flight

1. Read `docs/memory/component-registry.md` — confirm component is planned, not already in-progress
2. **Dependency check (molecules):** all constituent atoms must be `done`
3. **Dependency check (organisms):** all constituent molecules and atoms must be `done`
4. Read `docs/conventions/component-conventions.md` — follow the template
5. Read `docs/design-system.md` — understand brand context for this component
6. Read `docs/memory/token-registry.md` — know available tokens

If any dependency is not met, STOP and report what's missing.

## Build

1. Create folder: `src/components/{tier}/{ComponentName}/`
2. Create `ComponentName.tsx`:
   - Extend appropriate MUI base component props
   - All visual values from theme (never hardcode)
   - `React.forwardRef` for interactive elements
   - Forward `sx` prop
   - JSDoc on every prop
   - `displayName` set
3. Create `ComponentName.stories.tsx`:
   - `tags: ['autodocs']` in meta
   - Stories: Default, AllVariants, AllSizes, Disabled, Loading, Error, LongContent, MinimalContent
4. Create `index.ts` barrel export
5. Create component tokens in `tokens/component/{component}.json` if needed

## Verify

- Open story in Storybook at `localhost:6006`
- Confirm all stories render without errors
- Check visual appearance matches design system

## After

- Update `docs/memory/component-registry.md` — mark as `review`
- Update `docs/memory/token-registry.md` if tokens were created
- Update `docs/memory/decisions-log.md` with any design decisions