Design Spec Generator

Design Spec Generator

AI-powered design specification and workflow automation tool that creates professional documentation directly in Figma. Built for the cargoes-runner design system.

Overview

Design Spec Generator automates design system workflows using AI agents and the Model Context Protocol (MCP). It handles everything from component documentation to accessibility audits, design system compliance checks, and multi-platform handoffs.

Inspired by Uber's uSpec and the MCP Adoption Toolkit for design teams.

Features

Spec Generation (6 skills)

• Anatomy: Numbered markers + attribute tables
• API: Property documentation with types and defaults
• Properties: Variant grid with live previews
• Color: Design token annotations per state
• Structure: Spacing, padding, dimension specs
• Screen Reader: VoiceOver, TalkBack, ARIA specs

Design Workflows (5 skills)

• Accessibility Audit: WCAG 2.1 AA compliance checking
• Design System Audit: Detect hardcoded values and token violations
• Ticket Validation: Compare designs against acceptance criteria
• Multi-Tech Handoff: Generate specs for React, Angular, SwiftUI, Compose
• Token Migration: Audit and batch migrate hardcoded values

Quick Start

Prerequisites

• Cursor or Claude Code
• Figma Desktop (not web version)
• Node.js 18+
• Figma Personal Access Token

1. Get a Figma Token

1. Go to Figma API Settings
2. Create a new Personal Access Token
3. Enable scopes: File content (Read), Variables (Read), Comments (Read and write)
4. Copy the token (starts with figd_)

2. Configure MCP

Update .mcp.json in the project root:

{
  "mcpServers": {
    "figma-console": {
      "command": "npx",
      "args": ["-y", "figma-console-mcp@latest"],
      "env": {
        "FIGMA_ACCESS_TOKEN": "figd_YOUR_TOKEN_HERE",
        "ENABLE_MCP_APPS": "true"
      }
    }
  }
}

3. Install Desktop Bridge Plugin

1. Open Figma Desktop
2. Go to Plugins → Development → Import plugin from manifest
3. Navigate to this project and select figma-plugin/manifest.json
4. Run the Design Spec Generator - Desktop Bridge plugin in your Figma file

Note: The plugin is included in this project at figma-plugin/. You only need to import it once.

4. Run First-Time Setup

In Cursor, open this project and run:

@firstrun

Follow the prompts to configure your template library.

Usage

Spec Generation Skills

# Generate anatomy spec with markers and tables
@create-anatomy https://figma.com/design/.../node-id=123:456
This is a Button with label, icons, loading state.

# Generate API documentation
@create-api https://figma.com/design/.../node-id=123:456
Dropdown with single/multi-select, searchable, async loading.

# Generate variant exhibit
@create-properties https://figma.com/design/.../node-id=123:456

# Generate color token annotations
@create-color https://figma.com/design/.../node-id=123:456

# Generate dimension specs
@create-structure https://figma.com/design/.../node-id=123:456

# Generate accessibility specs
@create-screen-reader https://figma.com/design/.../node-id=123:456
Interactive button with loading and disabled states.

Design Workflow Skills

# Validate design against ticket requirements
@validate-ticket https://figma.com/design/.../node-id=123:456
Acceptance Criteria:
1. User can enter email and password
2. Form shows validation errors
3. Loading state during submission

# Audit for WCAG 2.1 AA compliance
@audit-accessibility https://figma.com/design/.../node-id=123:456
Focus on the login form components.

# Check design system compliance
@audit-design-system https://figma.com/design/.../node-id=123:456
Audit for hardcoded colors and spacing.

# Generate multi-platform handoff
@handoff-multi-tech https://figma.com/design/.../node-id=123:456
Button with primary, secondary, tertiary variants.
Generate for React and SwiftUI.

# Migrate hardcoded values to tokens
@migrate-tokens https://figma.com/design/.../node-id=123:456
Migrate all hardcoded colors to design tokens.

All Available Skills

Skill	Category	Description
@firstrun	Setup	One-time configuration wizard
@create-anatomy	Spec	Numbered markers + attribute table
@create-api	Spec	Property documentation with types
@create-properties	Spec	Variant grid with live previews
@create-color	Spec	Design token annotations
@create-structure	Spec	Spacing and dimension specs
@create-screen-reader	Spec	VoiceOver, TalkBack, ARIA specs
@validate-ticket	Workflow	Compare design vs acceptance criteria
@audit-accessibility	Workflow	WCAG 2.1 AA compliance audit
@audit-design-system	Workflow	Detect hardcoded values/violations
@handoff-multi-tech	Workflow	Multi-platform implementation specs
@migrate-tokens	Workflow	Batch migrate to design tokens

Project Structure

design-spec-generator/
├── .cursor/skills/              # Cursor agent skills
│   ├── firstrun/
│   ├── create-anatomy/
│   ├── create-api/
│   ├── create-properties/
│   ├── create-color/
│   ├── create-structure/
│   ├── create-screen-reader/
│   ├── validate-ticket/         # NEW
│   ├── audit-accessibility/     # NEW
│   ├── audit-design-system/     # NEW
│   ├── handoff-multi-tech/      # NEW
│   └── migrate-tokens/          # NEW
├── .claude/skills/              # Claude Code skills (mirror)
├── reference/
│   ├── accessibility/
│   │   ├── aria.md              # Web ARIA reference
│   │   ├── voiceover.md         # iOS VoiceOver reference
│   │   ├── talkback.md          # Android TalkBack reference
│   │   └── wcag-checklist.md    # WCAG 2.1 AA checklist
│   ├── component-patterns/
│   │   └── cargoes-runner.md    # Design system patterns
│   └── handoff/
│       └── platform-conventions.md  # React/Angular/Swift/Compose
├── templates/
│   ├── figma-template-guide.md  # Figma template creation guide
│   └── prompt-templates.md      # Copy-paste prompt templates
├── config/
│   └── spec-generator.config.json
├── .mcp.json                    # MCP configuration
├── CLAUDE.md                    # Claude Code instructions
└── README.md

Configuration

MCP Servers

The project uses two MCP servers:

Server	Purpose
figma-console	Deep canvas control, tokens, variables, components
figma-mcp-server	Code Connect features, design context reading

Workflow Settings

config/spec-generator.config.json contains workflow-specific settings:

{
  "workflows": {
    "accessibility": {
      "defaultStandard": "WCAG21AA",
      "contrastThresholds": { "normalText": 4.5, "largeText": 3.0 }
    },
    "handoff": {
      "platforms": ["react", "angular", "swiftui", "compose"]
    },
    "migration": {
      "batchSize": 50,
      "dryRunFirst": true
    }
  }
}

Reference Documentation

Accessibility

• reference/accessibility/aria.md - Web ARIA roles, states, keyboard patterns
• reference/accessibility/voiceover.md - iOS VoiceOver traits and patterns
• reference/accessibility/talkback.md - Android TalkBack semantics
• reference/accessibility/wcag-checklist.md - WCAG 2.1 AA success criteria

Platform Handoff

• reference/handoff/platform-conventions.md - Code patterns for:
  • React with Tailwind CSS
  • Angular with CSS Modules
  • SwiftUI for iOS
  • Jetpack Compose for Android

Design System

• reference/component-patterns/cargoes-runner.md - Component APIs and tokens

Prompt Templates

See templates/prompt-templates.md for copy-paste templates:

• Accessibility audit prompts
• Design system audit prompts
• Ticket validation prompts
• Multi-platform handoff prompts
• Token migration prompts

MCP Tools Available

When connected to Figma Console MCP:

Tool	Purpose
figma_get_status	Check connection status
figma_get_file_data	Get full file structure
figma_get_component	Extract component data
figma_get_variables	Get design tokens
figma_get_styles	Get color/text/effect styles
figma_execute	Run Figma Plugin API code
figma_take_screenshot	Capture screenshots
figma_batch_create_variables	Create tokens in batch
figma_batch_update_variables	Update tokens in batch

Best Practices

Session Management

• Start fresh sessions for each skill
• Each skill uses significant context
• Don't chain multiple skills in one session

During Generation

• Don't interact with Figma while generating
• Keep Desktop Bridge plugin running
• Wait for completion before making changes

Providing Context

• Describe states not visible in the current frame
• List all variants and their purposes
• Mention edge cases and error states

Cost Management

• Scope sessions to specific components/pages
• Run audits before migrations
• Use batch operations for efficiency

Troubleshooting

"MCP not connected"

1. Ensure Figma Desktop is running (not web)
2. Run the Desktop Bridge plugin in your Figma file
3. Check the MCP server is configured in .mcp.json

"Template not found"

Run @firstrun to configure your template library.

"Component not found"

Verify the Figma URL contains a valid node-id parameter.

"Skills not showing in Cursor"

1. Ensure this project folder is open in Cursor
2. Check .cursor/skills/ contains the skill folders
3. Restart Cursor

"Token migration failed"

1. Check if the file is editable
2. Verify you have edit permissions
3. Try smaller batches

Security

• All processing runs locally via Figma Console MCP
• No design data sent to external APIs
• WebSocket connection stays on localhost
• Figma token stored locally in .mcp.json

Credits

• Inspired by Uber's uSpec
• Built on Figma Console MCP by Southleft
• Workflow patterns from MCP Adoption Toolkit by Hugo França
• Designed for cargoes-runner design system

License

MIT