ADS3-Design-System/ARCHITECTURE.md

ARCHITECTURE.md — ADS 3.0 Design System

This is the living architecture document for the ADS 3.0 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

ADS 3.0 Design System is a React component library implementing the ADS 3.0 (Adaptive Design System) design language. It provides tokens, primitives, and composite components as a shared foundation. Application-specific screens and domain logic belong in downstream forks of this repo.

---

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 Layers

Tokens are structured in three layers:

1. Palette — raw colour values (--color-blue-01, --color-grey-03). Not used directly in components.
2. Semantic — purpose-based aliases (--color-primary, --color-error, --color-text). General UI usage.
3. Form control — shared interactive-state tokens for all form components (--color-control-border, --color-control-checked, --color-control-label, etc.). Ensures consistent styling across Input, Checkbox, Radio, Switch, Select, and future form primitives.
4. Button — dedicated tokens for the Button component's intent system (--color-button-default, --color-button-danger, --color-button-neutral, --color-button-subtle-bg, --color-button-subtle-text).
5. Badge — status colour tokens for the Badge component's variant system (--color-badge-info, --color-badge-success, --color-badge-error, --color-badge-warning, --color-badge-neutral, --color-badge-text).
6. Chip — tokens for the Chip component's border/fill states (--color-chip-border, --color-chip-text, --color-chip-bg, --color-chip-selected-bg, --color-chip-selected-text).
7. Tag — colour tokens for the Tag component's 11-colour system (--color-tag-navy, --color-tag-blue, --color-tag-green, --color-tag-red, --color-tag-orange, --color-tag-grey, --color-tag-teal, --color-tag-brown, --color-tag-purple, --color-tag-fuchsia, --color-tag-yellow, plus -light variants for each).
8. Alert — background, border, and icon colour tokens for 5 alert variants (--color-alert-{variant}-bg, --color-alert-{variant}-border, --color-alert-{variant}-icon for info, warning, error, success, neutral).
9. Switch — dedicated on-state tokens (--color-switch-on, --color-switch-on-hover) using success green per ADS 3.0.
10. Avatar — background and text colour tokens (--color-avatar, --color-avatar-text).
11. TopBar — background colour token (--color-topbar).
12. SideNav — navigation-specific tokens (--color-nav-bg, --color-nav-text, --color-nav-icon, --color-nav-active, --color-nav-divider).

Token Categories

• Palette colours: --color-{palette}-{shade} — 10 families (blue, red, orange, green, teal, brown, purple, fuchsia, yellow, grey) × 4 shades each
• Semantic colours: --color-{purpose} (e.g., --color-primary = navy, --color-info = bright blue, --color-error, --color-text)
• Form control colours: --color-control-{role} (e.g., --color-control-border, --color-control-checked)
• Button colours: --color-button-{intent} (e.g., --color-button-default, --color-button-danger)
• Badge colours: --color-badge-{variant} (e.g., --color-badge-info, --color-badge-error)
• Chip colours: --color-chip-{role} (e.g., --color-chip-border, --color-chip-selected-bg)
• Tag colours: --color-tag-{color} and --color-tag-{color}-light (e.g., --color-tag-blue, --color-tag-blue-light)
• 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/atoms/ — Atoms

Single-purpose, atomic building blocks. Each wraps a single native element or interaction pattern with no domain logic.

• Button, IconButton
• Input, Textarea, Select, Autocomplete
• Checkbox, Radio/RadioGroup, Switch
• Slider, RangeSlider
• FileInput
• Badge, Tag, Chip
• Tabs (TabList, Tab, TabPanel)
• List (ListItem, ListSubheader, ListDivider)
• Avatar, Tooltip

src/components/molecules/ — Molecules

Small compositions of atoms into reusable units. May combine icons, text, buttons, or other atoms.

• Alert, Accordion, Card, Dialog, Popover
• DataTable

src/components/organisms/ — Organisms

Larger compositions that carry domain semantics or define page-level regions. Built from atoms and molecules.

• TopBar, SideNav, PageHeader
• (planned) AppShell (header + sidebar + content area)
• (planned) DatePicker

Which Tier Does a Component Belong To?

Question	If yes →
Does it wrap a single native element or a single interaction pattern (button, input, toggle)?	atoms/
Does it compose 2+ atoms into a reusable unit (e.g., Alert = icon + text + close button)?	molecules/
Does it carry domain-specific naming or logic (e.g., ThemeCard, ParticipantRow)?	organisms/
Does it define a page-level region or shell (header, sidebar, content area)?	organisms/

When in doubt: start in atoms/. Promote to molecules/ when a component begins importing other atoms.

---

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
• Token discipline: Components reference semantic or domain-specific tokens (form-control, button), not palette tokens. If the needed token doesn't exist, add it to tokens.css before using a raw palette value.
• 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/
│   ├── atoms/            # Single-purpose elements
│   ├── molecules/        # Small compositions of atoms
│   └── organisms/        # Domain-aware / page-level components
├── tokens/
│   └── tokens.css        # Design tokens (@theme block)
├── styles/
│   └── global.css        # Tailwind imports + base styles
├── lib/
│   └── utils.ts          # cn() utility
├── hooks/                # Custom React hooks
├── 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