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

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