Initial scaffold: React 19 + Vite + TypeScript + Tailwind CSS v4 + Storybook 10

Design system and component library for the Research Synthesiser. Includes:
- Tailwind CSS v4 with @theme-based design tokens from the existing synthesiser
- Storybook 10.4 with MCP, a11y, docs, and vitest addons
- ESLint + Prettier with Tailwind class sorting
- Button component as pipeline validation
- CLAUDE.md with project principles and conventions
- ARCHITECTURE.md as living architecture document
- Penpot and Storybook MCP server configuration

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

ARCHITECTURE.md

@@ -0,0 +1,112 @@
+# 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
+
+```
+Penpot (design tool, self-hosted)
+  ↓  Penpot MCP / manual export
+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
+
+### Penpot (self-hosted at 192.168.50.211:9001)
+- MCP server runs locally via `npx @penpot/mcp@stable` (port 4401)
+- MCP plugin must be installed and active in the Penpot browser session
+- Tools available: `high_level_overview`, `execute_code`, `penpot_api_info`, `export_shape`, `import_image`
+- Design tokens in Penpot use W3C DTCG format — export as JSON, convert to `@theme` values
+
+### Storybook MCP
+- Available at `localhost:6006/mcp` when Storybook dev server is running
+- Provides: component listing, documentation retrieval, story generation, a11y testing