figma-to-code

name	figma-to-code
description	Generate production-ready React/Next.js code from Figma designs. Instructs proper Figma MCP tool usage, component reuse strategies, and variant mapping. **CRITICAL: ALWAYS use this skill when user provides a Figma link or mentions implementing/redesigning from Figma design.** Never attempt manual implementation without invoking this skill first.

Figma to Code Generator

Purpose

Generate production-ready React/Next.js code from Figma designs. Provides systematic workflows for using Figma MCP tools, enforces component reuse, maps Figma variants to code props.

When to Use

Use this skill when:

• User provides a Figma link to implement as code
• Creating a new page from Figma design
• Redesigning an existing page based on updated Figma designs
• Implementing a new component or component variant from Figma

Do not use this skill when:

• No Figma design is provided (user describes requirements verbally)
• Working on backend or non-UI code
• Making minor text or content updates to existing pages

Prerequisites

Required dependency: Figma MCP Server must be installed.

Before using Figma MCP tools, verify the server is available by attempting to use any Figma MCP tool (e.g., mcp__figma-desktop__get_metadata). If you receive an error indicating the tool is not available:

Prompt user with:

❌ Figma MCP Server Not Installed

To use Figma designs with Claude Code, you need to install the Figma MCP server.

Installation steps:
1. Open Figma Desktop app
2. Navigate to the MCP server installation guide:
   https://developers.figma.com/docs/figma-mcp-server

3. Follow the installation instructions for your operating system

4. Restart Claude Code after installation

Also ensure:
- Figma Desktop app is running
- You're logged into Figma
- The design file is open or you have access to it

Only proceed with Figma MCP tools after confirming the server is installed.

Figma MCP Tool Usage Protocol (MANDATORY)

Critical Rule: ALWAYS Use This Workflow When User Provides Figma Link

When user provides a Figma link or node ID, YOU MUST follow this exact tool sequence. Do NOT skip steps or change the order.

Required Tool Order: Metadata → Context → Screenshot → Variables

Step 1: Get Metadata (REQUIRED FIRST)

Tool: mcp__figma-desktop__get_metadata
Extract:
- Component/frame names and hierarchy
- Layer types (COMPONENT, FRAME, INSTANCE)
- Variant property names
- Child element structure

Look for: Component or frame? Variant properties? Children organization? Naming patterns?

Step 2: Get Design Context (REQUIRED SECOND)

Tool: mcp__figma-desktop__get_design_context
Extract:
- Colors (with variable references like "colors/iris/950")
- Spacing (padding, gaps, margins)
- Typography (font family, size, weight)
- Border radius, shadows, effects
- Component variant values

Look for: Which Figma variables? Spacing values? Hard-coded values?

Step 3: Get Screenshot (REQUIRED THIRD)

Tool: mcp__figma-desktop__get_screenshot
Use for: Visual verification, understanding layout

Step 4: Get Variables (REQUIRED FOURTH)

Tool: mcp__figma-desktop__get_variable_defs
When: Design uses Figma variables extensively or checking token consistency

MCP Tool Parameters

Always include for proper logging:

{ clientLanguages: "typescript,javascript", clientFrameworks: "react,nextjs" }

MCP Tool Rules

Do: ✓ Start with metadata, ✓ Use context for details, ✓ Use parameters Don't: ✗ Skip metadata, ✗ Wrong order, ✗ Screenshot alone

Critical Boundaries: Frontend Layer Focus

Default Scope: Frontend Only

Operate exclusively in the frontend layer by default. Figma designs represent UI/UX and should translate to frontend code only.

Frontend scope:

• [FRONTEND_DIR]/app/ - Next.js pages and routes
• [FRONTEND_DIR]/components/ - React components
• [FRONTEND_DIR]/lib/ - Frontend utilities
• [FRONTEND_DIR]/hooks/ - Custom React hooks
• [FRONTEND_DIR]/public/ - Static assets

Do NOT touch without permission:

• [BACKEND_DIR]/ - Backend directories and files
• Backend routes, database schemas, or API endpoints

Backend Change Protocol

ALWAYS ask user before:

1. Creating new API routes
2. Modifying existing API endpoints
3. Changing database schemas
4. Adding backend dependencies
5. Touching any files outside [FRONTEND_DIR]/

Ask with this format:

⚠️ Backend Change Required

To implement this Figma design, the following backend changes are needed:
[Specific backend changes listed]

Frontend can be mocked with placeholder data until backend is ready.

Would you like me to:
1. Implement frontend with mocked data (recommended)
2. Implement both frontend and backend
3. Only implement frontend and document backend requirements

Only proceed WITHOUT asking if:

• User explicitly stated "implement both frontend and backend"
• User is actively working in backend and asks to "complete the implementation"

Mock Data Pattern

Implement frontend with mock data first, document required API shape.

// TODO: Replace with actual API call to [BACKEND_DIR]/[API_MODULE]
const mockProducts = [{ id: 1, name: "Product 1", price: 99 }]

/**
 * Backend API Required:
 * GET /api/products
 * Response: { products: Array<{id, name, price, imageUrl}> }
 * Backend file: [BACKEND_DIR]/[API_MODULE]/routes.ts
 */
export function ProductList() {
  const products = mockProducts
  return // Render using mock data
}

Component Reuse Strategy

Priority: Reuse > Extend > Create

Check Existing Components First

Search locations:

• [COMPONENTS_DIR]/ui/ - UI library base components
• [COMPONENTS_DIR]/ - Custom components

Search method:

1. Extract base name from Figma (e.g., "Button" from "Button/Primary/Large")
2. Use Glob to find: [COMPONENTS_DIR]/ui/{name}.tsx
3. Read component file to check variants and props
4. Compare Figma variants with code props

Key components to check for:

• Button, Card, Dialog, Form, Input, Select, Textarea, Checkbox, Switch
• Alert, Badge, Tabs, Accordion, Table, DropdownMenu, Popover, Tooltip
• Other custom components in your UI library

Decision Matrix

Figma Design	Action
Matches existing exactly	Use existing with props
Matches with minor tweaks	Use existing + className
Can be composed	Use composition pattern
Needs new variant	Ask user before extending
Completely new pattern	Create new component

Variant Mapping: Figma → Code

Common Mappings

Figma Property	Figma Value	Code Prop	Code Value
variant	Primary	variant	"primary"
variant	Secondary	variant	"secondary"
variant	Outlined	variant	"outline"
size	Small	size	"sm"
size	Large	size	"lg"
state	Disabled	disabled	true

Multiple Variants Example

// Figma: Button/Primary/Large/Disabled
<Button variant="primary" size="lg" disabled={true}>Text</Button>

Creating New Components with Variants

// Example: Using your styling system for variants
const componentVariants = [VARIANT_SYSTEM_IMPLEMENTATION]
// Map Figma variant properties to your component's variant props
// e.g., Figma "Primary" -> variant="primary"
// e.g., Figma "Small" -> size="sm"

Code Generation Guidelines

TypeScript Component Pattern

import * as React from "react"
import { [STYLING_UTILITY] } from "[UTILITY_PATH]"

interface ComponentNameProps extends React.HTMLAttributes<HTMLDivElement> {
  variant?: "primary" | "secondary"  // Map from Figma variants
  size?: "sm" | "lg"  // Map from Figma size variants
}

export const ComponentName = React.forwardRef<HTMLDivElement, ComponentNameProps>(
  ({ className, variant = "primary", size = "lg", ...props }, ref) => {
    return (
      <div
        ref={ref}
        className={[APPLY_STYLES_BASED_ON_VARIANTS]}
        {...props}
      />
    )
  }
)

ComponentName.displayName = "ComponentName"

Styling Priority

1. Design System Variables (preferred): Use your project's semantic design tokens
2. Custom Palette: Use your project's defined color palette
3. Never: Hard-coded color values or arbitrary styles

Map Figma colors to your design system:

• Extract color variable names from Figma design context
• Map to your project's color system (CSS variables, theme tokens, etc.)
• Example: colors/primary/600 → [YOUR_PRIMARY_COLOR_TOKEN]

Responsive & Dark Mode

// Use your project's responsive breakpoint system
className={[RESPONSIVE_LAYOUT_CLASSES]}

// Use your project's theme/dark mode system
className={[THEME_AWARE_CLASSES]}

Coding Standards

File Naming and Location

Naming:

• Components: PascalCase (ProductCard.tsx)
• Utilities: kebab-case (format-date.ts)
• Pages: Next.js convention (page.tsx)

Locations:

• UI components: [COMPONENTS_DIR]/ui/component-name.tsx
• Feature components: [COMPONENTS_DIR]/feature-name/component-name.tsx
• Page components: [PAGES_DIR]/route/component-name.tsx

TypeScript & Code Style

• TypeScript: No any types, proper interfaces
• Immutability: Use const and readonly
• Null handling: Prefer null over undefined
• Functional patterns: No classes
• Styling: Follow your project's styling approach (no inline styles unless project convention allows)
• Descriptive names: isLoading, hasError
• One component per file
• Place tests next to components

Import order:

// 1. React/frameworks
import * as React from "react"
// 2. External packages
import { [EXTERNAL_UTILITIES] } from "[PACKAGE]"
// 3. Internal components
import { Button } from "[COMPONENTS_DIR]/ui/button"
// 4. Types
import type { User } from "[TYPES_DIR]"

Accessibility Requirements

Always include:

• Semantic HTML: <button>, <nav>, <main>
• ARIA labels: When semantic HTML isn't enough
• Keyboard navigation: Focus states, tab order
• Screen reader support: alt text, aria-labels

<button aria-label="Close" aria-pressed={isActive} disabled={isDisabled}>
  <X className="h-4 w-4" aria-hidden="true" />
</button>

Page Generation

Creating Full Pages

1. Get metadata to understand sections
2. Get context for each section
3. Identify which map to existing components
4. Generate using composition

// [PAGES_DIR]/route-name/page.tsx
import { ComponentA } from "[COMPONENTS_DIR]/ui/component-a"

export default function PageName() {
  return (
    <div className={[CONTAINER_STYLES]}>
      <header><h1 className={[HEADING_STYLES]}>Page Title</h1></header>
      <main className={[LAYOUT_STYLES]}><ComponentA /></main>
    </div>
  )
}

Redesigning Pages

1. Read current page first
2. Identify changes vs. staying same
3. Preserve data fetching and state
4. Update only UI layer
5. Ask before removing functionality

Quality Checklist

Before providing code, verify:

• Used metadata → context → screenshot → variables order
• Checked for existing components first
• Used composition over creation
• Mapped Figma variants to code props
• Used project's design system tokens/variables
• No any types, proper TypeScript
• Included accessibility attributes
• Responsive design following project conventions
• Theme/dark mode support if applicable
• Correct file naming and location
• Added component displayName
• JSDoc comments for complex logic
• All code in frontend directory only
• No backend changes without permission
• Used mock data if backend needed

Examples

For detailed workflow examples, see the reference file: examples.md

Examples include:

• Button component reuse
• Card composition
• Page with backend requirements
• Creating new component with variants
• Full page layout implementation
• Common patterns (composition, extending, mock data)

Error Handling

When Figma data unclear: Ask for clarification, use screenshot as fallback, document assumptions

When no component matches: Document why existing don't work, ask user: extend or create new?

When backend requirements unclear: Document API shape in JSDoc, use TypeScript interfaces, provide mock data