Richie
d915443b8c
Token foundation: fix 16 palette colours to match official ADS_COLORS, add 5 new palettes (teal, brown, purple, fuchsia, yellow), realign semantic tokens (primary=navy, info=bright blue), fix border radii to 8px base, add responsive heading typography. Component migration: swap primary/info references across all existing components, update Button (44px/semibold), Switch (green/compact), Chip (30px/8px radius + colour variants), SideNav (80px rail), Tag (11 colours). New components: SideNav, TopBar, Avatar, Tabs, PageHeader, Slider, RangeSlider, FileInput, DataTable, List, Autocomplete. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
163 lines
8.8 KiB
Markdown
163 lines
8.8 KiB
Markdown
# 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
|