figma-blueprint

Figma Blueprint

Generate FigJam architectural diagrams from codebase analysis. Explore source code and documentation, extract architectural patterns, convert to Mermaid syntax, and push to FigJam via Figma MCP tools.

When to Use

• User wants visual architecture diagrams derived from their codebase
• User mentions "figma", "diagram", "visualize architecture", "architecture to figma"
• User provides docs (PRD, system design, implementation plans) they want turned into visual boards
• User wants to update existing FigJam boards with current codebase state

Workflow

Phase 1 — Codebase Exploration

Delegate exploration to a sub-agent (subagent_type: Explore) to avoid polluting the main context. The sub-agent should:

1. Read source files, not just list them — extract class names, function signatures, module relationships
2. Read documentation — PRD, architecture docs, implementation plans, test frameworks
3. Read configuration — docker-compose, CI/CD, infrastructure configs
4. Return a structured summary of: components, layers, data flows, dependencies, and infrastructure

Provide the sub-agent with a thorough prompt specifying exactly what to extract. Target architectural structure, not implementation details.

Phase 2 — Diagram Identification

From the exploration results, identify diagram candidates. Common diagram types:

Type	Mermaid Syntax	Best For
System architecture	flowchart TB/LR	Layer stacks, component relationships
Data flow	flowchart LR	Memory tiers, message pipelines
Sequence diagram	sequenceDiagram	Request flows, message handling
Timeline/Roadmap	gantt	Phase planning, milestones
Component detail	flowchart TB with subgraphs	Zoomed-in subsystem views

Prioritize diagrams that show relationships not obvious from reading individual files.

Phase 3 — Mermaid Conversion

Convert each diagram candidate to Mermaid syntax. Guidelines:

• Use subgraph sections for logical groupings (layers, tiers, services)
• Add meaningful labels with key specs (latency targets, TTLs, port numbers)
• Apply color coding via style directives to distinguish component categories
• Keep node labels concise — full details belong in the docs, not the diagram
• For sequence diagrams, show the happy path first; edge cases are secondary

Phase 4 — FigJam Generation

Two paths depending on whether boards exist:

New boards — Use generate_diagram (from either mcp__claude_ai_Figma__generate_diagram or mcp__plugin_figma_figma__generate_diagram):

• Each call creates a separate FigJam board
• Returns a claim URL the user must open to save the board to their account
• Present all claim links in a clear numbered list with descriptions

Existing boards — Use use_figma (requires the figma:figma-use skill loaded first):

• Write directly to existing FigJam boards via file key
• No claim links needed — changes appear immediately
• Prefer the local plugin (plugin:figma:figma) for direct read/write

Figma MCP priority: Prefer the local plugin (plugin:figma:figma) over the Claude.ai built-in (claude.ai/Figma) when both are available. The local plugin provides direct OAuth-based access without claim links for existing boards.

Phase 5 — Persistence (Optional)

Save board references to project memory for future sessions:

1. Write a reference memory file with board URL, file key, root node ID, and content description
2. Update MEMORY.md index with a one-liner pointer

This enables future sessions to read/update boards without the user re-sharing URLs.

Diagram Candidates Checklist

When exploring a codebase, look for these architectural patterns:

• System layers — How do components stack? (ingestion → processing → storage)
• Data tiers — Memory hierarchy, caching strategy, promotion/eviction flows
• Message/request flow — End-to-end path from user input to response
• Infrastructure — Docker services, databases, monitoring, networking
• Deployment — Environments, CI/CD pipeline, cloud architecture
• Roadmap — Development phases, milestones, dependencies between phases
• Component internals — Zoomed-in views of complex subsystems

Additional Resources

Reference Files

• references/mermaid-patterns.md — Common Mermaid syntax patterns optimized for FigJam rendering, including color schemes, subgraph layouts, and connector styles that render well in FigJam