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 <noreply@anthropic.com>
2026-01-17 15:34:52 +01:00 · 2026-01-17 15:34:52 +01:00 · 4a79455c4d
commit 4a79455c4d
parent d7c29f49c9
4 changed files with 215 additions and 47 deletions
--- 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
--- a/examples/mcp-configs/figma.json
+++ 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"
+    }
+  }
+}
--- 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.
--- 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"