Richie
afba95fbaf
Replace self-hosted Penpot MCP references with the official Figma Remote MCP server (OAuth, HTTP transport). Swap placeholder semantic colours in tokens.css for the NSW Design System brand palette extracted from Figma (blues, reds, oranges, greens, greys) and add typography size tokens. 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
|
|
|
|
```
|
|
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`
|
|
|
|
### Storybook MCP
|
|
- Available at `localhost:6006/mcp` when Storybook dev server is running
|
|
- Provides: component listing, documentation retrieval, story generation, a11y testing
|