From 4a79455c4dbb47b89374a497d029848acc3e137a Mon Sep 17 00:00:00 2001 From: Florian BRUNIAUX Date: Sat, 17 Jan 2026 15:34:52 +0100 Subject: [PATCH] docs(images): add wireframing tools & Figma MCP documentation - Add Wireframing Tools section (Excalidraw, tldraw, Frame0, Paper+Photo) - Add Figma MCP Integration with official setup and workflow - Add Image Optimization for Claude Vision (resolution, tokens, formats) - Create examples/mcp-configs/figma.json config template - Update reference.yaml with new entries and shifted line numbers Co-Authored-By: Claude Opus 4.5 --- CHANGELOG.md | 9 ++ examples/mcp-configs/figma.json | 13 +++ guide/ultimate-guide.md | 143 ++++++++++++++++++++++++++++++++ machine-readable/reference.yaml | 97 +++++++++++----------- 4 files changed, 215 insertions(+), 47 deletions(-) create mode 100644 examples/mcp-configs/figma.json diff --git a/CHANGELOG.md b/CHANGELOG.md index d32c954..5259754 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,15 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). ## [Unreleased] +### Added + +- **Wireframing & Figma MCP documentation** in `guide/ultimate-guide.md` (+143 lines) + - **Wireframing Tools for AI Development** (L483-518): Comparison table for Excalidraw, tldraw, Frame0, Paper+Photo with MCP support indicators + - **Figma MCP Integration** (L520-583): Official Anthropic MCP server setup, available tools (`get_design_context`, `get_variable_defs`, `get_code_connect_map`), workflow examples + - **Image Optimization for Claude Vision** (L585-624): Resolution guidelines, token calculation formula, format recommendations + - New config template: `examples/mcp-configs/figma.json` + - Updated `machine-readable/reference.yaml` with new entries and shifted line numbers + ### Changed - **Semantic search tools priority**: grepai now recommended over mgrep diff --git a/examples/mcp-configs/figma.json b/examples/mcp-configs/figma.json new file mode 100644 index 0000000..4e195e5 --- /dev/null +++ b/examples/mcp-configs/figma.json @@ -0,0 +1,13 @@ +{ + "mcpServers": { + "figma": { + "transport": "http", + "url": "https://mcp.figma.com/mcp" + }, + "figma-desktop": { + "transport": "http", + "url": "http://127.0.0.1:3845/mcp", + "comment": "Requires Figma desktop app with Dev Mode enabled" + } + } +} diff --git a/guide/ultimate-guide.md b/guide/ultimate-guide.md index 52f1999..071899b 100644 --- a/guide/ultimate-guide.md +++ b/guide/ultimate-guide.md @@ -480,6 +480,149 @@ This suggests the form field reference is incorrect. Let me check your form hand > **πŸ’‘ Pro tip**: Take screenshots of error messages, design mockups, and documentation instead of describing them textually. Visual input is often faster and more precise than written descriptions. +##### Wireframing Tools for AI Development + +When designing UI before implementation, low-fidelity wireframes help Claude understand intent without over-constraining the output. Here are recommended tools that work well with Claude Code: + +| Tool | Type | Price | MCP Support | Best For | +|------|------|-------|-------------|----------| +| **Excalidraw** | Hand-drawn style | Free | βœ“ Community | Quick wireframes, architecture diagrams | +| **tldraw** | Minimalist canvas | Free | Emerging | Real-time collaboration, custom integrations | +| **Frame0** | Low-fi + AI | Free | βœ“ | Modern Balsamiq alternative, AI-assisted | +| **Paper sketch** | Physical | Free | N/A | Fastest iteration, zero setup | + +**Excalidraw** (excalidraw.com): +- Open-source, hand-drawn aesthetic reduces over-specification +- MCP available: `github.com/yctimlin/mcp_excalidraw` +- Export: PNG recommended (1000-1200px), also SVG/JSON +- Best for: Architecture diagrams, quick UI sketches + +**tldraw** (tldraw.com): +- Infinite canvas with minimal UI, excellent SDK for custom apps +- Agent starter kit available for building AI-integrated tools +- Export: JSON native, PNG via screenshot +- Best for: Collaborative wireframing, embedding in custom tools + +**Frame0** (frame0.app): +- Modern Balsamiq alternative (2025), offline-first desktop app +- Built-in AI: text-to-wireframe, screenshot-to-wireframe conversion +- Native MCP integration for Claude workflows +- Best for: Teams wanting low-fi wireframes with AI assistance + +**Paper + Photo**: +- Seriously, this works extremely well +- Snap a photo with your smartphone β†’ paste directly in Claude Code +- Tips: Good lighting, tight crop, avoid reflections/shadows +- Claude handles rotations and hand-drawn artifacts well + +**Recommended export settings**: PNG format, 1000-1200px on longest side, high contrast + +##### Figma MCP Integration + +Figma provides an **official MCP server** (announced 2025) that gives Claude direct access to your design files, dramatically reducing token usage compared to screenshots alone. + +**Setup options**: + +```bash +# Remote MCP (all Figma plans, any machine) +claude mcp add --transport http figma https://mcp.figma.com/mcp + +# Desktop MCP (requires Figma desktop app with Dev Mode) +claude mcp add --transport http figma-desktop http://127.0.0.1:3845/mcp +``` + +**Available tools via Figma MCP**: + +| Tool | Purpose | Tokens | +|------|---------|--------| +| `get_design_context` | Extracts React+Tailwind structure from frames | Low | +| `get_variable_defs` | Retrieves design tokens (colors, spacing, typography) | Very low | +| `get_code_connect_map` | Maps Figma components β†’ your codebase | Low | +| `get_screenshot` | Captures visual screenshot of frame | High | +| `get_metadata` | Returns node properties, IDs, positions | Very low | + +**Why use Figma MCP over screenshots?** +- **3-10x fewer tokens**: Structured data vs. image analysis +- **Direct token access**: Colors, spacing values are extracted, not interpreted +- **Component mapping**: Code Connect links Figma β†’ actual code files +- **Iterative workflow**: Small changes don't require new screenshots + +**Recommended workflow**: +``` +1. get_metadata β†’ Understand overall structure +2. get_design_context β†’ Get component hierarchy for specific frames +3. get_variable_defs β†’ Extract design tokens once per project +4. get_screenshot β†’ Only when visual reference needed +``` + +**Example session**: +```bash +You: Implement the dashboard header from Figma +Claude: [Calls get_design_context for header frame] +β†’ Returns: React structure with Tailwind classes, exact spacing +Claude: [Calls get_variable_defs] +β†’ Returns: --color-primary: #3B82F6, --spacing-md: 16px +Claude: [Implements component matching Figma exactly] +``` + +**Prerequisites**: +- Figma account (Free tier works for remote MCP) +- Dev Mode seat for desktop MCP features +- Design file must be accessible to your account + +**MCP config file** (`examples/mcp-configs/figma.json`): +```json +{ + "mcpServers": { + "figma": { + "transport": "http", + "url": "https://mcp.figma.com/mcp" + } + } +} +``` + +##### Image Optimization for Claude Vision + +Understanding Claude's image processing helps optimize for speed and accuracy. + +**Resolution guidelines**: + +| Range | Effect | +|-------|--------| +| **< 200px** | Loss of precision, text unreadable | +| **200-1000px** | Sweet spot for most wireframes | +| **1000-1568px** | Optimal quality/token balance | +| **1568-8000px** | Auto-downscaled (wastes upload time) | +| **> 8000px** | Rejected by API | + +**Token calculation**: `(width Γ— height) / 750 β‰ˆ tokens consumed` + +| Image Size | Approximate Tokens | +|------------|-------------------| +| 200Γ—200 | ~54 tokens | +| 500Γ—500 | ~334 tokens | +| 1000Γ—1000 | ~1,334 tokens | +| 1568Γ—1568 | ~3,279 tokens | + +**Format recommendations**: + +| Format | Use When | +|--------|----------| +| **PNG** | Wireframes, diagrams, text, sharp lines | +| **WebP** | General screenshots, good compression | +| **JPEG** | Photos onlyβ€”compression artifacts harm line detection | +| **GIF** | Avoid (static only, poor quality) | + +**Optimization checklist**: +- [ ] Crop to relevant area only +- [ ] Resize to 1000-1200px if larger +- [ ] Use PNG for wireframes/diagrams +- [ ] Check `/status` after pasting to monitor context usage +- [ ] Consider text description if context is >70% + +> **πŸ’‘ Token tip**: A 1000Γ—1000 wireframe uses ~1,334 tokens. The same information as structured text (via Figma MCP) might use 200-400 tokens. Use screenshots for visual context, structured data for implementation. + #### Session Continuation and Resume Claude Code allows you to **continue previous conversations** across terminal sessions, maintaining full context and conversation history. diff --git a/machine-readable/reference.yaml b/machine-readable/reference.yaml index 0caed8f..f88c0b4 100644 --- a/machine-readable/reference.yaml +++ b/machine-readable/reference.yaml @@ -3,7 +3,7 @@ # Source: guide/ultimate-guide.md # Purpose: Condensed index for LLMs to quickly answer user questions about Claude Code -version: "3.8.1" +version: "3.8.2" updated: "2026-01" # ════════════════════════════════════════════════════════════════ @@ -28,52 +28,53 @@ deep_dive: architecture_mcp: "guide/architecture.md:450" architecture_philosophy: "guide/architecture.md:580" # Main guide (guide/ultimate-guide.md) - installation: 185 - first_workflow: 266 - essential_commands: 315 - permission_modes: 596 - interaction_loop: 908 - context_management: 944 - context_triage: 1058 - session_vs_memory: 1091 - plan_mode: 1458 - rewind: 1636 - mental_model: 1675 - xml_prompting: 1731 - memory_files: 2218 - claude_folder: 2349 - settings: 2400 - claudemd_injection_warning: 2510 - precedence_rules: 2622 - agents: 2720 - agent_template: 2793 - agent_examples: 2901 - agent_validation_checklist: 3116 - skills: 3279 - skill_template: 3357 - skill_examples: 3425 - commands: 3704 - command_template: 3774 - hooks: 4027 - hook_templates: 4172 - security_hooks: 4434 - mcp_servers: 4573 - mcp_config: 4771 - mcp_security: 5373 - cicd: 5329 - ide_integration: 6018 - feedback_loops: 6088 - batch_operations: 6426 - pitfalls: 6545 - git_best_practices: 6814 - cost_optimization: 7280 - commands_table: 7733 - shortcuts_table: 7766 - troubleshooting: 7892 - cheatsheet: 8265 - daily_workflow: 8341 - superclaude_modes: 8634 - learning_mode: 8645 + installation: 187 + first_workflow: 268 + essential_commands: 317 + working_with_images: 413 + wireframing_tools: 483 + figma_mcp: 520 + image_optimization: 585 + permission_modes: 751 + interaction_loop: 1063 + context_management: 1099 + context_triage: 1212 + session_vs_memory: 1245 + fresh_context_pattern: 1289 + plan_mode: 1822 + rewind: 2000 + mental_model: 2082 + xml_prompting: 2139 + memory_files: 2787 + claude_folder: 2938 + settings: 2989 + precedence_rules: 3211 + agents: 3309 + agent_template: 3382 + agent_examples: 3520 + skills: 3898 + skill_template: 3976 + skill_examples: 4044 + commands: 4323 + command_template: 4393 + hooks: 4646 + hook_templates: 4791 + security_hooks: 5053 + mcp_servers: 5194 + mcp_config: 5488 + mcp_security: 5856 + cicd: 6157 + ide_integration: 6846 + feedback_loops: 6916 + batch_operations: 7254 + pitfalls: 7373 + git_best_practices: 7642 + cost_optimization: 8108 + commands_table: 8598 + shortcuts_table: 8631 + troubleshooting: 8757 + cheatsheet: 9132 + daily_workflow: 9208 # ════════════════════════════════════════════════════════════════ # DECISION TREE (most important - en premier) @@ -160,6 +161,7 @@ context: yellow: "50-70% β†’ be selective" orange: "70-90% β†’ /compact NOW" red: "90%+ β†’ /clear required" + fresh_context: "Reset per task for long autonomous sessions - see Section 2.2 Fresh Context Pattern" symptoms: short_responses: "/compact" forgetting_instructions: "/clear" @@ -205,6 +207,7 @@ mcp: context7: "library docs lookup" sequential: "structured multi-step reasoning" playwright: "browser automation / E2E" + figma: "design file access, tokens, structure (official)" check: "/mcp" config: ".claude/mcp.json or ~/.claude.json"