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

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

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