Figma Design Agent

An intelligent MCP (Model Context Protocol) server that bridges Figma designs with code generation. Matches Figma components to code templates and resolves design tokens automatically.

Overview

This agent system enables AI assistants (like Claude) to:

• Match Figma components to known design system patterns
• Resolve design tokens to platform-specific values (Tailwind, MUI, etc.)
• Generate code using pre-defined templates for web, React, Vue, Android, and Flutter

Architecture

figma-design-agent/
├── golden-records/          # Human-readable component specifications
│   ├── avatar_golden_record.json
│   ├── avatar_golden_record.md
│   └── tokens.json
├── kb/                      # Agent-optimized knowledge base
│   ├── components.agent.json
│   └── tokens.agent.json
├── src/
│   └── mcp-server.ts       # MCP server implementation
└── build_kb.js             # KB build script

Quick Start

1. Install Dependencies

npm install

2. Build Knowledge Base

npm run build:kb

This transforms golden records into agent-optimized KB files.

3. Build MCP Server

npm run build:server

4. Test the Setup

node test-server.js

5. Start the MCP Server

# Production
npm run start:mcp

# Development (with auto-reload)
npm run dev:mcp

MCP Tools

matchComponent

Matches a Figma node name to a known component and extracts variant/prop information.

Input:

{
  "figmaNode": {
    "name": "M3/Navigation/Avatar/Monogram",
    "type": "COMPONENT"
  }
}

Output:

{
  "matched": true,
  "component": {
    "name": "Avatar",
    "category": "User Representation",
    "description": "Avatars represent users or entities..."
  },
  "variant": {
    "name": "Monogram",
    "type": "text",
    "description": "Displays user initials"
  },
  "templates": {
    "react": {
      "template": "<Avatar className='{{styles}}' ... />",
      "component": "Avatar",
      "package": "@mui/material"
    }
  },
  "referencedTokens": ["M3/sys/light/primary-container"],
  "specifications": { ... },
  "accessibility": { ... }
}

resolveToken

Resolves a design token name to its code value.

Input:

{
  "tokenName": "M3/sys/light/primary-container"
}

Output:

{
  "resolved": true,
  "tokenName": "M3/sys/light/primary-container",
  "value": "bg-purple-100"
}

Golden Records

Golden records are the source of truth for component specifications. They include:

• Metadata: Version, last updated, Figma file ID
• Specifications: Dimensions, shapes, constraints
• Variants: Different states of the component
• Design Tokens: Color, typography, spacing references
• Accessibility: ARIA roles, labels, requirements
• Platform Templates: Code templates for web, React, Vue, Android, Flutter
• Usage Guidelines: Best practices and examples

Creating New Golden Records

1. Extract component data from Figma
2. Create a JSON file following the schema: golden-records/component_golden_record_schema.json
3. Create a markdown file for human readability
4. Rebuild the knowledge base: npm run build:kb

Knowledge Base Build Process

The build_kb.js script:

1. Reads all golden record JSON files
2. Extracts agent-actionable fields
3. Optimizes for fast lookup
4. Generates kb/components.agent.json and kb/tokens.agent.json

This separation allows:

• Human editors to maintain readable golden records
• Agents to access optimized, focused data
• Fast iteration without agent retraining

Integration with Claude Code

Add to your Claude Code MCP settings:

{
  "mcpServers": {
    "figma-design-agent": {
      "command": "node",
      "args": ["/Users/mootantan/projects/figma-design-agent/dist/mcp-server.js"]
    }
  }
}

Current Components

• Avatar: User representation with image, monogram, and status variants

Supported Platforms

• Web: Native HTML
• React: Material-UI (@mui/material)
• Vue: Vuetify
• Android: Jetpack Compose (Material 3)
• Flutter: Material Design

Design Tokens

20+ Material 3 design tokens currently supported, including:

• Color tokens (primary, secondary, surface, etc.)
• Semantic tokens mapped to Tailwind classes

Development Workflow

Add a New Component

1. Create golden record JSON and MD in golden-records/
2. Run npm run build:kb to update knowledge base
3. Test with node test-server.js
4. Rebuild MCP server if needed: npm run build:server

Update Design Tokens

1. Edit golden-records/tokens.json
2. Run npm run build:kb
3. Restart MCP server

Testing

Run the test suite:

node test-server.js

This validates:

• Knowledge base loading
• Component name matching
• Token resolution
• Server readiness

Architecture Decisions

Why Golden Records?

• Human-first: Easy to edit and review
• Traceable: Link back to Figma sources
• Versionable: Git-friendly JSON/MD format

Why Separate KB Files?

• Performance: Agents load only what they need
• Scalability: Can grow to hundreds of components
• Maintainability: Clear separation of concerns

Why MCP?

• Standardized: Works with any MCP-compatible client
• Composable: Can combine with other MCP tools
• Efficient: In-memory KB for fast lookups

Future Enhancements

• Semantic component matching (RAG-based)
• Figma API integration for auto-extraction
• Component composition rules
• Dark mode token variants
• Responsive sizing tokens
• Animation/transition templates
• Multi-language token support

Contributing

To add support for a new design system:

1. Create golden records for components
2. Define design token mappings
3. Add platform templates
4. Update the schema if needed
5. Rebuild and test

License

MIT

Credits

Built with:

• @modelcontextprotocol/sdk
• Material Design 3 specifications
• TypeScript

---

Status: Production Ready ✅ Version: 1.0.0 Last Updated: 2025-11-12