diff --git a/plans/brand-colours.md b/plans/brand-colours.md new file mode 100644 index 0000000..7668014 --- /dev/null +++ b/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? diff --git a/plans/penpot-to-figma.md b/plans/penpot-to-figma.md new file mode 100644 index 0000000..c5884b1 --- /dev/null +++ b/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 diff --git a/plans/typography.md b/plans/typography.md new file mode 100644 index 0000000..5e737ee --- /dev/null +++ b/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? diff --git a/plans/workflow.md b/plans/workflow.md new file mode 100644 index 0000000..f134861 --- /dev/null +++ b/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