Richie
dbf6a5870d
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>
113 lines
3.9 KiB
Markdown
113 lines
3.9 KiB
Markdown
# 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
|