implement-designs

name	implement-designs
source	botcore
description	Guides the Figma design-to-code workflow using MCP integration, token extraction, and structured implementation. Covers Figma MCP setup, authentication, URL parsing, design context retrieval, token translation from Tailwind/Figma output to CSS custom properties, icon identification, asset management, and Code Connect mapping. Use when implementing a design from Figma, setting up the Figma MCP server, extracting design specs, translating design tokens, or converting React/Tailwind output to web components. Triggers: figma, design, design-to-code, implement design, figma link, screenshot, mcp, design tokens, figma mcp.
version	1.0.0
triggers	["figma","design","design-to-code","implement design","figma link","screenshot","design tokens","figma mcp","token extraction"]
portable	true

Implementing Designs — Figma Design-to-Code Workflow

Structured workflow for turning Figma designs into production code using the Figma MCP server, design token extraction, and component translation.

Capabilities

1. Set up and troubleshoot the Figma MCP server (VS Code extension, authentication, Dev Mode)
2. Parse Figma URLs to extract file keys and node IDs for MCP tool calls
3. Retrieve screenshots and design context from Figma nodes via MCP tools
4. Extract design specifications (tokens, dimensions, spacing, typography, shadows) from MCP output
5. Translate Figma/Tailwind token formats into CSS custom properties
6. Map React Code Connect component names to web component equivalents
7. Identify icons from Figma metadata rather than visual guessing
8. Manage image assets extracted from Figma (expiring URLs, system vs sample-data classification)
9. Break large Figma frames into sublayers to work within MCP context limits

Routing Logic

• For detailed Figma-to-CSS token mapping (colors, typography, spacing, borders, shadows) see references/figma-token-map.md
• For React-to-web-component Code Connect translation tables see references/code-connect-map.md
• For image asset organization and Figma extraction workflow see references/asset-management.md

Core Principles

• Extract specs, never code. Figma MCP returns React + Tailwind output. Treat it as a design specification source, not as copy-paste code. Pull out the design values (tokens, dimensions, spacing) and implement in your project's component system.
• Tokens over hardcoded values. Always convert hex colors, pixel values, and font stacks to semantic design tokens. Hardcoded values break when themes change.
• Screenshot first, then context. Always call get_screenshot before get_design_context so you know what you are building.
• Navigate to main component. Figma frame selection often returns the parent layout. Guide the designer to right-click and "Go to main component" for a tightly scoped node with variants and states.
• Icons from metadata, not screenshots. Icon layer names in Figma often show "Shape" or "Path" instead of the icon name. Always use get_metadata or ask the designer.
• Download assets immediately. Figma MCP image URLs expire after 7 days. Download on extraction and reference local paths, never Figma URLs.

Workflow

1. Setup Figma MCP

Install the official Figma MCP server via VS Code Extensions marketplace (search "Figma MCP"). Start the server, authenticate via browser popup, and enable Dev Mode in Figma Desktop. Verify these tools are available:

Tool	Purpose
get_screenshot	Visual screenshot of any Figma node
get_design_context	Layout, tokens, component structure for a node
get_metadata	Instance names, icon names, component refs
get_variable_defs	Design token variable definitions

Troubleshooting quick fixes:

• Tools keep turning off: Reload VS Code window
• Duplicate installs: Remove all, reinstall in workspace only
• Auth popup missing: Stop/start server, check behind VS Code window
• Calls fail: Verify account access and Dev Mode is enabled

2. Get the Right Figma Node

Ask the designer to right-click the component in Figma, select "Go to main component", and share the URL. This gives a scoped node with properties, variants, and states rather than a parent layout frame.

Parse the URL to extract identifiers:

URL pattern: https://www.figma.com/design/{fileKey}/{fileName}?node-id={nodeId}&m=dev
- fileKey: alphanumeric string after /design/
- nodeId:  value after node-id= (replace - with : for the MCP API)

3. Retrieve Design Specs

1. Call get_screenshot to see the target visual
2. Call get_design_context on the focused node
3. If the response is too large, call on the root first to get child node IDs, then call on each sublayer individually
4. For icons, call get_metadata on the icon node to get the exact instance name

4. Extract and Translate Tokens

Pull design values from MCP output. Convert Tailwind utility syntax to CSS custom properties:

MCP Output Pattern	CSS Custom Property
bg-[var(--colorNeutralBackground1,white)]	background: var(--colorNeutralBackground1)
text-[color:var(--colorNeutralForeground1)]	color: var(--colorNeutralForeground1)
font-[family-name:var(--font-family/base)]	font-family: var(--fontFamilyBase)
text-[length:var(--font-size/300)]	font-size: var(--fontSizeBase300)
gap-[var(--horizontal/s,8px)]	gap: var(--spacingHorizontalS)
rounded-[var(--x-large,8px)]	border-radius: var(--borderRadiusXLarge)
shadow-[var(--shadow4)]	box-shadow: var(--shadow4)

Conversion rule: Strip the Tailwind utility prefix, remove the fallback value after the comma, convert the slash-separated path to camelCase CSS custom property name.

See references/figma-token-map.md for the full token rosetta stone (color, typography, spacing, elevation, border radius).

5. Translate Components

If Figma MCP returns React component names (from Code Connect), map each to the project's web component equivalent. Common pattern: <ReactName> becomes <prefix-kebab-name>.

Key translation rules:

• React camelCase props become kebab-case HTML attributes (iconOnly becomes icon-only)
• className is ignored (use scoped styles instead)
• onClick becomes a @click event binding or native event listener
• children becomes default slot content
• icon prop becomes an icon element in a named slot

See references/code-connect-map.md for the full component mapping table.

6. Handle Assets

• Download image URLs from MCP output immediately (they expire in 7 days)
• Classify images: system assets (logos, illustrations) vs sample data (avatars, thumbnails)
• Reference local paths, never Figma URLs, in component code
• For icons, search the project icon packages rather than extracting raster images

See references/asset-management.md for the full asset workflow.

Checklist

• Figma MCP server installed, authenticated, and all four tools available
• Designer navigated to main component (not parent frame) and shared URL
• Screenshot retrieved to confirm visual target
• Design context retrieved (sublayered if too large)
• All hardcoded values converted to semantic design tokens
• Tailwind utility syntax converted to CSS custom properties
• React components mapped to web component equivalents
• Icons identified via get_metadata, not guessed from screenshots
• Image assets downloaded locally, not referenced by Figma URL
• Implementation reviewed for design fidelity against screenshot

When to Escalate

• Icon cannot be identified: Figma layers show only "Shape" or "Path" and get_metadata returns generic names. Ask the designer for the specific icon name.
• MCP context limit exceeded: Even sublayering does not reduce the response size enough. Ask the designer to provide a more focused Figma node or break the design into smaller components.
• Token not found in design system: A Figma value does not map to any known design token. Flag the value, use the nearest token with a comment noting the deviation, and raise with the design team.
• Custom non-standard styling: Elements use data visualization color slots, custom gradients, or other non-standard values that do not map to component appearances. Implement as custom-styled plain elements and document the decision.
• Code Connect snippet mismatch: A Code Connect snippet references a component that does not exist in the project's component library. Check for recent additions or ask the design system team.