# ARCHITECTURE.md — SDC-Frontend

This is the living architecture document for the SDC-Frontend design system. All structural decisions are recorded here. Update this document when the architecture evolves — never let the codebase and this document drift apart.

---

## 1. Overview

SDC-Frontend is a React component library and design system that will serve as the frontend for the Research Synthesiser. It is built in phases:

1. **Design system** — tokens, primitives, composite components
2. **Application screens** — the synthesiser UI rebuilt on top of the design system

---

## 2. Token Pipeline

```
Figma (design tool)
  ↓  Figma MCP / get_variable_defs
src/tokens/tokens.css (@theme block)
  ↓  Tailwind CSS v4 reads @theme
  ↓  Generates utility classes + CSS custom properties
Components (use Tailwind utilities or var() references)
  ↓  Rendered in
Storybook (visual verification)
```

### Token Categories
- **Colours**: `--color-*` (bg, surface, border, text, primary, success, warning, error)
- **Radii**: `--radius-*` (sm, default, lg, full)
- **Shadows**: `--shadow-*` (default, md)

### How Tailwind v4 @theme Works
Declaring `--color-primary: #2563eb` inside `@theme` in `tokens.css` automatically generates utilities like `bg-primary`, `text-primary`, `border-primary`. No JavaScript config file needed — the CSS file is the config.

---

## 3. Component Taxonomy

### `src/components/ui/` — Primitives
Atomic, reusable building blocks. Each is self-contained with no domain logic.
- Button, Input, Textarea, Select
- Card, Badge, Tag
- Dialog, Tooltip, Popover

### `src/components/composite/` — Composed Components
Built from primitives, may carry light domain semantics.
- StatusMessage (success/error/warning/info)
- TabBar, TabPanel
- ThemeCard (maps to synthesiser's theme display)

### `src/components/layout/` — Layout
Page-level structural components.
- AppShell (header + sidebar + content area)
- PageHeader

---

## 4. Styling Approach

- **Primary**: Tailwind utility classes
- **Conditional classes**: `cn()` from `@/lib/utils` (clsx + tailwind-merge)
- **Token values**: Always from `src/tokens/tokens.css`, never hardcoded
- **No CSS modules, no styled-components, no inline styles** (except truly dynamic values)
- **Class ordering**: Enforced by `prettier-plugin-tailwindcss`

---

## 5. Storybook Conventions

- Every component has a co-located `.stories.tsx` file
- All stories use `tags: ['autodocs']` for auto-generated docs
- Stories cover: default state, all variants, edge cases, disabled/error states
- A11y addon runs on all stories — violations should be addressed
- MCP addon enabled at `localhost:6006/mcp` for AI-assisted development

---

## 6. Project Structure

```
src/
├── components/
│   ├── ui/               # Primitives
│   ├── composite/        # Composed components
│   └── layout/           # Layout components
├── tokens/
│   └── tokens.css        # Design tokens (@theme block)
├── styles/
│   └── global.css        # Tailwind imports + base styles
├── lib/
│   └── utils.ts          # cn() utility
├── hooks/                # Custom React hooks
├── pages/                # App screens (Phase 2)
├── App.tsx               # Root component
└── main.tsx              # Vite entry point
```

---

## 7. Design Tool Integration

### Figma
- Project file: https://www.figma.com/design/mrabO6AtxN3ektGiTk0I9c/ResearchInsights (file key: `mrabO6AtxN3ektGiTk0I9c`)
- MCP server: Official Figma Remote MCP at `https://mcp.figma.com/mcp` (HTTP transport, OAuth auth)
- Key tools: `get_design_context`, `get_variable_defs`, `get_screenshot`, `search_design_system`, `use_figma`
- Design tokens extracted via `get_variable_defs` → mapped to `@theme` values in `tokens.css`

### Code Connect
- Links Figma components to their React implementations
- Once linked, `get_design_context` returns actual component code instead of generic markup
- Mapped as we build each component via `add_code_connect_map` (label: "React")

### Storybook MCP
- Available at `localhost:6006/mcp` when Storybook dev server is running
- Provides: component listing, documentation retrieval, story generation, a11y testing
- `@storybook/addon-designs` embeds Figma frames in the story panel for side-by-side comparison
- `@storybook/addon-mcp` serves the MCP endpoint

### claude2figma Skills
- 4 skills in `.claude/skills/` that enforce design system compliance when writing to Figma
- **figma-preflight**: Validates MCP connection, audits libraries, builds a Token Map of all styles/variables
- **component-rules**: Library-first lookup, Auto Layout conventions, semantic node naming
- **figma-style-binding**: All visual values must bind to Figma Styles or Variables, never hardcoded; includes post-write QA
- **reference-interpreter**: Converts screenshots/references into structured Design Briefs mapped to design tokens