ADS3-Design-System/plans/penpot-to-figma.md

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