From 49525fc6c89529cbf3a775549fc36d4b9c16d49f Mon Sep 17 00:00:00 2001 From: Vadym Samoilenko Date: Fri, 15 May 2026 10:29:55 +0100 Subject: [PATCH] vault backup: 2026-05-15 10:29:55 --- .obsidian/plugins/hoarder-sync/data.json | 2 +- 01 Projects/modcomms/Mod Comms.md | 5 +- 99 Daily/2026-05-15.md | 18 ++ ...ode Connect integration Developer Docs.md | 0 .../Code to canvas Developer Docs.md | 0 raw/{ => _processed}/Figma skills for MCP.md | 0 .../Guide to the Figma MCP server.md | 0 ...Code and Figma MCP in 50 Min Felix Lee.md | 0 ...o set up the Dev Mode MCP server Figma.md | 0 ...te Screens and Views from Design System.md | 0 .../Skill Code Connect Developer Docs.md | 0 ...eate_new_file — Create a New Figma File.md | 0 ...ructure your Figma file for better code.md | 0 .../Tools and prompts Developer Docs 1.md | 0 .../Tools and prompts Developer Docs.md | 0 .../Trigger specific tools when needed.md | 0 ...Write effective prompts to guide the AI.md | 0 wiki/_master-index.md | 3 +- wiki/claude-code/_index.md | 13 ++ wiki/claude-code/figma-code-connect-skill.md | 203 ++++++++++++++++++ .../claude-code/figma-dev-mode-mcp-editors.md | 91 ++++++++ .../figma-file-structure-best-practices.md | 55 +++++ wiki/claude-code/figma-mcp-code-connect.md | 71 ++++++ wiki/claude-code/figma-mcp-code-to-canvas.md | 93 ++++++++ .../figma-mcp-designer-workflow.md | 100 +++++++++ .../figma-mcp-effective-prompts.md | 67 ++++++ wiki/claude-code/figma-mcp-guide.md | 102 +++++++++ wiki/claude-code/figma-mcp-skills.md | 132 ++++++++++++ wiki/claude-code/figma-mcp-tools-reference.md | 167 ++++++++++++++ wiki/claude-code/figma-mcp-trigger-tools.md | 52 +++++ wiki/claude-code/figma-skill-build-screens.md | 138 ++++++++++++ .../figma-skill-create-new-file.md | 76 +++++++ 32 files changed, 1383 insertions(+), 5 deletions(-) rename raw/{ => _processed}/Code Connect integration Developer Docs.md (100%) rename raw/{ => _processed}/Code to canvas Developer Docs.md (100%) rename raw/{ => _processed}/Figma skills for MCP.md (100%) rename raw/{ => _processed}/Guide to the Figma MCP server.md (100%) rename raw/{ => _processed}/How to Design and Code with Claude Code and Figma MCP in 50 Min Felix Lee.md (100%) rename raw/{ => _processed}/How to set up the Dev Mode MCP server Figma.md (100%) rename raw/{ => _processed}/Skill Build Update Screens and Views from Design System.md (100%) rename raw/{ => _processed}/Skill Code Connect Developer Docs.md (100%) rename raw/{ => _processed}/Skill create_new_file — Create a New Figma File.md (100%) rename raw/{ => _processed}/Structure your Figma file for better code.md (100%) rename raw/{ => _processed}/Tools and prompts Developer Docs 1.md (100%) rename raw/{ => _processed}/Tools and prompts Developer Docs.md (100%) rename raw/{ => _processed}/Trigger specific tools when needed.md (100%) rename raw/{ => _processed}/Write effective prompts to guide the AI.md (100%) create mode 100644 wiki/claude-code/figma-code-connect-skill.md create mode 100644 wiki/claude-code/figma-dev-mode-mcp-editors.md create mode 100644 wiki/claude-code/figma-file-structure-best-practices.md create mode 100644 wiki/claude-code/figma-mcp-code-connect.md create mode 100644 wiki/claude-code/figma-mcp-code-to-canvas.md create mode 100644 wiki/claude-code/figma-mcp-designer-workflow.md create mode 100644 wiki/claude-code/figma-mcp-effective-prompts.md create mode 100644 wiki/claude-code/figma-mcp-guide.md create mode 100644 wiki/claude-code/figma-mcp-skills.md create mode 100644 wiki/claude-code/figma-mcp-tools-reference.md create mode 100644 wiki/claude-code/figma-mcp-trigger-tools.md create mode 100644 wiki/claude-code/figma-skill-build-screens.md create mode 100644 wiki/claude-code/figma-skill-create-new-file.md diff --git a/.obsidian/plugins/hoarder-sync/data.json b/.obsidian/plugins/hoarder-sync/data.json index 775f19a..75d35ca 100644 --- a/.obsidian/plugins/hoarder-sync/data.json +++ b/.obsidian/plugins/hoarder-sync/data.json @@ -4,7 +4,7 @@ "syncFolder": "Hoarder", "attachmentsFolder": "Hoarder/attachments", "syncIntervalMinutes": 60, - "lastSyncTimestamp": 1778832510045, + "lastSyncTimestamp": 1778837394014, "updateExistingFiles": false, "excludeArchived": true, "onlyFavorites": false, diff --git a/01 Projects/modcomms/Mod Comms.md b/01 Projects/modcomms/Mod Comms.md index ebc4853..2d2e4e1 100644 --- a/01 Projects/modcomms/Mod Comms.md +++ b/01 Projects/modcomms/Mod Comms.md @@ -9,8 +9,8 @@ url: https://baic.oliver.solutions/modcomms/ server: baic tags: [barclays, ai, compliance, proof-review, multi-agent, gcp] created: 2026-04-14 -last_commit: 2026-05-14 -commits: 208 +last_commit: 2026-05-15 +commits: 209 port: 8000 db: PostgreSQL --- @@ -205,6 +205,7 @@ npm run build ## Timeline / Git History | Date | Change | |------|--------| +| 2026-05-15 | feat(knowledge-base): smart resume for interrupted processing jobs | | 2026-05-14 | Rename Legal Agent to Risk & Control Agent across frontend and backend | | 2026-04-15 | Replace logo SVG with PNG v6 in Sidebar and PDF Report | | 2026-04-15 | Add deploy-dev.sh for dev server (sudo docker, fix dist permissions) | diff --git a/99 Daily/2026-05-15.md b/99 Daily/2026-05-15.md index 3470921..066d0fd 100644 --- a/99 Daily/2026-05-15.md +++ b/99 Daily/2026-05-15.md @@ -14,3 +14,21 @@ tags: [daily] - 10:14 (<1min) — session ended | `memory-compiler` - 10:15 (<1min) — session ended | `memory-compiler` - 10:15 (<1min) — session ended | `memory-compiler` +- 10:16 — session ended | `modcomms` +- 10:16 — session ended | `memory-compiler` +- 10:17 (<1min) — session ended | `memory-compiler` +- 10:18 (<1min) — session ended | `memory-compiler` +- 10:19 (<1min) — session ended | `memory-compiler` +- 10:20 (1min) — session ended | `memory-compiler` +- 10:21 (<1min) — session ended | `modcomms` +- 10:21 — session ended | `memory-compiler` +- 10:22 (1min) — session ended | `modcomms` +- 10:22 — session ended | `memory-compiler` +- 10:23 (<1min) — session ended | `memory-compiler` +- 10:24 — session ended | `memory-compiler` +- 10:24 (<1min) — session ended | `memory-compiler` +- 10:25 (<1min) — session ended | `memory-compiler` +- 10:26 (1min) — session ended | `memory-compiler` +- 10:27 (<1min) — session ended | `memory-compiler` +- 10:28 (<1min) — session ended | `memory-compiler` +- 10:28 (<1min) — session ended | `memory-compiler` diff --git a/raw/Code Connect integration Developer Docs.md b/raw/_processed/Code Connect integration Developer Docs.md similarity index 100% rename from raw/Code Connect integration Developer Docs.md rename to raw/_processed/Code Connect integration Developer Docs.md diff --git a/raw/Code to canvas Developer Docs.md b/raw/_processed/Code to canvas Developer Docs.md similarity index 100% rename from raw/Code to canvas Developer Docs.md rename to raw/_processed/Code to canvas Developer Docs.md diff --git a/raw/Figma skills for MCP.md b/raw/_processed/Figma skills for MCP.md similarity index 100% rename from raw/Figma skills for MCP.md rename to raw/_processed/Figma skills for MCP.md diff --git a/raw/Guide to the Figma MCP server.md b/raw/_processed/Guide to the Figma MCP server.md similarity index 100% rename from raw/Guide to the Figma MCP server.md rename to raw/_processed/Guide to the Figma MCP server.md diff --git a/raw/How to Design and Code with Claude Code and Figma MCP in 50 Min Felix Lee.md b/raw/_processed/How to Design and Code with Claude Code and Figma MCP in 50 Min Felix Lee.md similarity index 100% rename from raw/How to Design and Code with Claude Code and Figma MCP in 50 Min Felix Lee.md rename to raw/_processed/How to Design and Code with Claude Code and Figma MCP in 50 Min Felix Lee.md diff --git a/raw/How to set up the Dev Mode MCP server Figma.md b/raw/_processed/How to set up the Dev Mode MCP server Figma.md similarity index 100% rename from raw/How to set up the Dev Mode MCP server Figma.md rename to raw/_processed/How to set up the Dev Mode MCP server Figma.md diff --git a/raw/Skill Build Update Screens and Views from Design System.md b/raw/_processed/Skill Build Update Screens and Views from Design System.md similarity index 100% rename from raw/Skill Build Update Screens and Views from Design System.md rename to raw/_processed/Skill Build Update Screens and Views from Design System.md diff --git a/raw/Skill Code Connect Developer Docs.md b/raw/_processed/Skill Code Connect Developer Docs.md similarity index 100% rename from raw/Skill Code Connect Developer Docs.md rename to raw/_processed/Skill Code Connect Developer Docs.md diff --git a/raw/Skill create_new_file — Create a New Figma File.md b/raw/_processed/Skill create_new_file — Create a New Figma File.md similarity index 100% rename from raw/Skill create_new_file — Create a New Figma File.md rename to raw/_processed/Skill create_new_file — Create a New Figma File.md diff --git a/raw/Structure your Figma file for better code.md b/raw/_processed/Structure your Figma file for better code.md similarity index 100% rename from raw/Structure your Figma file for better code.md rename to raw/_processed/Structure your Figma file for better code.md diff --git a/raw/Tools and prompts Developer Docs 1.md b/raw/_processed/Tools and prompts Developer Docs 1.md similarity index 100% rename from raw/Tools and prompts Developer Docs 1.md rename to raw/_processed/Tools and prompts Developer Docs 1.md diff --git a/raw/Tools and prompts Developer Docs.md b/raw/_processed/Tools and prompts Developer Docs.md similarity index 100% rename from raw/Tools and prompts Developer Docs.md rename to raw/_processed/Tools and prompts Developer Docs.md diff --git a/raw/Trigger specific tools when needed.md b/raw/_processed/Trigger specific tools when needed.md similarity index 100% rename from raw/Trigger specific tools when needed.md rename to raw/_processed/Trigger specific tools when needed.md diff --git a/raw/Write effective prompts to guide the AI.md b/raw/_processed/Write effective prompts to guide the AI.md similarity index 100% rename from raw/Write effective prompts to guide the AI.md rename to raw/_processed/Write effective prompts to guide the AI.md diff --git a/wiki/_master-index.md b/wiki/_master-index.md index 45f7807..4764d63 100644 --- a/wiki/_master-index.md +++ b/wiki/_master-index.md @@ -31,10 +31,9 @@ This 3-hop pattern works for hundreds of articles without vector search. | [[wiki/dotfiles/_index\|dotfiles/]] | Linux terminal ricing: Kitty, Fish, WezTerm CLI, modern Rust CLI tools, LazyVim, unified themes, Tabby, Aerospace WM | 22 | | [[wiki/agent-sdk/_index\|agent-sdk/]] | Claude Agent SDK (formerly Claude Code SDK) — build autonomous AI agents in Python and TypeScript | 30 | | [[wiki/llm-models/_index\|llm-models/]] | LLM model catalogs — OpenAI, Claude/Anthropic, and Google Gemini models, IDs, context, pricing | 3 | -| [[wiki/claude-code/_index\|claude-code/]] | Claude Code product docs — install, capabilities, surfaces, MCP, hooks, scheduling, multi-agent, plugins, skills, channels, error recovery, LM Studio local, Figma MCP, global rules, local config | 36 | +| [[wiki/claude-code/_index\|claude-code/]] | Claude Code product docs — install, capabilities, surfaces, MCP, hooks, scheduling, multi-agent, plugins, skills, channels, error recovery, LM Studio local, Figma MCP, global rules, local config | 49 | | [[wiki/reports/_index\|reports/]] | Weekly and monthly summaries — generate: `uv run python scripts/report-generator.py --weekly` | 1 | | [[wiki/infrastructure/_index\|infrastructure/]] | Server inventory: all 10 SSH hosts — optical, optical-dev, optical-prod, baic, librechat, modocmms, box-cli, aimpress, pve | 11 | - | [[wiki/testing/_index\|testing/]] | Web app testing: functional, performance, security, UI types; TDD/BDD/Agile methodologies; Selenium/Cypress/Playwright/JMeter/OWASP ZAP tools | 1 | diff --git a/wiki/claude-code/_index.md b/wiki/claude-code/_index.md index 1f96ff2..57ff28a 100644 --- a/wiki/claude-code/_index.md +++ b/wiki/claude-code/_index.md @@ -50,3 +50,16 @@ Claude Code is Anthropic's agentic coding assistant. Works across terminal, IDE, | [[wiki/claude-code/global-rules-claude-md\|global-rules-claude-md]] | Global CLAUDE.md rules: core principles, workflow (plan-first, subagents, verify), escalation, change limits, skills/MCP routing, git, code reuse, secrets, server ops | raw/Claude Code Global Rules (CLAUDE.md).md | 2026-05-15 | | [[wiki/claude-code/local-machine-config\|local-machine-config]] | CLAUDE.local.md: Obsidian vault path + folder structure, Mailgun domain gotcha (mg.oliver.solutions), Oliver VPN Tunnelblick check snippet | raw/Claude Code Local Config (CLAUDE.local.md).md | 2026-05-15 | | [[wiki/claude-code/figma-mcp-setup\|figma-mcp-setup]] | Figma MCP server setup in Claude Code: remote (plugin install) vs desktop (Dev Mode + local URL); auth flow, what tools are unlocked | raw/Claude Code and Figma Set up the MCP server.md | 2026-05-15 | +| [[wiki/claude-code/figma-mcp-code-connect\|figma-mcp-code-connect]] | Code Connect + Figma MCP: CodeConnectSnippet wrapper, CLI vs UI mappings, custom instructions for AI code generation matching your design system | raw/Code Connect integration Developer Docs.md | 2026-05-15 | +| [[wiki/claude-code/figma-mcp-code-to-canvas\|figma-mcp-code-to-canvas]] | Code to canvas: capture live browser UI into editable Figma frames via `generate_figma_design`; multi-step flow capture, roundtrip code→canvas→code | raw/Code to canvas Developer Docs.md | 2026-05-15 | +| [[wiki/claude-code/figma-mcp-skills\|figma-mcp-skills]] | All 8 Figma MCP skills: figma-use (canvas write), figma-implement-design (canvas→code), figma-create-new-file, figma-code-connect-components, figma-generate-library (multi-phase), figma-generate-design | raw/Figma skills for MCP.md | 2026-05-15 | +| [[wiki/claude-code/figma-mcp-guide\|figma-mcp-guide]] | Figma MCP server overview: capabilities, remote vs desktop variants, client support matrix (write-to-canvas, code-to-canvas), skills concept, usage patterns | raw/Guide to the Figma MCP server.md | 2026-05-15 | +| [[wiki/claude-code/figma-mcp-designer-workflow\|figma-mcp-designer-workflow]] | Designer's practical guide: Figma→website (15 min), FigJam→game, UX reviewer skill, code-to-canvas roundtrip; Felix Lee demos + adoption landscape | raw/How to Design and Code with Claude Code and Figma MCP in 50 Min Felix Lee.md | 2026-05-15 | +| [[wiki/claude-code/figma-dev-mode-mcp-editors\|figma-dev-mode-mcp-editors]] | Enable Dev Mode MCP server in Figma desktop app; connect to Cursor (one-click), VS Code (settings.json), Windsurf (plugin store); 5 tools exposed | raw/How to set up the Dev Mode MCP server Figma.md | 2026-05-15 | +| [[wiki/claude-code/figma-skill-build-screens\|figma-skill-build-screens]] | 6-step workflow to build/update Figma screens from design system: component discovery (Code Connect → existing screens → search), variables, wrapper-first creation, section-by-section build, image transfer from generate_figma_design | raw/Skill Build Update Screens and Views from Design System.md | 2026-05-15 | +| [[wiki/claude-code/figma-code-connect-skill\|figma-code-connect-skill]] | Full 6-step skill for creating `.figma.ts` template files: parse URL, discover unmapped, fetch properties (TEXT/BOOLEAN/VARIANT/INSTANCE_SWAP/SLOT), identify code component, write template, validate; all API methods + pitfalls | raw/Skill Code Connect Developer Docs.md | 2026-05-15 | +| [[wiki/claude-code/figma-skill-create-new-file\|figma-skill-create-new-file]] | `/figma-create-new-file` skill: resolve planKey via whoami, call create_new_file (design or figjam), get file_key + file_url for use_figma | raw/Skill create_new_file — Create a New Figma File.md | 2026-05-15 | +| [[wiki/claude-code/figma-file-structure-best-practices\|figma-file-structure-best-practices]] | 7 practices for clean Figma files: components, Code Connect, variables/tokens, semantic names, Auto Layout, annotations — maximizes MCP code quality | raw/Structure your Figma file for better code.md | 2026-05-15 | +| [[wiki/claude-code/figma-mcp-tools-reference\|figma-mcp-tools-reference]] | All 18 Figma MCP tools: read (get_design_context, get_metadata, get_screenshot, get_variable_defs, get_figjam), Code Connect (get/add/send_code_connect_map), write (use_figma, generate_figma_design, upload_assets), utility (create_new_file, generate_diagram, whoami, get_libraries, search_design_system) | raw/Tools and prompts Developer Docs 1.md | 2026-05-15 | +| [[wiki/claude-code/figma-mcp-trigger-tools\|figma-mcp-trigger-tools]] | Nudge the AI to the right Figma MCP tool with explicit prompts: get_design_context vs get_variable_defs; prompt patterns that work | raw/Trigger specific tools when needed.md | 2026-05-15 | +| [[wiki/claude-code/figma-mcp-effective-prompts\|figma-mcp-effective-prompts]] | Write specific prompts to control framework, component source, file target, and layout — the more precise, the less cleanup | raw/Write effective prompts to guide the AI.md | 2026-05-15 | diff --git a/wiki/claude-code/figma-code-connect-skill.md b/wiki/claude-code/figma-code-connect-skill.md new file mode 100644 index 0000000..36858e3 --- /dev/null +++ b/wiki/claude-code/figma-code-connect-skill.md @@ -0,0 +1,203 @@ +--- +title: "Figma Code Connect — Skill Workflow (.figma.ts templates)" +aliases: [figma-code-connect-skill, figma-ts-templates, code-connect-workflow] +tags: [figma, code-connect, mcp, skill, typescript, design-to-code] +sources: [raw/Skill Code Connect Developer Docs.md] +created: 2026-05-15 +updated: 2026-05-15 +--- + +# Figma Code Connect — Skill Workflow + +Step-by-step process for creating `.figma.ts` template files that map Figma components to code snippets using the Figma MCP server skill. + +> Covers **template files only** (`.figma.ts` using MCP tools). Parser-based files (`.figma.tsx` with `figma.connect()` via CLI) are a separate approach. + +## Prerequisites + +- Figma MCP tools available (e.g. `get_code_connect_suggestions`) — verify before starting +- Component published to a Figma team library (unpublished = stop) +- Organization or Enterprise plan (not Free/Pro) +- Figma URL must include `node-id` query param +- Add `@figma/code-connect/figma-types` to `tsconfig.json`: + ```json + { "compilerOptions": { "types": ["@figma/code-connect/figma-types"] } } + ``` + +## 6-Step Workflow + +### Step 1 — Parse the Figma URL + +Extract `fileKey` and `nodeId`: + +| URL format | fileKey | nodeId | +|-----------|---------|--------| +| `figma.com/design/:fileKey/:name?node-id=X-Y` | `:fileKey` | `X-Y` → `X:Y` | +| `figma.com/file/:fileKey/:name?node-id=X-Y` | `:fileKey` | `X-Y` → `X:Y` | +| Branch URL with `:branchKey` | use `:branchKey` | from `node-id` param | + +**Always convert hyphens to colons in nodeId**: `1234-5678` → `1234:5678` + +### Step 2 — Discover Unmapped Components + +Call `get_code_connect_suggestions` with `fileKey`, `nodeId`, `excludeMappingPrompt: true`. + +- **"No published components found"** → tell user to publish first, stop +- **"All already connected"** → inform user, stop +- **Normal response** → extract `mainComponentNodeId` per component; use these (not the original URL node) for all subsequent steps. Repeat Steps 3–6 for each component. + +### Step 3 — Fetch Component Properties + +Call `get_context_for_code_connect` with `fileKey`, resolved `nodeId`, `clientFrameworks`, `clientLanguages`. + +Property types returned: + +| Type | Description | +|------|-------------| +| TEXT | Text content (labels, placeholders) | +| BOOLEAN | Toggle (show/hide, disabled) | +| VARIANT | Enum options (size, state) | +| INSTANCE_SWAP | Swappable nested instance (icon) | +| SLOT | Freeform content region | + +### Step 4 — Identify the Code Component + +1. Check `figma.config.json` for `paths`/`importPaths` +2. Search codebase in `src/components/`, `components/`, `lib/ui/`, `app/components/` +3. Compare props interface vs Figma properties from Step 3 +4. **Confirm with user** before writing the template + +### Step 5 — Create the Template File + +**File location:** alongside existing `.figma.ts`/`.figma.tsx` files, named `ComponentName.figma.ts` + +#### Template structure + +```ts +// url=https://www.figma.com/file/{fileKey}/{fileName}?node-id={nodeId} +// source={path to code component} +// component={component name} +import figma from 'figma' +const instance = figma.selectedInstance + +// property extractions... + +export default { + example: figma.code``, + imports: ['import { Component } from "..."'], + id: 'component-name', + metadata: { nestable: true, props: {} } +} +``` + +#### Property mapping methods + +| Figma Type | Method | Notes | +|-----------|--------|-------| +| TEXT | `instance.getString('Name')` | Returns string | +| BOOLEAN | `instance.getBoolean('Name', { true: ..., false: ... })` | Mapping optional | +| VARIANT | `instance.getEnum('Name', { 'FigmaVal': 'codeVal' })` | Must map ALL values | +| INSTANCE_SWAP | `instance.getInstanceSwap('Name')` | Returns `InstanceHandle \| null` | +| SLOT | `instance.getSlot('Name')` | Returns `ResultSection[] \| undefined` | +| Child layer | `instance.findInstance('LayerName')` | No component property | +| Text layer | `instance.findText('LayerName').textContent` | Named text layer | + +#### VARIANT exhaustive mapping (critical) + +Every value from `get_context_for_code_connect` **must** appear in `getEnum`. Unmapped value → silent `undefined`: + +```ts +// Correct — all 4 values mapped +const status = instance.getEnum('Status', { + 'Success': 'success', + 'Error': 'error', + 'Warning': 'warning', + 'Info': 'info', +}) +``` + +#### Interpolation rules + +| Value type | Wrapping | +|-----------|----------| +| String (`getString`, `getEnum`, `textContent`) | Quotes: `variant="${variant}"` | +| Instance snippet (`executeTemplate().example`) | Braces: `icon={${iconCode}}` | +| Slot sections (`getSlot()`) | Directly in template: `` `${content}` `` | +| Boolean bare prop | Conditional: `${disabled ? 'disabled' : ''}` | + +#### Instance swap pattern + +```ts +const icon = instance.getInstanceSwap('Icon') +let iconCode +if (icon && icon.type === 'INSTANCE') { // type check required — findInstance returns ErrorHandle on failure + iconCode = icon.executeTemplate().example +} +``` + +#### SelectorOptions for `findInstance`/`findText` + +```ts +// Target inside a nested instance (stop at boundary by default) +instance.findInstance('child', { traverseInstances: true }) + +// Disambiguate duplicate layer names +instance.findInstance('child', { traverseInstances: true, path: ['ParentLayer'] }) +``` + +### Step 6 — Validate + +Read back the file and check: +- Every Figma property from Step 3 is covered +- All emitted attributes exist in the code component's `Props` interface (never invent props) +- No hardcoded children — INSTANCE_SWAP and slots use dynamic APIs +- INSTANCE_SWAP uses `getInstanceSwap()`, not `getSlot()`; SLOT uses `getSlot()`, not `getInstanceSwap()` +- `type === 'INSTANCE'` check present before every `executeTemplate()` call + +## Key Takeaways + +- **6 steps**: parse URL → discover unmapped → fetch properties → identify code component → write template → validate +- **VARIANT coverage is mandatory** — every enum value must be in the mapping; missing = silent `undefined` +- **Never string-concatenate `ResultSection[]`** — interpolate inside `` figma.code`...` `` tagged templates +- **`hasCodeConnect()` guard is wrong** — always call `executeTemplate()` directly after `type === 'INSTANCE'` check +- **`getSlot()` ≠ `getInstanceSwap()`** — SLOT type uses `getSlot()`, INSTANCE_SWAP uses `getInstanceSwap()`; they are not interchangeable +- **Never hardcode child content** — always resolve dynamically via `executeTemplate()`, omit if no Code Connect exists +- **`findInstance()` returns ErrorHandle (truthy) on failure**, not null — always add `type === 'INSTANCE'` guard +- **Confirm code component match with user** before writing the template (Step 4) + +## Quick API Reference + +### `instance.*` methods + +| Method | Returns | +|--------|---------| +| `getString(prop)` | `string` | +| `getBoolean(prop, mapping?)` | `boolean \| any` | +| `getEnum(prop, mapping)` | `any` | +| `getInstanceSwap(prop)` | `InstanceHandle \| null` | +| `getSlot(prop)` | `ResultSection[] \| undefined` | +| `findInstance(name, opts?)` | `InstanceHandle \| ErrorHandle` | +| `findText(name, opts?)` | `TextHandle \| ErrorHandle` | +| `findConnectedInstance(id, opts?)` | `InstanceHandle \| ErrorHandle` | +| `findConnectedInstances(fn, opts?)` | `InstanceHandle[]` | +| `findLayers(fn, opts?)` | `(InstanceHandle \| TextHandle)[]` | + +### `InstanceHandle` methods + +| Method | Returns | +|--------|---------| +| `executeTemplate()` | `{ example: ResultSection[], metadata: Metadata }` | +| `hasCodeConnect()` | `boolean` (avoid as a guard — see pitfalls) | +| `codeConnectId()` | `string \| null` | + +## Related Articles + +- [[wiki/claude-code/figma-mcp-code-connect|figma-mcp-code-connect]] — higher-level overview: CodeConnectSnippet wrapper, CLI vs MCP mappings +- [[wiki/claude-code/figma-mcp-skills|figma-mcp-skills]] — all 8 Figma MCP skills including `figma-code-connect-components` +- [[wiki/claude-code/figma-mcp-setup|figma-mcp-setup]] — enable Figma MCP server in Claude Code +- [[wiki/claude-code/figma-skill-build-screens|figma-skill-build-screens]] — building/updating Figma screens from design system +- [[wiki/claude-code/figma-mcp-guide|figma-mcp-guide]] — Figma MCP server overview and capabilities + +## Sources + +- `raw/Skill Code Connect Developer Docs.md` — Figma Developer Docs, Code Connect skill reference diff --git a/wiki/claude-code/figma-dev-mode-mcp-editors.md b/wiki/claude-code/figma-dev-mode-mcp-editors.md new file mode 100644 index 0000000..0c5d4e5 --- /dev/null +++ b/wiki/claude-code/figma-dev-mode-mcp-editors.md @@ -0,0 +1,91 @@ +--- +title: "Figma Dev Mode MCP — Cursor, VS Code, Windsurf Setup" +aliases: [figma-dev-mode-mcp, figma-mcp-cursor, figma-mcp-vscode, figma-mcp-windsurf] +tags: [figma, mcp, dev-mode, cursor, vscode, windsurf, setup] +sources: [raw/How to set up the Dev Mode MCP server Figma.md] +created: 2026-05-15 +updated: 2026-05-15 +--- + +# Figma Dev Mode MCP — Cursor, VS Code, Windsurf Setup + +Figma's Dev Mode MCP server exposes Figma design context to any MCP-capable code editor. This is a **local server** running inside the Figma desktop app — not a remote plugin. + +## Requirements + +- Figma **desktop app** (download at figma.com/downloads) — required for local connection +- **Full seat or Dev seat** — free viewer seats cannot use the MCP server +- Figma file open in Dev Mode + +## Step 1 — Enable the MCP Server in Figma + +1. Open Figma desktop app → log in +2. Open any file → switch to **Dev Mode** +3. In the right panel, find the **MCP server block** → toggle it **on** +4. If errors appear, a toast notification shows at the bottom +5. Server stays on for all subsequent files until manually disabled + +> To disable: re-open any file in Dev Mode → toggle off the MCP server block. + +## Step 2 — Connect to Your Editor + +### Cursor + +1. Go to `docs.cursor.com/tools` — Figma one-click install available +2. Confirm Figma desktop app is running (required) +3. Click install — config is pre-filled automatically +4. Wait for **5 tools** to appear in the MCP tools list +5. Open the AI panel → switch to **agent mode** → ready + +> If tools don't load: toggle server off/on in Figma, or restart the Figma app. + +### VS Code + +1. Open Settings → search `MCP` +2. Enable **"Chat: Use MCP protocol"** (required for Copilot/AI agents) +3. Click **"Edit in settings.json"** → add the server config block with the local URL +4. Save → click **Start server** in the MCP panel +5. Open the AI tab → verify the 5 Figma tools appear under Tools + +> Local URL pattern: same `localhost` endpoint used for all MCP-capable editors. + +### Windsurf + +1. Open Windsurf Settings → **Cascade** section → **Open Plugin Store** +2. Search for **Figma** → click **Install** +3. Return to Cascade — 5 Figma tools now appear automatically + +> If tools are missing: reset the server from Cascade or restart the Figma app. + +## MCP Tools Exposed + +Currently **5 tools** are exposed (number will change as Figma adds/consolidates capabilities): + +- Design context retrieval +- Screenshot capture +- Component inspection +- Code suggestions +- (Additional tools to be added) + +## Key Takeaways + +- Dev Mode MCP server **requires the Figma desktop app** — no web-only option +- **Local connection only** — server runs on localhost inside Figma +- Server toggle lives in the **Dev Mode right panel** per file, but stays active across files once enabled +- Cursor has a **one-click install** at docs.cursor.com/tools +- VS Code needs manual `settings.json` config + "Use MCP protocol" toggle enabled +- Windsurf uses the **plugin store** (Cascade → Plugin Store → search Figma) +- All three editors expose the same 5 tools via the same localhost URL +- Check Figma help center docs for config snippets to connect other MCP-compatible editors + +## Related + +- [[wiki/claude-code/figma-mcp-setup|figma-mcp-setup]] — Claude Code variant (remote plugin vs desktop Dev Mode) +- [[wiki/claude-code/figma-mcp-guide|figma-mcp-guide]] — full overview: capabilities, client support matrix, skills +- [[wiki/claude-code/figma-mcp-skills|figma-mcp-skills]] — all 8 Figma MCP skills for Claude Code +- [[wiki/claude-code/mcp-integration|mcp-integration]] — MCP protocol setup in Claude Code + +## Sources + +- Video: "How to set up the Dev Mode MCP server | Figma" (Peter McCarron, 2025-06-30) +- `raw/How to set up the Dev Mode MCP server Figma.md` diff --git a/wiki/claude-code/figma-file-structure-best-practices.md b/wiki/claude-code/figma-file-structure-best-practices.md new file mode 100644 index 0000000..90487a1 --- /dev/null +++ b/wiki/claude-code/figma-file-structure-best-practices.md @@ -0,0 +1,55 @@ +--- +title: "Structure your Figma file for better code" +aliases: [figma-file-best-practices, figma-clean-file, figma-code-quality] +tags: [figma, mcp, code-generation, design-system, components] +sources: [raw/Structure your Figma file for better code.md] +created: 2026-05-15 +updated: 2026-05-15 +--- + +# Structure your Figma file for better code + +How to organize a Figma file so the MCP server and AI can generate clean, consistent, system-aligned code. + +## 7 Practices + +### 1. Use Components +Anything repeated (buttons, cards, inputs, nav items) must be a component. Enables reuse — especially when paired with [[wiki/claude-code/figma-mcp-code-connect|Code Connect]]. + +### 2. Link Components to Code via Code Connect +The #1 lever for consistent component reuse. Without it the model guesses which code component to use. + +### 3. Use Figma Variables for Tokens +Apply variables for spacing, color, border-radius, and typography. Maps directly to design tokens in generated code. + +### 4. Use Semantic Layer Names +Replace default names (`Frame1268`, `Group5`) with intent-driven names: `CardContainer`, `ProductImage`, `CTA_Button`. The model uses names to infer functionality. + +### 5. Use Auto Layout +Communicates responsive layout intent. Avoids absolute positioning in generated code. Test: resize the frame in Figma before generating code — if it breaks, fix layout first. + +### 6. Use Annotations +Convey behavior that's invisible in visuals: interaction states, alignment rules, responsiveness notes. + +### 7. Use Dev Resources *(coming soon)* +Links to developer documentation attached to layers in Dev Mode. + +## Key Takeaways + +- **Components + Code Connect** = the highest-impact combination; skip it and the model guesses +- **Semantic names** feed directly into generated variable/class names and component selection +- **Auto Layout** → cleaner flexbox/grid code; absolute positioning = a red flag +- **Variables** map 1:1 to design tokens; unlabeled colors/spacing = magic numbers in output +- **Annotations** are the escape hatch for logic that can't be expressed visually +- Pre-flight check: resize frame in Figma → verify layout holds → then generate code + +## Related + +- [[wiki/claude-code/figma-mcp-code-connect|Code Connect integration]] — how to map Figma components to real code components +- [[wiki/claude-code/figma-code-connect-skill|Code Connect skill]] — step-by-step `.figma.ts` template creation +- [[wiki/claude-code/figma-mcp-guide|Figma MCP guide]] — full overview of MCP server capabilities +- [[wiki/claude-code/figma-skill-build-screens|Build Screens skill]] — workflow for creating screens from a design system + +## Sources + +- [Structure your Figma file for better code](https://developers.figma.com/docs/figma-mcp-server/structure-figma-file/) — Figma Developer Docs diff --git a/wiki/claude-code/figma-mcp-code-connect.md b/wiki/claude-code/figma-mcp-code-connect.md new file mode 100644 index 0000000..533947e --- /dev/null +++ b/wiki/claude-code/figma-mcp-code-connect.md @@ -0,0 +1,71 @@ +--- +title: "Figma MCP — Code Connect Integration" +aliases: [figma-code-connect-mcp, code-connect-mcp-integration] +tags: [figma, mcp, code-connect, design-system, ai-codegen] +sources: [raw/Code Connect integration Developer Docs.md] +created: 2026-05-15 +updated: 2026-05-15 +--- + +# Figma MCP — Code Connect Integration + +When [Code Connect](https://developers.figma.com/docs/code-connect/) is configured for your design system, the Figma MCP server injects real implementation details into the AI's context window — so generated code matches your actual component library, not a generic guess. + +## How It Works + +The MCP server wraps each connected component in a synthetic `` element containing: + +- **Design properties** — current variant, boolean props, text content from Figma +- **Import statements** — how to import the component +- **Component snippet** — actual usage code +- **Custom instructions** — team-defined rules added via Code Connect UI + +## CLI Mappings vs UI Mappings + +| Aspect | CLI Mappings | UI Mappings | +|--------|-------------|-------------| +| Import source | `imports` field → `source` field → omitted | Auto-generated from mapped component path + name | +| Component name | From your Code Connect file | From mapping config; falls back to Figma design name | +| Snippet content | Full user-defined snippet (prop mappings, file paths) | Auto-generated from design component name + current props | +| Richness | High — exact patterns from codebase | Basic — design properties only (unless custom instructions added) | + +### CLI — richer context + +- Includes **prop mappings**: how Figma properties translate to code props +- Includes **component source paths**: file locations in your repo +- Direct implementation examples from your codebase + +### UI — augment with custom instructions + +UI mappings produce basic snippets by default. Use **"Add instructions for MCP"** in Code Connect UI to add: +- Prop patterns and variants +- Accessibility requirements +- Team conventions and edge cases + +These appear as **user rules** inside the ``. + +## Best Practices + +1. **Connect core components first** — highest-frequency design system components have the most impact +2. **Add custom instructions** — especially for UI mappings; documents prop patterns, a11y, and edge cases +3. **Keep mappings current** — update Code Connect when component APIs change in code +4. **Iterate on instructions** — use Code Connect UI preview to test and refine until AI output matches team patterns + +## Key Takeaways + +- Code Connect + Figma MCP = AI generates code using your real components, not hallucinated ones +- CLI mappings give the richest context (full snippets, prop mappings, source paths) +- UI mappings need custom instructions to reach comparable quality +- The `` wrapper is synthetic — it's injected by the MCP server, not in Figma itself +- Start small: connect the 5–10 most-used components and add instructions iteratively + +## Related + +- [[wiki/claude-code/figma-mcp-setup|Figma MCP Setup]] — how to install and authenticate the MCP server +- [[wiki/claude-code/figma-mcp-custom-rules|Figma MCP Custom Rules]] — project-level CLAUDE.md rules for Figma MCP workflow +- [[wiki/claude-code/figma-mcp-avoid-large-frames|Avoid Large Frames]] — selection strategy for efficient MCP output +- [[wiki/claude-code/mcp-integration|MCP Integration]] — general MCP setup in Claude Code + +## Sources + +- `raw/Code Connect integration Developer Docs.md` (clipped 2026-05-13 from developers.figma.com) diff --git a/wiki/claude-code/figma-mcp-code-to-canvas.md b/wiki/claude-code/figma-mcp-code-to-canvas.md new file mode 100644 index 0000000..c4aef14 --- /dev/null +++ b/wiki/claude-code/figma-mcp-code-to-canvas.md @@ -0,0 +1,93 @@ +--- +title: "Figma MCP — Code to Canvas" +aliases: [code-to-canvas, figma-generate-design, live-ui-to-figma] +tags: [figma, mcp, claude-code, design, ui-capture] +sources: [raw/Code to canvas Developer Docs.md] +created: 2026-05-15 +updated: 2026-05-15 +--- + +# Figma MCP — Code to Canvas + +Convert live, running UI from your browser into editable Figma frames — single screens or entire multi-step flows in one session. + +> **Note:** "Code to canvas" is distinct from "Write to canvas" (which lets agents write directly to an open Figma canvas). This feature captures rendered UI from a browser. + +## What It Does + +- Renders your live app in a browser, then sends the DOM/visual output to Figma as editable design layers +- Supports capturing full screens or individual elements +- Useful for capturing entire user flows (login → onboarding → dashboard) side by side +- Structural issues (unclear empty states, abrupt permission walls, steps to merge) become visible on the canvas + +## The Roundtrip Workflow + +``` +Code → Browser render → Figma canvas (align, annotate, refine) → back to code +``` + +1. Run `generate_figma_design` via Figma MCP +2. Client starts a local server, injects a capture script, opens a browser +3. Use the in-browser toolbar: **Entire screen** or **Select element** +4. Open the resulting Figma file — frames are standard design layers +5. Review on canvas with team, make annotations/decisions +6. Prompt Claude Code with a Figma frame URL → implement the UI changes + +## MCP Tool + +**`generate_figma_design`** — the underlying Figma MCP tool. + +See [[wiki/claude-code/figma-mcp-setup|figma-mcp-setup]] for how to install the remote Figma MCP server first. + +## Supported Clients + +- Claude Code +- Cursor +- VS Code +- Warp +- Augment, Codex (OpenAI), Factory, Firebender + +## Destinations + +| Target | How to prompt | +|--------|--------------| +| New Figma file | "…capture the UI in a new Figma file." | +| Existing Figma file | "…capture the UI in ``." | +| Clipboard | "…capture the UI to my clipboard." — paste into any file | + +- **Any seat** — can create/edit files in your drafts +- **Full seat + edit permission** — required to edit existing files outside your drafts + +## Step-by-Step + +1. Set up the remote Figma MCP server (see [[wiki/claude-code/figma-mcp-setup|figma-mcp-setup]]) +2. Prompt: "Start a local server for my app and capture the UI in a new Figma file." +3. Client injects script, browser opens; initial capture happens automatically +4. In browser toolbar: click **Entire screen** or **Select element** for additional captures +5. Click **Open file** (or paste from clipboard) + +## Tips + +- If local server is already running, omit "Start a local server…" from the prompt +- Multi-page capture: first prompt with file URL, then "Also capture the checkout page" — client infers the same file +- For live web apps, prompt the client to use Playwright to inject the capture script +- For local UI, Playwright injection is not needed + +## Key Takeaways + +- **Code-to-canvas closes the dev↔design loop** — no more screenshots, no "run it locally" +- **`generate_figma_design`** is the MCP tool; it requires the remote Figma MCP server +- **Multi-step flow capture** in one session: each state becomes a side-by-side frame +- **Standard Figma layers** — fully editable, supports annotations and design decisions +- **Roundtrip**: UI from code → canvas review → code implementation via Figma frame URL +- For live/deployed apps, use Playwright to inject the capture script + +## Related + +- [[wiki/claude-code/figma-mcp-setup|Figma MCP Setup]] — install the remote server first +- [[wiki/claude-code/figma-mcp-code-connect|Code Connect + Figma MCP]] — link design components to code +- [[wiki/claude-code/figma-mcp-custom-rules|Figma MCP Custom Rules]] — CLAUDE.md rules for design-to-code flow + +--- + +*Source: raw/Code to canvas Developer Docs.md* diff --git a/wiki/claude-code/figma-mcp-designer-workflow.md b/wiki/claude-code/figma-mcp-designer-workflow.md new file mode 100644 index 0000000..116aa47 --- /dev/null +++ b/wiki/claude-code/figma-mcp-designer-workflow.md @@ -0,0 +1,100 @@ +--- +title: "Figma MCP Designer Workflow — Felix Lee Demo" +aliases: [figma-mcp-designer, claude-code-designer-workflow, figma-to-code-demo] +tags: [claude-code, figma, mcp, design, workflow, skills, figjam] +sources: [raw/How to Design and Code with Claude Code and Figma MCP in 50 Min Felix Lee.md] +created: 2026-05-15 +updated: 2026-05-15 +--- + +# Figma MCP Designer Workflow — Felix Lee Demo + +Practical walkthrough by Felix Lee (CEO, ADPList) on using Claude Code + Figma MCP as a designer. Covers four concrete workflows: design-to-code, FigJam-to-game, UX reviewer skill, and code-to-canvas. + +## Why Claude Code over other coding agents + +- Higher quality output than Gemini AI Studio, Cursor Codex — "from a taste perspective, Claude Code just wins" +- Same model (e.g. Opus 4.6) in Cursor vs Claude Code produces **surprisingly different output** — Claude Code native wins +- Use Claude Code as the AI brain; use Cursor only as a file/preview pane if needed + +## Workflow 1 — Figma Design → Working Website (15 min) + +1. Open the Figma frame in **Dev Mode** +2. Copy the example prompt ("implement this design from Figma") from the Dev Mode panel +3. Paste into Claude Code terminal — Figma MCP auto-fetches all assets (images, icons, colors, fonts) +4. Iterate with follow-up prompts: after-state, logo fix, sticky elements +5. Total time: ~10–15 min for a functional landing page + +**Key advantage of MCP over screenshot:** MCP fills all assets automatically. Screenshot approach requires back-and-forth to supply every icon/image manually. + +## Workflow 2 — FigJam Flowchart → Working Game + +1. Use FigJam AI to generate a flowchart (e.g. "draw a flowchart of a simple Flappy Bird game") +2. Copy the FigJam board link +3. Prompt: `"using this Figma flow chart, build the Flappy Bird game"` — paste the link +4. Claude Code calls `get_figjam` MCP tool, reads the board, then scaffolds the game +5. Result: playable HTML game with animations, scoreboard, difficulty settings — in minutes + +**Caveat:** For well-known games (Flappy Bird, Tetris), the model likely knows the rules already. The flowchart mainly steers app structure, not core mechanics. + +## Workflow 3 — UX Reviewer Skill + +Prompt Claude Code to create the skill: +``` +Create a Claude skill for a UX reviewer. +Review screenshots and mockups. +Keep it flexible, for designers or mixed teams. +``` + +- Claude generates a `ux-reviewer.md` skill file with structured instructions +- To use: `review this screenshot using the UX reviewer skill` — **must name the skill explicitly**, otherwise Claude ignores it and gives generic feedback +- A "council of advisors" pattern: create separate skills per role (UX researcher, UI designer, visual polisher) and run them in sequence or simultaneously + +**Skill = a markdown file of structured instructions.** Write it yourself or have Claude generate it; open-source skill libraries on GitHub are also worth checking. + +## Workflow 4 — Code to Canvas (Figma's new feature) + +- Run app on localhost, then prompt: `export this to a Figma file using Figma MCP` +- Claude calls `generate_figma_design` — creates a new Figma file with the captured UI +- Output: **editable vectors/SVGs**, not screenshots — colors, shapes, icons are all editable components +- Limitation: layer names are auto-generated and messy (all named "icon", "group", etc.) + +**Controversy:** The roundtrip (code → canvas → code) is circular. Designers want the opposite: Figma → full-stack app with database and backend. Code-to-canvas is useful mainly for design system synchronisation and design tweaks after the fact. + +## Practical Apps Built With This Stack + +| App | Complexity | Time | Notes | +|-----|-----------|------|-------| +| Personal website (felixlee.dev) | Dark/light mode, RAG AI chat, Supabase | Days | Good starter project — no client pressure | +| ADPList Rep Globe | 3D animated globe + live data from AWS CSV | ~12 hrs | Screenshot of Shopify globe as reference; no 3D asset used | +| Growth Analyzer | Landing page scorer, Stripe payments, Google auth | ~48 hrs / 3 wks | Hardest part: visual hotspot placement (Gemini Pro best for this) | + +## Designer Adoption Landscape + +- Most designers are **not freaked out enough** — still Figma-only, workflow unchanged +- ADPList data: only ~10–20% increase in Claude Code/Cursor conversations among designers in 6 months +- Main barrier: terminal + IDE looks daunting to non-coders +- Designers over-rely on Figma Make (less capable, no deep skills/MCP) +- Prediction: design systems will be the primary surviving Figma use case as LLMs get better at pixel-perfect fidelity + +## Key Takeaways + +- **Figma MCP pays off most for assets** — it eliminates the manual asset-supply loop that screenshot-only workflows require +- **Explicitly invoke skills by name** in prompts; Claude won't auto-activate them reliably +- **FigJam → code** works today, but the model's prior knowledge does the heavy lifting for common app types +- **Code → canvas** is useful for design-system sync, not as a daily workflow +- **Taste replication is unsolved** — even 4 hrs/day for 2 weeks couldn't reliably replicate a specific designer's aesthetic +- Designers who adopt Claude Code early gain a significant speed advantage; those who stay Figma-only risk being bottlenecked + +## Related Articles + +- [[wiki/claude-code/figma-mcp-guide|Figma MCP Guide — overview and capabilities]] +- [[wiki/claude-code/figma-mcp-setup|Figma MCP Setup — remote vs desktop variants]] +- [[wiki/claude-code/figma-mcp-code-to-canvas|Code to Canvas — generate_figma_design flow]] +- [[wiki/claude-code/figma-mcp-skills|All 8 Figma MCP skills]] +- [[wiki/claude-code/skills|Skills system — creation, storage, invocation]] + +## Sources + +- Raw: `raw/How to Design and Code with Claude Code and Figma MCP in 50 Min Felix Lee.md` +- Original video: YouTube — Felix Lee × Peter Yang, published 2026-03-22 diff --git a/wiki/claude-code/figma-mcp-effective-prompts.md b/wiki/claude-code/figma-mcp-effective-prompts.md new file mode 100644 index 0000000..8baf001 --- /dev/null +++ b/wiki/claude-code/figma-mcp-effective-prompts.md @@ -0,0 +1,67 @@ +--- +title: "Write Effective Prompts for Figma MCP" +aliases: [figma-prompts, figma-mcp-prompting] +tags: [figma, mcp, prompts, claude-code, design-to-code] +sources: [raw/Write effective prompts to guide the AI.md] +created: 2026-05-15 +updated: 2026-05-15 +--- + +# Write Effective Prompts for Figma MCP + +The Figma MCP gives your AI structured design data — but the output quality depends entirely on how specific your prompt is. Treat it like briefing a teammate: the clearer your intent, the better the result. + +## What a Good Prompt Controls + +| Dimension | What to specify | +|-----------|----------------| +| Framework | SwiftUI, React, Chakra UI, Tailwind, etc. | +| Component source | `src/components/ui`, design system library | +| File target | exact file path to add/modify | +| Layout system | flexbox, grid, absolute, custom Stack | +| Codebase conventions | naming, file structure, existing patterns | + +## Prompt Patterns + +### Specify the framework or library +``` +Generate iOS SwiftUI code from the selected Figma frame +Implement the selected frame using Chakra UI components +``` + +### Point to existing components +``` +Generate this using components from src/components/ui +Implement this using our Stack layout component +``` + +### Target a specific file (add, don't create) +``` +Add this component to src/components/marketing/PricingCard.tsx +``` +> Use this when you want code inserted into an existing file, not a new one generated alongside it. + +### Specify layout approach +``` +Implement using flexbox layout only +Build this with CSS Grid — no absolute positioning +``` + +## Key Takeaways + +- The MCP supplies structured Figma data; your prompt determines what the AI does with it +- Vague prompts → generic code; specific prompts → codebase-aligned output +- Always specify: framework, component source, target file path, layout system +- Use imperative language: "Add to", "Generate using", "Implement with" +- The more constraints you give, the less cleanup you do afterward + +## Related + +- [[wiki/claude-code/figma-mcp-trigger-tools|figma-mcp-trigger-tools]] — nudge the AI toward specific Figma MCP tools +- [[wiki/claude-code/figma-mcp-custom-rules|figma-mcp-custom-rules]] — bake prompt conventions into CLAUDE.md so you don't repeat them +- [[wiki/claude-code/figma-mcp-guide|figma-mcp-guide]] — Figma MCP overview and capabilities +- [[wiki/claude-code/figma-mcp-tools-reference|figma-mcp-tools-reference]] — full tool list with descriptions + +## Sources + +- [Write effective prompts to guide the AI — Figma Developers](https://developers.figma.com/docs/figma-mcp-server/write-effective-prompts/) (clipped 2026-05-13) diff --git a/wiki/claude-code/figma-mcp-guide.md b/wiki/claude-code/figma-mcp-guide.md new file mode 100644 index 0000000..39ad803 --- /dev/null +++ b/wiki/claude-code/figma-mcp-guide.md @@ -0,0 +1,102 @@ +--- +title: "Guide to the Figma MCP Server" +aliases: [figma-mcp-overview, figma-mcp-server-guide] +tags: [figma, mcp, design-to-code, code-to-canvas, claude-code, integrations] +sources: [raw/Guide to the Figma MCP server.md] +created: 2026-05-15 +updated: 2026-05-15 +--- + +# Guide to the Figma MCP Server + +High-level overview of Figma's MCP server — what it does, how to connect it, and what clients support which features. + +## What It Does + +The Figma MCP server bridges design and code in both directions: + +- **Read designs → code** — extract variables, components, layout data, and generated code from Figma frames +- **Write code → canvas** — create/modify native Figma frames, components, auto layout, and variables via agent prompts +- **Live UI → Figma** — capture running browser UI (localhost, staging, production) as editable Figma layers +- **FigJam / Make access** — pull diagrams, flows, and prototype resources into your dev context +- **Code Connect consistency** — keep generated code aligned to your actual component library + +## Two Server Variants + +| Variant | How it runs | Key difference | +|---------|-------------|----------------| +| **Remote** (preferred) | Hosted at `https://mcp.figma.com/mcp` | Full feature set: write-to-canvas, code-to-canvas | +| **Desktop** | Via Figma desktop app, local URL | Subset of features; useful for orgs with strict network policies | + +Write-to-canvas and code-to-canvas are **remote-only** features. + +## Client Support Matrix + +| Client | Desktop | Remote | Write to canvas | Code to canvas | Skills/Plugin | +|--------|---------|--------|-----------------|----------------|---------------| +| Claude Code | ✓ | ✓ | ✓ | ✓ | Figma plugin | +| Claude Desktop | ✓ | ✓ | ✓ | ✓ | Figma connector | +| Cursor | ✓ | ✓ | ✓ | ✓ | Figma plugin | +| VS Code | ✓ | ✓ | ✓ | ✓ | Figma plugin | +| Copilot CLI | ✓ | ✓ | ✓ | ✓ | Figma plugin | +| Gemini CLI | ✓ | ✓ | — | — | Extension | +| Codex (OpenAI) | ✓ | ✓ | ✓ | ✓ | Codex Skills | +| Android Studio | ✓ | ✓ | — | — | — | +| Amazon Q | ✓ | — | — | — | — | +| Replit | — | ✓ | — | — | — | + +## Skills + +Skills are agent-level instruction bundles layered on top of MCP tools. They tell the agent **which tools to call, in what order, and how to apply the results**. + +Skills don't add new MCP capabilities — they package recommended workflows. Examples: + +- Connect Figma components to code via Code Connect +- Generate design system rules aligned to your codebase +- Translate a selected frame into production-ready code + +See [[wiki/claude-code/figma-mcp-skills|figma-mcp-skills]] for the full list of 8 Figma skills. + +## Core Usage Patterns + +### Get Design Context (link-based) +1. Select a layer in Figma Design +2. Copy the URL from the browser address bar +3. Paste into your MCP client prompt: *"Implement this design"* +4. The client extracts the node ID and calls `get_design_context` + +### Send Live UI to Figma (remote only) +1. Prompt: *"Start a local server for my app and capture the UI in a new Figma file"* +2. Client opens browser window; use the capture toolbar to capture pages/states +3. Client creates a Figma file and returns the link + +### Write to Canvas +Requires remote server + a Skills prompt. Agent builds/modifies frames using the design system as the source of truth. Currently free during beta; will become usage-based. + +## Plans & Access + +- **Remote server** — all seats and plans +- **Desktop server** — Dev or Full seat, all paid plans +- Write-to-canvas — free during beta period; will become usage-based + +## Key Takeaways + +- Remote server is **always preferred** — wider feature set, no desktop app dependency +- Write-to-canvas and code-to-canvas are **remote-only** — check client support matrix first +- Skills reduce guesswork by packaging multi-tool workflows into reusable instructions +- Design context is URL-based — paste a Figma layer URL and the node ID is auto-extracted +- Code Connect keeps generated code consistent with your actual component library + +## Related + +- [[wiki/claude-code/figma-mcp-setup|figma-mcp-setup]] — installation steps for Claude Code (remote vs desktop) +- [[wiki/claude-code/figma-mcp-skills|figma-mcp-skills]] — all 8 Figma MCP skills and when to use them +- [[wiki/claude-code/figma-mcp-code-connect|figma-mcp-code-connect]] — Code Connect integration details +- [[wiki/claude-code/figma-mcp-code-to-canvas|figma-mcp-code-to-canvas]] — code-to-canvas capture flow +- [[wiki/claude-code/figma-mcp-custom-rules|figma-mcp-custom-rules]] — project-level CLAUDE.md rules for Figma MCP +- [[wiki/claude-code/mcp-integration|mcp-integration]] — general MCP setup in Claude Code + +## Sources + +- raw/Guide to the Figma MCP server.md +- https://help.figma.com/hc/en-us/articles/32132100833559-Guide-to-the-Figma-MCP-server diff --git a/wiki/claude-code/figma-mcp-skills.md b/wiki/claude-code/figma-mcp-skills.md new file mode 100644 index 0000000..36714cc --- /dev/null +++ b/wiki/claude-code/figma-mcp-skills.md @@ -0,0 +1,132 @@ +--- +title: "Figma MCP Skills Reference" +aliases: [figma-skills, figma-mcp-skills] +tags: [figma, mcp, skills, claude-code, design-to-code, code-to-design] +sources: [raw/Figma skills for MCP.md] +created: 2026-05-15 +updated: 2026-05-15 +--- + +# Figma MCP Skills Reference + +Pre-built instructions that teach Claude how to handle common Figma tasks reliably. Included automatically when the Figma MCP plugin is installed in Claude Code. + +Manual download: [github.com/figma/mcp-server-guide](https://github.com/figma/mcp-server-guide/archive/refs/heads/main.zip) + +--- + +## Skills Overview + +| Skill | Purpose | Direction | +|-------|---------|-----------| +| `figma-use` | Write frames, components, variables, layouts to canvas | Code → Canvas | +| `figma-use-figjam` | Write stickies, sections, connectors to FigJam boards | Code → Canvas | +| `figma-implement-design` | Turn Figma design into working code | Canvas → Code | +| `figma-create-new-file` | Create blank design file or FigJam board in drafts | Utility | +| `figma-code-connect-components` | Link Figma components to their code implementations | Bridge | +| `figma-create-design-system-rules` | Persist team conventions to a config file once | Setup | +| `figma-generate-library` | Build/sync full design system library from codebase | Code → Canvas | +| `figma-generate-design` | Push full-page screens into Figma from app code | Code → Canvas | + +--- + +## Core Skills + +### `figma-use` +The foundational write-to-canvas skill. Required by all other canvas-writing skills. + +- Creates/modifies frames, components, variables, auto layout on a Figma Design canvas +- **Requires:** Figma Design file URL + edit access +- **Paid feature** (free during beta) — Full or Dev seats on paid plans; Dev = read-only outside drafts + +Prompt patterns: +``` +"Using this Figma file: , create a settings screen using our existing components." +"Using this selection: , add an empty state matching the design system." +"Using this Figma file: , convert raw colors to variables." +``` + +### `figma-use-figjam` +Same as `figma-use` but for FigJam boards (stickies, connectors, sections, tables). + +- **Requires:** FigJam file URL + edit access +- Same beta/paid status as `figma-use` + +### `figma-implement-design` +Design → Code. Reads a Figma frame, pulls assets, generates code using existing project components. + +- Self-validates output against the original design before finishing +- **Requires:** Link to specific frame or component + +### `figma-create-new-file` +Creates a blank file in drafts. Usually the first step before `figma-use`. + +``` +/figma-create-new-file → design file "Untitled" +/figma-create-new-file figjam My Whiteboard → FigJam "My Whiteboard" +/figma-create-new-file design My New Design → design file named +``` +Returns a direct link. Prompts to select org if account spans multiple. + +--- + +## Bridge Skills + +### `figma-code-connect-components` +Links published Figma components to their code implementations (Figma Code Connect). + +- Scans codebase for matching components, shows proposed mappings for review, then creates in bulk +- **Requires:** Figma URL or selected components; components published to team library; **Organization or Enterprise plan** + +### `figma-create-design-system-rules` +One-time setup: analyzes codebase, writes a rules config file (component paths, token names, file conventions). + +- Run once per project or when onboarding AI to an existing codebase +- **Requires:** Codebase access + +--- + +## Example/Advanced Skills + +### `figma-generate-library` +Builds or syncs a full Figma design system library from a codebase. Multi-phase with review pauses: + +1. **Discovery** — scan codebase + existing Figma file, confirm scope +2. **Foundations** — variable collections (colors, spacing, tokens), text/effect styles +3. **File structure** — standard pages (Cover, Foundations, Components, Utilities) +4. **Components** — variants, auto-layout, variable bindings, screenshot validation +5. **Integration & QA** — Code Connect mappings, naming, accessibility check + +**Requires:** Codebase access + existing Figma file (create with `figma-create-new-file` first) + +### `figma-generate-design` +Pushes full app pages/screens into Figma using real design system assets. Can screenshot a live app for layout reference. + +- Assembles screens section by section from codebase + design system +- **Requires:** Codebase access + Figma file with linked design system library + +--- + +## Key Takeaways + +- **`figma-use` is the foundation** — all write-to-canvas skills depend on it; load this skill first for any canvas work +- **Direction matters** — `figma-implement-design` is Canvas→Code; `figma-use`/`figma-generate-design` are Code→Canvas +- **Plugin install = auto-include** — skills are bundled automatically in Claude Code when the Figma MCP plugin is installed; no manual setup needed +- **`figma-create-new-file` first** — always create the target file before running `figma-use` or `figma-generate-library` +- **Code Connect requires Enterprise** — `figma-code-connect-components` only works on Organization/Enterprise plans +- **`figma-generate-library` is multi-phase** — it pauses for human review between phases; don't expect single-shot output +- **Community skills** — additional skills available at figma.com/community/skills + +--- + +## Related Articles + +- [[wiki/claude-code/figma-mcp-setup|figma-mcp-setup]] — how to connect Figma MCP server to Claude Code +- [[wiki/claude-code/figma-mcp-code-connect|figma-mcp-code-connect]] — Code Connect deep dive (CodeConnectSnippet, CLI mappings) +- [[wiki/claude-code/figma-mcp-code-to-canvas|figma-mcp-code-to-canvas]] — code-to-canvas via `generate_figma_design` +- [[wiki/claude-code/figma-mcp-custom-rules|figma-mcp-custom-rules]] — CLAUDE.md rules for Figma MCP workflows +- [[wiki/claude-code/skills|skills]] — Claude Code skills system: creation, storage, invocation + +## Sources + +- `raw/Figma skills for MCP.md` — scraped from help.figma.com/hc/en-us/articles/39166810751895 diff --git a/wiki/claude-code/figma-mcp-tools-reference.md b/wiki/claude-code/figma-mcp-tools-reference.md new file mode 100644 index 0000000..67daa5e --- /dev/null +++ b/wiki/claude-code/figma-mcp-tools-reference.md @@ -0,0 +1,167 @@ +--- +title: "Figma MCP Server — Tools Reference" +aliases: [figma-mcp-tools, figma-tools-api] +tags: [figma, mcp, tools, code-connect, design-to-code] +sources: [raw/Tools and prompts Developer Docs 1.md, raw/Tools and prompts Developer Docs.md] +created: 2026-05-15 +updated: 2026-05-15 +--- + +# Figma MCP Server — Tools Reference + +Complete reference for all 18 tools exposed by the Figma MCP server. Some tools are **remote only** (require the remote Figma MCP server, not the desktop Dev Mode server). + +## Tool Summary Table + +| Tool | Remote Only | Supported Files | Purpose | +|------|-------------|-----------------|---------| +| `add_code_connect_map` | No | Figma Design | Map Figma node → code component | +| `create_new_file` | Yes | None required | Create blank Design or FigJam file | +| `generate_diagram` | Yes | None required | FigJam diagram from Mermaid/natural language | +| `generate_figma_design` | Yes (select clients) | Figma Design | Push live browser UI as design layers | +| `get_code_connect_map` | No | Figma Design | Retrieve node-to-code mappings | +| `get_code_connect_suggestions` | No | Figma Design | Auto-suggest Code Connect mappings | +| `get_context_for_code_connect` | Yes | Figma Design | Fetch component metadata for template generation | +| `get_design_context` | No | Design, Make | Design context → code (React+Tailwind by default) | +| `get_figjam` | No | FigJam | Convert FigJam diagrams to XML | +| `get_libraries` | Yes | Figma Design | List subscribed + available design libraries | +| `get_metadata` | No | Figma Design | Sparse XML: layer IDs, names, types, positions | +| `get_screenshot` | No | Design, FigJam | Screenshot selection (preserve layout fidelity) | +| `get_variable_defs` | No | Figma Design | Colors, spacing, typography tokens | +| `search_design_system` | Yes | Figma Design | Search components/variables/styles by text | +| `send_code_connect_mappings` | No | Figma Design | Confirm suggested Code Connect mappings | +| `upload_assets` | Yes | Figma Design | Upload PNG/JPG/GIF/WebP (max 10MB each) | +| `use_figma` | Yes | Design, FigJam | General-purpose write to Figma (create/edit/delete) | +| `whoami` | Yes | None required | Return authenticated user identity + plans | + +## Read Tools (Design → Code) + +### `get_design_context` +Primary tool for design-to-code. Returns full styling info for selected layers. Default output: **React + Tailwind**. + +- Override framework via prompt: `generate in Vue`, `generate in plain HTML + CSS`, `generate in iOS` +- Use with Code Connect to map to your actual components: `using components from src/components/ui` +- Desktop server: works on selection. Remote server: requires frame/layer link. + +### `get_metadata` +Lightweight alternative to `get_design_context`. Returns only layer IDs, names, types, positions, sizes as sparse XML. + +- Use for large designs where full `get_design_context` exceeds token limits +- Agent can then call `get_design_context` on just the sub-sections it needs + +### `get_screenshot` +Takes a screenshot of your Figma selection. Preserves layout fidelity in generated code. + +- Keep enabled unless concerned about token limits + +### `get_variable_defs` +Returns design tokens (colors, spacing, typography) from your selection. Use to extract variable names and values before implementing. + +### `get_figjam` +Converts FigJam diagrams to XML (includes screenshots). Similar to `get_metadata` but for FigJam boards. + +## Code Connect Tools + +### `get_code_connect_map` +Returns mapping of selected Figma instance node IDs → code components. + +Each entry contains: +- `componentName` — component name in codebase +- `source` — file path or URL +- `snippet`, `snippetImports`, `snippetNestedFunctions` — code snippet data +- `version` — mapping source (UI vs CLI) +- `label` — framework label (e.g. `React`) + +Multiple instances of the same component → separate entries. Nested components included. + +### `get_code_connect_suggestions` +Figma-prompted auto-detection: suggests Figma component → codebase component mappings. + +### `send_code_connect_mappings` +Confirms suggestions from `get_code_connect_suggestions`. Called after reviewing suggestions. + +### `add_code_connect_map` +Manually add a mapping: Figma node ID → code component. Improves design-to-code output quality. + +### `get_context_for_code_connect` (remote only) +Fetches structured metadata for a component: properties, variants, descendant tree, text nodes. Used internally by the `figma-code-connect` skill — not for direct user invocation. + +## Write Tools (Code → Canvas) + +### `use_figma` (remote only, beta — free during beta) +General-purpose write tool. Creates, edits, deletes, or inspects objects in Design files and FigJam boards. + +**Figma Design:** pages, frames, components, variants, variables, styles, text, images. +**FigJam:** stickies, sections, connectors, shapes, tables, code blocks. + +Best used with a skill: +- [[wiki/claude-code/figma-mcp-skills|figma-use skill]] — for Figma Design workflows +- [[wiki/claude-code/figma-mcp-skills|figma-use-figjam skill]] — for FigJam workflows + +### `generate_figma_design` (remote only, select clients) +Captures live browser UI as editable Figma design layers. + +- Sends to: new file, existing file, or clipboard +- Respects seat type (edit permission required for existing files) +- See [[wiki/claude-code/figma-mcp-code-to-canvas|Code to Canvas]] for full workflow + +### `upload_assets` (remote only) +Upload images (PNG, JPG, GIF, WebP) into a Figma Design file. + +- Max 10MB per asset +- Provide node URL → image becomes fill for that node +- No URL → new frames created with images as fills + +## Utility Tools + +### `create_new_file` (remote only) +Creates blank Design or FigJam file in authenticated user's drafts. Multi-plan users are asked which team/org. + +See [[wiki/claude-code/figma-skill-create-new-file|figma-create-new-file skill]] for the full workflow (includes `whoami` to resolve `planKey`). + +### `generate_diagram` (remote only, beta — free during beta) +Generates interactive FigJam diagrams from Mermaid syntax or natural language. + +**Supported types:** Flowchart, Gantt, State, Sequence, Architecture, ERD + +- No Mermaid knowledge needed — describe in natural language, agent generates syntax +- Can create in new or existing FigJam file +- Include `"Use the Figma MCP generate_diagram tool"` in prompt to ensure tool is invoked + +### `get_libraries` (remote only) +Returns two lists for a Figma file: +1. **Subscribed** — libraries currently added to the file +2. **Available** — community UI kits + org libraries + +Used alongside `search_design_system`. + +### `search_design_system` (remote only) +Full-text search across all connected design libraries. Finds components, variables, and styles. Returns matching assets so agent reuses existing elements instead of creating from scratch. + +### `whoami` (remote only) +Returns: email address, all plans the user belongs to, seat type per plan. Used to resolve `planKey` before `create_new_file`. + +## Key Takeaways + +- **18 tools total** — 9 read-only, 3 write (use_figma, generate_figma_design, upload_assets), 3 utility (create_new_file, generate_diagram, whoami), 3 Code Connect +- **Remote-only tools** require the Figma plugin (not the desktop Dev Mode server): use_figma, generate_figma_design, generate_diagram, create_new_file, get_libraries, search_design_system, get_context_for_code_connect, upload_assets, whoami +- **Design-to-code flow:** `get_metadata` (outline) → `get_design_context` (styling) → `get_screenshot` (layout fidelity) → implement +- **Code Connect** is the key to high-quality output — maps Figma nodes to actual codebase components; set up with `add_code_connect_map` or auto-suggest with `get_code_connect_suggestions` +- **`use_figma` and `generate_diagram`** are currently free in beta but will become paid features +- **Desktop server** exposes 5 tools only; **remote server** unlocks all 18 +- For large frames, use `get_metadata` first to avoid token overload, then selectively call `get_design_context` on sub-sections + +## Related Articles + +- [[wiki/claude-code/figma-mcp-guide|Figma MCP Guide]] — server overview, remote vs desktop, client support matrix +- [[wiki/claude-code/figma-mcp-setup|Figma MCP Setup]] — install remote plugin or enable desktop Dev Mode server +- [[wiki/claude-code/figma-mcp-skills|Figma MCP Skills]] — all 8 skills that wrap these tools +- [[wiki/claude-code/figma-mcp-code-connect|Code Connect Integration]] — full Code Connect setup guide +- [[wiki/claude-code/figma-mcp-code-to-canvas|Code to Canvas]] — `generate_figma_design` workflow +- [[wiki/claude-code/figma-skill-create-new-file|figma-create-new-file Skill]] — `create_new_file` + `whoami` flow +- [[wiki/claude-code/figma-mcp-avoid-large-frames|Avoid Large Frames]] — when to use `get_metadata` vs `get_design_context` + +## Sources + +- `raw/Tools and prompts Developer Docs 1.md` (captured from developers.figma.com/docs/figma-mcp-server/tools-and-prompts/) +- `raw/Tools and prompts Developer Docs.md` (duplicate capture, same URL) diff --git a/wiki/claude-code/figma-mcp-trigger-tools.md b/wiki/claude-code/figma-mcp-trigger-tools.md new file mode 100644 index 0000000..6e8d289 --- /dev/null +++ b/wiki/claude-code/figma-mcp-trigger-tools.md @@ -0,0 +1,52 @@ +--- +title: "Figma MCP — Trigger Specific Tools" +aliases: [figma-mcp-explicit-tools, figma-tool-nudge] +tags: [figma, mcp, prompt-engineering, tools, design-to-code] +sources: [raw/Trigger specific tools when needed.md] +created: 2026-05-15 +updated: 2026-05-15 +--- + +# Figma MCP — Trigger Specific Tools + +The Figma MCP exposes multiple tools, each providing a different kind of structured context. As the tool count grows, AI assistants don't always pick the right one automatically — explicit prompt nudges fix this. + +## Key Tools + +| Tool | What it returns | When to trigger it | +|------|----------------|-------------------| +| `get_design_context` | React + Tailwind structured representation of the selection | Starting point for code generation; translate to any framework after | +| `get_variable_defs` | Variables and styles (color, spacing, typography tokens) | When you need token names/values in generated code | + +## The Problem + +AI assistants often default to `get_design_context` even when you need variables. Users reported requesting variable values but getting raw code instead. + +## The Fix — Explicit Prompt + +Instead of: +> "Generate code for this frame" + +Say: +> "Get the variable names and values used in this frame" + +Being explicit about *what you want* is enough to steer the model toward the correct tool. + +## Key Takeaways + +- **AI tool selection is not deterministic** — add intent to your prompts when output feels wrong or incomplete. +- **`get_design_context`** = structure/layout → code generation starting point. +- **`get_variable_defs`** = design tokens → use when you need exact color/spacing/type values in generated code. +- **Prompt pattern:** name the artifact you want ("variable names and values", "design context", "screenshot") not just the end goal ("generate code"). +- If output is still off after nudging, check [[wiki/claude-code/figma-mcp-avoid-large-frames|figma-mcp-avoid-large-frames]] — large selections degrade tool output quality. + +## Related + +- [[wiki/claude-code/figma-mcp-tools-reference|figma-mcp-tools-reference]] — full reference for all 18 Figma MCP tools +- [[wiki/claude-code/figma-mcp-avoid-large-frames|figma-mcp-avoid-large-frames]] — selection size affects output quality +- [[wiki/claude-code/figma-mcp-custom-rules|figma-mcp-custom-rules]] — lock in the right tool flow via CLAUDE.md rules +- [[wiki/claude-code/figma-mcp-guide|figma-mcp-guide]] — Figma MCP overview and capabilities + +## Sources + +- `raw/Trigger specific tools when needed.md` (source: developers.figma.com/docs/figma-mcp-server/trigger-specific-tools/) diff --git a/wiki/claude-code/figma-skill-build-screens.md b/wiki/claude-code/figma-skill-build-screens.md new file mode 100644 index 0000000..e5f0364 --- /dev/null +++ b/wiki/claude-code/figma-skill-build-screens.md @@ -0,0 +1,138 @@ +--- +title: "Figma Skill: Build / Update Screens from Design System" +aliases: [figma-generate-design-skill, figma-build-screens, figma-screen-from-design-system] +tags: [figma, mcp, design-system, claude-code, skill, components, variables] +sources: [raw/Skill Build Update Screens and Views from Design System.md] +created: 2026-05-15 +updated: 2026-05-15 +--- + +# Figma Skill: Build / Update Screens from Design System + +Skill for creating or updating **composed Figma views** (pages, modals, drawers, sidebars, panels) by reusing the published design system — components, variables, and styles — rather than drawing primitives with hardcoded values. + +**Always load `figma-use` before any `use_figma` call** — it contains critical rules (color ranges, font loading) that apply to every script. Pass `skillNames: "figma-generate-design"` in all `use_figma` calls (logging parameter). + +## Skill Boundaries + +| Use this skill | Switch to | +|---|---| +| Composed views (screens, modals, drawers) from design system instances | `figma-implement-design` — generating code from a Figma design | +| New or updated multi-section containers | `figma-use` directly — creating new reusable components/variants | +| | `figma-code-connect` — writing Code Connect mappings | + +## Parallel Workflow (Web Apps with Images) + +When the source is a **web app** with images, run both in parallel: + +1. Build via `use_figma` + design system components (this skill's workflow) +2. Run `generate_figma_design` to capture a pixel-perfect browser screenshot + +Then merge: copy `imageHash` values from the capture into the `use_figma` output. Delete the capture afterward. + +> **Mandatory when source contains images** — `use_figma` Plugin API cannot fetch external image URLs; it can only reuse `imageHash` values already in the file. + +## Required Workflow (6 Steps) + +### Step 1 — Understand the Deliverable + +- Read relevant source files; identify major sections (Header, Hero, Panels, Footer / Title Bar, Form, Action Bar, etc.) +- List UI components per section (buttons, inputs, cards, nav pills, etc.) +- Check for images → if present on a web app, start `generate_figma_design` capture in parallel now + +### Step 2 — Collect Component Keys, Variables, Styles + +**Hard gate:** no `use_figma` canvas mutations until all Step 2 rows are filled. + +#### 2a: Components (priority order) + +1. **Code Connect files first** — search `*.figma.ts`, `*.figma.tsx`, `*.figma.js`, `@FigmaConnect` annotations. Parse `fileKey` + `nodeId` from URL; resolve component key via `figma.getNodeByIdAsync()` on the library file. Batch lookups in one call. +2. **Inspect existing screens** — walk `INSTANCE` nodes in an existing frame, collect `mainComponent` keys. Most authoritative source. +3. **`search_design_system` (last resort)** — only if unresolved after 1 & 2. Search broadly with synonyms ("button"/"btn", "nav"/"pill"/"tab", etc.). Also read `componentProperties` for TEXT/BOOLEAN property keys needed in Step 4. + +#### 2b: Variables (colors, spacing, radii) + +- `getLocalVariableCollectionsAsync()` returns **local only** — empty result ≠ no variables exist +- Use `search_design_system` with `includeVariables: true` for library variables (run parallel queries: "gray", "background", "space", "radius", etc.) +- Inspect existing screen's `boundVariables` for the most authoritative map +- Import library variables: `figma.variables.importVariableByKeyAsync(key)` + +#### 2c: Styles (text, effect/shadow) + +- `search_design_system` with `includeStyles: true` → "heading", "body", "shadow", "elevation" +- Or inspect existing screen: collect `textStyleId` / `effectStyleId` per node +- Import: `figma.importStyleByKeyAsync(key)` + +### Step 3 — Create Wrapper Frame First + +Create the wrapper in its own `use_figma` call before building any sections. Return its ID. + +```js +const wrapper = figma.createAutoLayout("VERTICAL"); +wrapper.name = "VIEW_NAME"; +wrapper.resize(WIDTH, 100); // 1440 full page / 640 modal / 360 drawer +wrapper.layoutSizingHorizontal = "FIXED"; +wrapper.x = maxX + 200; wrapper.y = 0; +return { wrapperId: wrapper.id }; +``` + +> **Never** build sections as top-level children and reparent later — `appendChild()` across calls silently fails. + +### Step 4 — Build Each Section Inside Wrapper + +One section per `use_figma` call. Fetch wrapper by ID, append sections directly. + +Key rules: +- Import components via `figma.importComponentSetByKeyAsync(key)` +- Bind variables: `setBoundVariable("paddingLeft", spacingVar)` and `setBoundVariableForPaint()` for colors +- Apply text styles: `node.textStyleId = style.id` +- Override instance text via `setProperties({ "Label#2:0": "Actual text" })` — more reliable than direct `characters` manipulation +- Set `layoutSizingHorizontal = "FILL"` **after** appending to wrapper +- `get_screenshot` after each section — check for cropped text, overlapping, wrong variants + +**What to build manually vs import:** + +| Build manually | Import from design system | +|---|---| +| Wrapper frame, section containers, layout grids | Components (buttons, cards, inputs, nav) | +| | Variables (fills/strokes/spacing/radii) | +| | Text styles, effect styles | + +### Step 5 — Validate Full View + Transfer Images + +- `get_screenshot` per section (not just the full view — resolution hides detail) +- Check: cropped text, overlapping elements, placeholder text, blank image frames, wrong variants +- Transfer images from `generate_figma_design` capture: find `fill.type === "IMAGE"` nodes, copy `imageHash` to matching target frames +- Delete capture after transfer + +### Step 6 — Updating Existing Views + +1. `get_metadata` to inspect existing structure +2. Locate nodes by ID/name; swap with `existingButton.swapComponent(newVariant)` +3. Update text/variants/layout selectively; remove deprecated sections +4. Validate each modification with `get_screenshot` + +## Error Recovery + +1. STOP on error — don't retry immediately +2. Read error; use `get_metadata` or `get_screenshot` to inspect state +3. Fix the script; retry (failed scripts are atomic — nothing persists on error) +4. Each section call is independent — previous sections are safe + +## Key Takeaways + +- **Never hardcode hex colors or pixel spacing** — always use design system variables (`setBoundVariable`, `setBoundVariableForPaint`) +- **Discovery order matters:** Code Connect → existing screens → `search_design_system` (last resort) +- **`getLocalVariableCollectionsAsync()` empty ≠ no variables** — always also run `search_design_system` for library vars +- **Create wrapper first, sections inside** — cross-call `appendChild()` silently fails +- **One section per `use_figma` call** — validate visually after each +- **Images require parallel `generate_figma_design`** — `use_figma` cannot fetch external image URLs +- **Override text via `setProperties()`** not `characters` — use component property keys from Step 2a discovery +- **`figma-use` is a prerequisite** — load it before every `use_figma` call + +## Related Articles + +- [[wiki/claude-code/figma-mcp-skills|figma-mcp-skills]] — overview of all 8 Figma MCP skills +- [[wiki/claude-code/figma-mcp-code-to-canvas|figma-mcp-code-to-canvas]] — `generate_figma_design` for pixel-perfect captures +- [[wiki/claude-code/figma-mcp-code-connect|figma-mcp-code-connect]] — Code Connect file structure and mappings +- [[wiki/claude-code/figma-mcp-guide|figma-mcp-guide]] — Figma MCP server overview and capabilities diff --git a/wiki/claude-code/figma-skill-create-new-file.md b/wiki/claude-code/figma-skill-create-new-file.md new file mode 100644 index 0000000..ed71c95 --- /dev/null +++ b/wiki/claude-code/figma-skill-create-new-file.md @@ -0,0 +1,76 @@ +--- +title: "Figma Skill: create_new_file" +aliases: [figma-create-new-file, figma-new-file] +tags: [figma, mcp, skill, claude-code] +sources: [raw/Skill create_new_file — Create a New Figma File.md] +created: 2026-05-15 +updated: 2026-05-15 +--- + +# Figma Skill: create\_new\_file + +Creates a blank Figma file in the user's drafts folder. Used as a precursor to [[wiki/claude-code/figma-mcp-skills|figma-use]] when no target file exists yet. + +## Invocation + +``` +/figma-create-new-file [editorType] [fileName] +``` + +| Argument | Default | Values | +|----------|---------|--------| +| `editorType` | `design` | `design`, `figjam` | +| `fileName` | `Untitled` | Any string | + +**Examples:** +- `/figma-create-new-file` → design file "Untitled" +- `/figma-create-new-file figjam My Whiteboard` +- `/figma-create-new-file design My New Design` + +## Workflow + +### Step 1 — Resolve planKey + +Required by `create_new_file`. Decision tree: + +1. **planKey already known** (from prior `whoami` or user prompt) → use it directly +2. **No planKey** → call `whoami` tool + - Single plan in response → use its `key` automatically + - Multiple plans → ask user which team/org, then use corresponding `key` + +### Step 2 — Call create\_new\_file + +```json +{ + "planKey": "team:123456", + "fileName": "My New Design", + "editorType": "design" +} +``` + +| Parameter | Required | +|-----------|----------| +| `planKey` | Yes | +| `fileName` | Yes | +| `editorType` | Yes | + +### Step 3 — Use the result + +Response contains: +- `file_key` — use in subsequent [[wiki/claude-code/figma-mcp-skills|use_figma]] calls +- `file_url` — direct link to open file in Figma browser + +## Key Takeaways + +- File lands in the user's **drafts folder** for the selected plan +- Only `"design"` and `"figjam"` editor types are supported +- `planKey` must be resolved first — requires `whoami` if unknown +- After creation, load [[wiki/claude-code/figma-skill-build-screens|figma-use skill]] before calling `use_figma` +- Install the skill from [github.com/figma/mcp-server-guide](https://github.com/figma/mcp-server-guide) + +## Related + +- [[wiki/claude-code/figma-mcp-skills|figma-mcp-skills]] — all 8 Figma MCP skills overview +- [[wiki/claude-code/figma-mcp-guide|figma-mcp-guide]] — Figma MCP server overview +- [[wiki/claude-code/figma-skill-build-screens|figma-skill-build-screens]] — next step: building screens in the new file +- [[wiki/claude-code/figma-mcp-code-to-canvas|figma-mcp-code-to-canvas]] — alternative: code → canvas flow