richie/ADS3-Design-System
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add project plans for brand colours, typography, workflow, and Figma migration

Browse Source 
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Richie
2026-05-21 11:56:10 +10:00
parent 40d53f86dd
commit 0e1b06b376
4 changed files with 346 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

73
plans/brand-colours.md Normal file
View File

@@ -0,0 +1,73 @@
# Plan: Brand Colour Tokens
## What
Replace the placeholder design tokens in `src/tokens/tokens.css` with the actual brand colour palette from Figma, and extrapolate additional variants for extended UI use.
## Why
The current tokens use generic blues/greens — they don't match the project's brand. The Figma palette defines the canonical colours; we need to mirror those names and extend them with hover/active/background variants for component development.
## Approach
### 1. Palette layer — mirror Figma names exactly
These are the base brand colours, named to match Figma:
| Token | Hex (estimated from screenshot) | Notes |
|---|---|---|
| `--color-blue-01` | `#002664` | Deep navy (primary dark) |
| `--color-blue-02` | `#146CFD` | Bright blue (primary) |
| `--color-blue-03` | `#69B3E7` | Sky blue |
| `--color-blue-04` | `#CBEDFD` | Ice blue |
| `--color-red-01` | `#3E0014` | Dark burgundy/maroon |
| `--color-red-02` | `#D7153A` | Crimson (primary red) |
| `--color-red-03` | `#F5C5D0` | Soft pink |
| `--color-red-04` | `#FDDDE5` | Pale pink |
| `--color-grey-01` | `#3D3D3D` | Darkest grey |
| `--color-grey-02` | `#6D7278` | Medium grey |
| `--color-grey-03` | `#C0C0C0` | Light grey |
| `--color-grey-04` | `#E0E0E0` | Lighter grey |
| `--color-off-white` | `#F4F4F4` | Off white |
| `--color-surface` | `#FAFAFA` | Surface |
| `--color-white` | `#FFFFFF` | White |
| `--color-orange-02` | `#EC6608` | Warning orange (light mode) |
| `--color-orange-03` | `#F5B98A` | Warning orange (dark mode) |
| `--color-green-02` | `#00A651` | Success green (light mode) |
| `--color-green-03` | `#89E5B3` | Success green (dark mode) |
### 2. Extrapolated variants
For each colour family, generate useful variants not in Figma:
- **Orange 01** (dark) and **Orange 04** (light bg) — fill the gaps in the orange scale
- **Green 01** (dark) and **Green 04** (light bg) — fill the gaps in the green scale
- **Blue 05** — ultra-light blue for backgrounds
- **Red 05** — ultra-light red for backgrounds
- **Hover/active states** — slightly darker/lighter versions of primary interactive colours
### 3. Semantic mapping layer
Map palette colours to semantic roles so components use intent-based tokens:
```
--color-primary → blue-01
--color-primary-hover → derived (darker blue-01)
--color-primary-light → blue-04
--color-text → grey-01
--color-text-secondary → grey-02
--color-border → grey-04
--color-bg → off-white
--color-error → red-02
--color-error-bg → red-04
--color-warning → orange-02
--color-warning-bg → orange-04
--color-success → green-02
--color-success-bg → green-04
--color-info → blue-02
--color-info-bg → blue-04
```
## Key decisions needed from you
1. **Hex accuracy** — These are my best estimates from the screenshot. Can you verify any of these, or should I proceed and we refine later?
2. **Dark mode** — The Figma shows light/dark mode status colours. Should we set up CSS custom property dark mode switching now, or defer and just define all the values?
3. **Semantic vs palette** — Do you want components to reference palette names (`bg-blue-01`) or semantic names (`bg-primary`), or both?

49
plans/penpot-to-figma.md Normal file
View File

@@ -0,0 +1,49 @@
# Penpot → Figma Migration Plan
## Context
Penpot MCP has been unreliable (plugin disconnects, "Server not initialized" errors on session resumption). Pivoting to Figma for the design-to-code workflow.
- **Figma project**: https://www.figma.com/design/mrabO6AtxN3ektGiTk0I9c/ResearchInsights
- **File key**: `mrabO6AtxN3ektGiTk0I9c`
## Figma MCP Server Choice
**Official Figma Remote MCP Server** (`https://mcp.figma.com/mcp`)
| Aspect | Detail |
|--------|--------|
| Transport | HTTP (Streamable HTTP) |
| Auth | OAuth browser flow (no PAT support) |
| Rate limits | 200 calls/day, 10-15/min on Pro; free during beta |
| Read tools | `get_design_context`, `get_metadata`, `get_screenshot`, `get_variable_defs`, `get_code_connect_map`, `search_design_system`, `get_libraries` |
| Write tools | `use_figma`, `create_new_file`, `upload_assets` |
| Setup | `claude mcp add --scope user --transport http figma https://mcp.figma.com/mcp` |
**Why official over community options**: We need `get_variable_defs` (token extraction), `get_design_context` (component specs), and `search_design_system` (library search). The Framelink community server only has 2 read-only tools. The official server covers our design system workflow end-to-end.
**Fallback**: If rate limits or OAuth issues arise, Framelink (`figma-developer-mcp`) uses a PAT with no daily call limits.
## Changes
### Documentation updates (automated)
- `ARCHITECTURE.md` — Replace Penpot section with Figma, update token pipeline diagram
- `CLAUDE.md` — Replace Penpot MCP section with Figma MCP, update design-to-code workflow
### Settings cleanup (automated)
- `.claude/settings.json` — Replace Penpot WebFetch domains with Figma domains
- `.claude/settings.local.json` — Remove Penpot debugging artifacts and exposed MCP token
### Memory updates (automated)
- Replace `project-penpot-setup.md` with `project-figma-setup.md`
- Update `MEMORY.md` index
### User actions (manual)
1. Remove Penpot MCP: `claude mcp remove penpot`
2. Add Figma MCP: `claude mcp add --scope user --transport http figma https://mcp.figma.com/mcp`
3. Authenticate when prompted (OAuth browser flow)
## What stays the same
- All CSS/token work (tokens.css, typography.css, global.css) — design-tool-agnostic
- Storybook MCP — unchanged
- Component conventions, file structure, TypeScript patterns — unchanged
- Brand colours already in tokens.css — unchanged

74
plans/typography.md Normal file
View File

@@ -0,0 +1,74 @@
# Typography System Plan
## What we're building
A complete typography token set for the design system, sourced from the NSW Design System style guide (desktop, >= 960px), expanded with missing styles for a well-balanced type system.
## Font Family
**Public Sans** — the NSW Government typeface. Self-hosted via `@fontsource-variable/public-sans` (weights 100–900, normal + italic).
Fallback stack: `'Public Sans', system-ui, sans-serif`
## Typography Scale
### From the style guide (12 styles)
| Style | Class | Weight | Size | Line Height | Notes |
|-------|-------|--------|------|-------------|-------|
| Heading 1 | text-h1 | 700 | 48px | 1.25 | |
| Heading 2 | text-h2 | 700 | 32px | 1.25 | |
| Heading 3 | text-h3 | 700 | 24px | 1.333 | |
| Heading 4 | text-h4 | 700 | 20px | 1.4 | |
| Heading 5 | text-h5 | 700 | 16px | 1.5 | |
| Intro | text-intro | 400 | 20px | 1.4 | Lead paragraph |
| Body Strong | text-body-strong | 700 | 16px | 1.5 | |
| Body | text-body | 400 | 16px | 1.5 | |
| Small Strong | text-small-strong | 700 | 14px | 1.357 | |
| Small | text-small | 400 | 14px | 1.357 | |
| Body Link | text-body-link | 700 | 16px | 1.5 | Underlined, Blue 02 |
| Small Link | text-small-link | 700 | 14px | 1.357 | Underlined, Blue 02 |
### New additions (4 styles)
| Style | Class | Weight | Size | Line Height | Rationale |
|-------|-------|--------|------|-------------|-----------|
| Heading 6 | text-h6 | 700 | 14px | 1.43 | Completes heading hierarchy; same size as Small but bold, sits between H5 and body |
| Label | text-label | 500 | 14px | 1.43 | Form labels — medium weight distinguishes from body text without being as heavy as bold. The user called this out as missing |
| Caption | text-caption | 400 | 12px | 1.5 | Metadata, timestamps, helper text. Introduces 12px to the scale |
| Overline | text-overline | 700 | 12px | 1.5 | Category tags, section labels. Uppercase + 0.05em letter-spacing |
**Total: 16 styles**
## Size scale summary
48 → 32 → 24 → 20 → 16 → 14 → 12 (px)
## Implementation
### 1. tokens.css — Add to @theme block
- `--font-sans` for the font family
- `--text-{name}` + `--text-{name}--line-height` for each size/line-height pair (Tailwind v4 convention — gives us `text-h1`, `text-body`, etc. utilities automatically)
- Font weights don't need custom tokens — Tailwind's built-in `font-normal` (400), `font-medium` (500), `font-bold` (700) cover our needs
### 2. typography.css — Composed utility classes
Create `src/tokens/typography.css` with `@utility` directives for styles that combine multiple properties:
- `text-body-strong`, `text-small-strong` (size + weight)
- `text-body-link`, `text-small-link` (size + weight + underline + colour)
- `text-overline` (size + weight + uppercase + letter-spacing)
- `text-label` (size + weight)
This keeps the @theme block as raw tokens and the utilities as compositions.
### 3. Load Public Sans
Add Google Fonts import to `index.html` or `src/index.css`. Google Fonts is fine for dev; can revisit self-hosting later if needed for production/privacy.
### 4. Figma — Typography styles
Create typography styles in the Figma design file via MCP so designers can apply them from the styles panel.
## Key decisions
- **Public Sans via Google Fonts** — simplest path; the font is open source (OFL) so self-hosting later is trivial.
- **Tailwind v4 `--text-*` naming** — gives us free utility classes. Composed styles go in a separate file to keep tokens.css clean.
- **No `text-xs`/`text-sm`/`text-lg` scale aliases** — the semantic names (`text-body`, `text-caption`) are clearer for a design system. Tailwind defaults still work if needed.
- **Medium (500) for Label** — distinguishes from Regular body text without being as heavy as Bold headings. Common pattern in Material Design, Atlassian DS, etc.
## Questions for Richie
1. **Font loading**: Google Fonts import in `index.html`, or self-host from the start?
2. **Does this expanded set look right?** Any styles you want to add or remove?

150
plans/workflow.md Normal file
View File

@@ -0,0 +1,150 @@
# Workflow Plan — Figma + Code + Storybook
## Problem
We have three tools — Figma (design), code (React/Tailwind/TypeScript), and Storybook (component dev/docs/testing) — plus MCP servers for both Figma and Storybook. We need a clear process for how these connect as we build components, and what tooling/skills are worth adding to streamline things.
---
## Two Entry Points, One Loop
Components can start from either direction — the key is that both converge on the same verification and linking steps.
### Entry A: Design-First (Figma → React)
Richie has designed a component in Figma. We implement it in code.
1. **Inspect** — `get_design_context` on the Figma node returns reference code, a screenshot, and metadata.
2. **Extract tokens** — `get_variable_defs` pulls colours, spacing, typography values. Cross-check against `tokens.css` to confirm tokens exist or flag gaps.
3. **Check existing components** — Storybook MCP `get-documentation` lists what we've already built. Reuse before rebuilding.
4. **Build** — React component with TypeScript props, Tailwind utilities via `cn()`, tokens from `tokens.css`.
5. **Story** — Write stories using Storybook MCP `get-storybook-story-instructions` to match current conventions. Cover default, variants, edge cases.
6. **Test** — Storybook MCP `run-story-tests` for rendering + a11y. Fix violations before moving on.
7. **Visual verify** — `get_screenshot` from Figma vs Storybook preview. Compare side-by-side.
8. **Link** — `add_code_connect_map` to link the Figma component to the React component.
9. **Embed** — Add `addon-designs` parameter to the story pointing back to the Figma source.
### Entry B: Code-First (React → Figma)
Claude builds a component from a description or reference. We push it to Figma for Richie to review.
1. **Build** — React component in code, using design tokens from `tokens.css`.
2. **Story** — Write stories, verify in Storybook (same as steps 5-6 above).
3. **Push to Figma** — `use_figma` to create the component/frame/variants. The claude2figma skills enforce token binding here — no hardcoded values.
4. **Verify** — `get_screenshot` to confirm it landed correctly.
5. **Link** — `add_code_connect_map` to bridge it back.
6. **Embed** — Add `addon-designs` parameter to the story.
We used this flow when creating the typography specimen frame.
### The Shared End State
Regardless of entry point, every finished component has:
- A React implementation with typed props and Tailwind styling
- Storybook stories with autodocs, variants, and a11y coverage
- A Figma representation using bound tokens/variables
- A Code Connect link bridging the two
- An `addon-designs` embed in its story for side-by-side comparison
---
## Where Storybook Fits in Both Directions
Storybook isn't just for docs — with its MCP server it becomes the **verification layer** in both directions:
| Capability | MCP Tool | When to use |
|---|---|---|
| List existing components | `list-all-documentation` | Before building anything — check what exists |
| Get component API | `get-documentation` | When composing or extending existing components |
| Story conventions | `get-storybook-story-instructions` | When writing new stories — ensures consistency |
| Visual preview | `preview-stories` | After building — visual confirmation in-context |
| Test + a11y | `run-story-tests` | After every component build — catches violations early |
### Addon: `@storybook/addon-designs`
Embeds Figma frames directly in the Storybook addon panel. Each story can link to its Figma source:
```tsx
parameters: {
design: {
type: 'figma',
url: 'https://www.figma.com/design/mrabO6AtxN3ektGiTk0I9c/ResearchInsights?node-id=...',
},
},
```
This creates a permanent link between implementation and design intent — developers see the spec alongside the rendered component without switching tools.
Both addons are installed and registered in `.storybook/main.ts`.
---
## Code Connect — The Bridge Layer
Code Connect is the most important piece we haven't set up yet. It links Figma components to their React implementations, so:
- `get_design_context` returns our actual component code instead of generic markup
- Designers see real implementation details in Figma's Dev Mode
- The mapping grows as we build — each new component strengthens the bridge
**Setup:**
1. As we build each component, call `add_code_connect_map` with label "React"
2. For existing components, use `get_code_connect_suggestions` to get AI-suggested mappings
3. Periodically run `get_code_connect_map` to audit coverage
---
## Skills and Tooling to Add
### Adopt now
| Skill | What it does | Why |
|---|---|---|
| **claude2figma** (4 skills) | Preflight reads all tokens/styles/components before writing; Component Rules enforces library instance usage; Style Binding binds colours/text/spacing to variables with QA; Reference Interpreter parses design references into structured briefs | Directly solves token fidelity when writing to Figma. Prevents hardcoded values. |
| **Built-in /simplify** | Three parallel review agents check reuse, quality, efficiency | Already available. Run after building each component. |
| **Built-in /review** | Code correctness review | Already available. Run before committing. |
| **Built-in /verify** | Launches the app and confirms the change works visually | Already available. Use for visual confirmation. |
### Evaluate
| Skill | What it does | Verdict |
|---|---|---|
| **Storybook docs skill** (thebushidocollective) | Generates comprehensive Storybook docs with MDX, autodocs, JSDoc | Test whether it adds value beyond Storybook MCP's built-in `get-storybook-story-instructions`. May be redundant. |
| **A11y audit skill** | WCAG compliance, screen reader support, keyboard navigation | The Storybook a11y addon + `run-story-tests` already covers per-component checks. An audit skill would add value for periodic full-system sweeps. |
### Skip
| Skill | Why skip |
|---|---|
| **frontend-design** (Anthropic) | We're implementing an existing NSW design system, not making creative aesthetic choices |
| **awesome-design-md** | We have our own design language from Figma |
| **React specialist subagent** | CLAUDE.md already covers these conventions |
---
## The Component Build Checklist
Regardless of entry point, every component should pass through these gates:
```
[ ] Design reference exists (Figma frame OR code-first build)
[ ] Tokens checked (get_variable_defs vs tokens.css — flag gaps)
[ ] Existing components checked (Storybook MCP list-all-documentation)
[ ] React component built (TypeScript, Tailwind, cn(), forwardRef)
[ ] Stories written (default + variants + edge cases + autodocs)
[ ] Tests pass (Storybook MCP run-story-tests, including a11y)
[ ] Visual verified (Figma screenshot vs Storybook side-by-side)
[ ] Figma representation exists (designed by Richie OR pushed via use_figma)
[ ] Code Connect linked (add_code_connect_map, label: React)
[ ] Figma embed in story (addon-designs parameter)
[ ] /simplify run
```
---
## Decisions Made
- **claude2figma skills** — Installed (4 skills in `.claude/skills/`)
- **Storybook addons** — `addon-designs` + `addon-mcp` installed and registered
- **Code Connect** — Link as we build, regardless of entry point
- **Build order** — Start with primitives, work up to composites then layouts