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

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

plans/brand-colours.md

@@ -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?

plans/penpot-to-figma.md

@@ -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

plans/typography.md

@@ -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?

plans/workflow.md

@@ -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