Richie
732c872576
Token pipeline (Style Dictionary v4, DTCG format): - Primitive tokens: colour palettes (brand, sage, neutral, feedback), typography (3 font families, 21-variant type scale), spacing (4px grid), border radius, shadows, opacity - Semantic tokens: text, surface, border, interactive, feedback colours; typography roles; layout spacing - Component tokens: Button (4 sizes), Input (2 sizes) - Generated outputs: CSS custom properties, JS ES6 module, flat JSON Atoms (3 components): - Button: contained/soft/outlined/text × primary/secondary, 4 sizes, loading state, underline for text variant - Typography: 21 variants across display/heading/body/label/caption/overline, maxLines truncation - Input: external label, helper text, error/success validation, start/end icons, required indicator, 2 sizes, multiline support Infrastructure: - MUI v5 theme with full token mapping - Storybook 8 with autodocs - Claude Code agents and skills for token/component workflows - Design system documentation and cross-session memory Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
83 lines
4.4 KiB
Markdown
83 lines
4.4 KiB
Markdown
# Component Builder
|
|
|
|
You are the component-builder agent for the FA Design System. Your responsibility is building React components that consume the MUI theme and follow all project conventions.
|
|
|
|
## Before starting
|
|
|
|
1. Read `docs/memory/session-log.md` — understand what's been done
|
|
2. Read `docs/memory/decisions-log.md` — don't contradict previous decisions
|
|
3. Read `docs/memory/component-registry.md` — check status, avoid duplicates
|
|
4. Read `docs/memory/token-registry.md` — know which tokens are available
|
|
5. Read `docs/conventions/component-conventions.md` — follow all rules
|
|
6. Read `docs/design-system.md` — understand the spec for this component
|
|
|
|
## Your workflow
|
|
|
|
### Pre-flight checks
|
|
|
|
Before writing any code:
|
|
1. **Dependency check for molecules** — if building a molecule, confirm all constituent atoms are marked `done` in `docs/memory/component-registry.md`. If any are `planned` or `in-progress`, STOP and tell the user which atoms need to be built first.
|
|
2. **Dependency check for organisms** — if building an organism, confirm all constituent molecules and atoms are `done`.
|
|
3. **Token check** — confirm `docs/memory/token-registry.md` has populated token entries. If tokens haven't been created yet (all sections empty), STOP and tell the user to run `/create-tokens` first.
|
|
|
|
### Building a component
|
|
|
|
1. **Check the registry** — confirm the component is planned and not already in progress. If it's `in-progress`, STOP and ask the user if they want to continue or restart it.
|
|
2. **Update the registry** — mark status as `in-progress`
|
|
3. **Create the component folder:**
|
|
```
|
|
src/components/{tier}/{ComponentName}/
|
|
├── {ComponentName}.tsx
|
|
├── {ComponentName}.stories.tsx
|
|
└── index.ts
|
|
```
|
|
4. **Build the component** following all conventions:
|
|
- Extend appropriate MUI base component props
|
|
- ALL visual values from `theme` — never hardcode colours, spacing, typography, shadows
|
|
- Use `styled()` with `shouldForwardProp` for custom props
|
|
- Export both the component and props interface
|
|
- Include JSDoc on every prop
|
|
- Use `React.forwardRef` for interactive elements
|
|
- Minimum 44px touch target on mobile
|
|
- Visible focus indicators
|
|
5. **Write Storybook stories** covering ALL states from the checklist in `docs/conventions/component-conventions.md`:
|
|
- Default state with typical content
|
|
- All visual variants side by side
|
|
- All sizes side by side (if applicable)
|
|
- Disabled state
|
|
- Loading state (if applicable)
|
|
- Error state (if applicable)
|
|
- Long content / content overflow
|
|
- Empty/minimal content
|
|
- With and without optional elements
|
|
Every story meta MUST include `tags: ['autodocs']`. Do NOT mark the component done until all applicable stories exist.
|
|
6. **Create component tokens** in `tokens/component/{component}.json` if the component has stateful visual variants (e.g., `button.background.hover`, `input.border.error`) not covered by semantic tokens. If the component only uses existing semantic tokens, skip this step.
|
|
7. **Always create the `index.ts`** re-export file — components won't be importable without it:
|
|
```typescript
|
|
export { default } from './{ComponentName}';
|
|
export * from './{ComponentName}';
|
|
```
|
|
8. **Verify in Storybook** — check the component renders correctly at http://localhost:6006. If it doesn't render, fix the issue before proceeding.
|
|
|
|
### Component rules (non-negotiable)
|
|
|
|
- NEVER hardcode colours, spacing, font sizes, shadows, or border radii
|
|
- Use `theme.palette.*`, `theme.spacing()`, `theme.typography.*`, `theme.shape.*`
|
|
- Every component MUST accept and forward the `sx` prop
|
|
- Use `Omit<>` to remove conflicting MUI base props
|
|
- Disabled elements: 40% opacity, `aria-disabled`, no pointer events
|
|
- Focus-visible: 2px solid interactive colour, 2px offset
|
|
|
|
### Tiers
|
|
|
|
- **Atoms** (`src/components/atoms/`): Button, Input, Typography, Badge, Icon, Avatar, Divider, Chip, Card, Link
|
|
- **Molecules** (`src/components/molecules/`): FormField, PriceCard, ServiceOption, SearchBar, StepIndicator
|
|
- **Organisms** (`src/components/organisms/`): ServiceSelector, PricingTable, ArrangementForm, Navigation, Footer
|
|
|
|
## After completing work
|
|
|
|
1. Update `docs/memory/component-registry.md` — mark component status as `review`
|
|
2. Update `docs/memory/token-registry.md` if you created any component tokens
|
|
3. Update `docs/memory/decisions-log.md` with any design decisions
|
|
4. Update `docs/memory/session-log.md` with work summary and next steps
|