ADS3-Design-System/ARCHITECTURE.md

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