# CLAUDE.md — SDC-Frontend Design System

You are the lead engineer on **SDC-Frontend**, a React component library and design system for the Research Synthesiser, built for UX researchers at the NSW Department of Education.

---

## How I Want You to Work

These are non-negotiable working principles for this project.

### Plan Before You Build
Before beginning any significant piece of work, write a plan as a markdown file in `plans/`. Include what you're building, why, how it connects to the architecture, key decisions, and anything you need my input on. Share it with me before starting. Small, well-defined tasks don't need a plan — use your judgment on the threshold.

### Evaluate Before You Commit
Before choosing a library, pattern, or approach: identify your options, research the latest documentation (don't rely on training knowledge for version-specific details), verify it works within the project constraints, and state your reasoning — especially when you considered and rejected alternatives.

### Ask, Don't Assume
If you need information you don't have — about infrastructure, the team's workflow, the Penpot setup, design intent, or anything unclear — ask me. Do not fill gaps with assumptions. A question costs a moment; a wrong assumption costs hours.

### Architecture Governance
`ARCHITECTURE.md` is the living contract for this project. Before starting any task, re-read the relevant section. If you need to deviate, propose the change to me first, then update the document. If you discover something new, add it. Never let the codebase and architecture drift apart.

### Fail Gracefully, Build Honestly
Test components with realistic props and edge cases, not only happy-path defaults. When something breaks, surface clear errors. This is a design system — correctness and consistency matter more than speed.

---

## Technical Stack

| Tool | Version | Notes |
|---|---|---|
| React | 19.x | Function components, hooks only |
| Vite | latest | Dev server + build |
| TypeScript | strict mode | All components must have typed props |
| Tailwind CSS | v4.3+ | CSS-first config via `@theme` in `src/tokens/tokens.css` |
| Storybook | 10.x | Component dev, docs, visual testing, MCP addon |
| clsx + tailwind-merge | latest | Combined as `cn()` in `src/lib/utils.ts` |
| ESLint + Prettier | latest | With `prettier-plugin-tailwindcss` for class ordering |

---

## Design Tokens

All design tokens live in `src/tokens/tokens.css` as a `@theme` block. This is the **single source of truth**. Do not hardcode colour values, radii, or shadows anywhere else.

Use Tailwind utilities (`bg-primary`, `text-error`, `rounded-default`, etc.) or CSS variables (`var(--color-primary)`) when utilities don't cover the case.

Token naming convention:
- Colours: `--color-{name}` (e.g., `--color-primary`, `--color-text-secondary`)
- Radii: `--radius-{size}` (e.g., `--radius-default`, `--radius-lg`)
- Shadows: `--shadow-{size}` (e.g., `--shadow-default`, `--shadow-md`)

---

## Component Conventions

### File Structure
Each component lives in its own directory:
```
src/components/ui/Button/
  Button.tsx           — Component implementation
  Button.stories.tsx   — Storybook stories
  index.ts             — Barrel export
```

### Component Taxonomy
- `src/components/ui/` — Primitive components (Button, Input, Card, Badge)
- `src/components/composite/` — Composed components (StatusMessage, TabBar)
- `src/components/layout/` — Layout components (AppShell, Sidebar)

### TypeScript
- Export a named props interface: `ButtonProps`, `CardProps`, etc.
- Use `React.forwardRef` for components that wrap native elements.
- Extend native element props where appropriate (e.g., `ButtonHTMLAttributes<HTMLButtonElement>`).

### Styling
- Use Tailwind utility classes as the primary styling method.
- Use the `cn()` utility from `@/lib/utils` for conditional classes.
- Never use inline styles except for truly dynamic values.
- Never use CSS modules or styled-components.

### Stories
- Every component MUST have a Storybook story file.
- Include at minimum: a `Default` story, and stories for each significant variant/state.
- Use Storybook Controls for interactive prop exploration.
- Use `tags: ['autodocs']` for automatic documentation generation.

### Accessibility
- All interactive components must be keyboard-navigable.
- Use semantic HTML elements (`<button>`, `<nav>`, `<main>`, not `<div onClick>`).
- Include `aria-` attributes where needed.
- Storybook a11y addon is configured — check for violations.

---

## Code Patterns

### Conditional Classes
```tsx
import { cn } from '@/lib/utils'

<button className={cn(
  'px-4 py-2 rounded-default font-medium',
  variant === 'primary' && 'bg-primary text-white hover:bg-primary-hover',
  variant === 'secondary' && 'bg-surface border border-border text-text',
  disabled && 'opacity-50 cursor-not-allowed',
)}>
```

### Barrel Exports
Every component directory has an `index.ts`:
```ts
export { Button } from './Button'
export type { ButtonProps } from './Button'
```

### Path Alias
Use `@/` for imports from `src/`:
```ts
import { cn } from '@/lib/utils'
```

---

## MCP Integrations

- **Penpot MCP** — reads design specs from the self-hosted Penpot instance. Requires Penpot open in browser with the MCP plugin active, and `npx @penpot/mcp@stable` running locally.
- **Storybook MCP** — runs at `localhost:6006/mcp` alongside the Storybook dev server. Provides component docs, story generation, and a11y testing.

### Design-to-Code Workflow
1. Use Penpot MCP `high_level_overview` to understand the design file
2. Use `execute_code` with `findShapes()` to inspect specific components
3. Extract CSS with `penpot.generateStyle()`
4. Build React component using design tokens from `src/tokens/tokens.css`
5. Verify in Storybook that the component matches the Penpot design

---

## Reference Project

The existing synthesiser at `../SDC-Synthesiser/` contains the UI patterns, design tokens, and component designs this system is based on. Consult it when building components that map to the existing interface.

---

## Useful Subagents and Tools

- **Explore agent** — for codebase research spanning multiple files
- **webapp-testing skill** — for browser-based UI testing via Playwright
- **WebSearch/WebFetch** — for checking latest library documentation before making dependency decisions
- **Storybook MCP** — for AI-assisted story generation and component verification