# 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