figma-design-system-to-design-md

name	figma-design-system-to-design-md
description	Convert Figma design tokens into structured design.md for AI-assisted coding with Cursor, Claude Code, and Copilot
triggers	["convert my design tokens to design.md","generate design system documentation from Figma","create design.md from tokens","document my design system automatically","extract design tokens to markdown","sync Figma design system to docs","build design.md from CSS variables","parse design tokens for AI coding"]

figma-design-system-to-design-md

Skill by ara.so — Design Skills collection.

A Claude Code skill plugin that automatically converts Figma design tokens into a structured design.md file. It extracts CSS variables, Tailwind config, theme files, and optionally pulls data from Figma MCP to create comprehensive design system documentation that AI coding tools can understand.

What It Does

The Problem: Design systems live in Figma and code, but documentation is outdated or nonexistent. Developers guess at color roles, spacing scales, and typography.

The Solution: One command generates a complete design.md that stays in sync with your actual token files.

The tool:

• Detects token sources automatically (CSS variables, Tailwind config, theme files)
• Parses and classifies tokens into categories (colors, typography, spacing, etc.)
• Optionally enriches data via Figma MCP
• Generates structured design.md with semantic roles
• Works framework-agnostic (React, Vue, Svelte, etc.)

Installation

As Claude Code Plugin

# Via marketplace
claude plugin install figma-design-system-to-design-md

# Via GitHub
claude /plugin install https://github.com/albertzhangz10/figma-design-system-to-design-md

Local Development

git clone https://github.com/albertzhangz10/figma-design-system-to-design-md.git
cd figma-design-system-to-design-md
claude --plugin-dir /path/to/figma-design-system-to-design-md

Web Version (No Installation)

For non-technical users: https://figmadesignmd.com/ Just paste a Figma URL and get your design.md.

Key Commands

# Generate design.md in project root
/figma-design-system-to-design-md

# Custom output path
/figma-design-system-to-design-md ./docs/design.md

# Specify token file directory
/figma-design-system-to-design-md --tokens-dir ./src/styles

Token Source Detection

The skill automatically searches for these patterns:

CSS Tokens:

• **/tokens.css
• **/variables.css
• **/theme.css
• **/globals.css

JSON/JS Tokens:

• **/tokens.json
• **/tokens.ts
• **/tokens.js
• **/theme.ts

Framework Config:

• tailwind.config.js
• tailwind.config.ts
• uno.config.ts

What Gets Generated

Section	Source	Auto-Generated
Colors (base + semantic roles)	Token files	✅
Typography (families, scale, weights)	Token files	✅
Spacing (scale with values)	Token files	✅
Border Radius	Token files	✅
Border Width	Token files	✅
Elevation (shadows)	Tailwind / Figma MCP	✅
Responsive (breakpoints)	Config files	✅
Components (variants, states)	Figma MCP	🔶 Optional
Overview (design intent)	Manual	✍️
Do's and Don'ts	Manual	✍️

Configuration

Enabling Figma MCP (Optional)

For enhanced component extraction and effect styles:

1. Open Figma desktop app (latest version)
2. Menu → Preferences → Enable Dev Mode MCP Server
3. Restart Claude Code
4. Open your design system file in Figma

Project Requirements

• Required: Token files in your project (any format)
• Optional: Figma MCP Server for component data
• Recommended: Claude Code latest version

Code Examples

Example 1: CSS Variables Token File

Input (src/styles/tokens.css):

:root {
  /* Colors - Base */
  --color-blue-50: #eff6ff;
  --color-blue-500: #3b82f6;
  --color-blue-900: #1e3a8a;
  
  /* Colors - Semantic */
  --color-text-primary: var(--color-blue-900);
  --color-surface-primary: #ffffff;
  --color-border-default: #e5e7eb;
  
  /* Typography */
  --font-sans: 'Inter', system-ui, sans-serif;
  --font-size-sm: 0.875rem;
  --font-size-base: 1rem;
  --font-size-lg: 1.125rem;
  
  /* Spacing */
  --spacing-1: 0.25rem;
  --spacing-2: 0.5rem;
  --spacing-4: 1rem;
  --spacing-8: 2rem;
  
  /* Border Radius */
  --radius-sm: 0.125rem;
  --radius-md: 0.375rem;
  --radius-lg: 0.5rem;
}

Generated design.md (excerpt):

## Colors

### Base Palette
- `--color-blue-50`: #eff6ff (Light accent)
- `--color-blue-500`: #3b82f6 (Primary brand)
- `--color-blue-900`: #1e3a8a (Dark text)

### Semantic Roles
- **Text Primary**: `--color-text-primary` → var(--color-blue-900)
- **Surface Primary**: `--color-surface-primary` → #ffffff
- **Border Default**: `--color-border-default` → #e5e7eb

## Typography

### Font Families
- Sans: `'Inter', system-ui, sans-serif` (`--font-sans`)

### Size Scale
- Small: 0.875rem (`--font-size-sm`)
- Base: 1rem (`--font-size-base`)
- Large: 1.125rem (`--font-size-lg`)

## Spacing Scale
- 1: 0.25rem (4px) — `--spacing-1`
- 2: 0.5rem (8px) — `--spacing-2`
- 4: 1rem (16px) — `--spacing-4`
- 8: 2rem (32px) — `--spacing-8`

Example 2: Tailwind Config

Input (tailwind.config.ts):

import type { Config } from 'tailwindcss'

export default {
  theme: {
    extend: {
      colors: {
        primary: {
          50: '#eff6ff',
          500: '#3b82f6',
          900: '#1e3a8a',
        },
        semantic: {
          text: '#1e3a8a',
          surface: '#ffffff',
          border: '#e5e7eb',
        },
      },
      fontFamily: {
        sans: ['Inter', 'system-ui', 'sans-serif'],
      },
      spacing: {
        '1': '0.25rem',
        '2': '0.5rem',
        '4': '1rem',
        '8': '2rem',
      },
      borderRadius: {
        'sm': '0.125rem',
        'md': '0.375rem',
        'lg': '0.5rem',
      },
    },
  },
} satisfies Config

Example 3: TypeScript Theme Object

Input (src/theme/tokens.ts):

export const tokens = {
  colors: {
    base: {
      blue50: '#eff6ff',
      blue500: '#3b82f6',
      blue900: '#1e3a8a',
    },
    semantic: {
      textPrimary: '#1e3a8a',
      surfacePrimary: '#ffffff',
      borderDefault: '#e5e7eb',
    },
  },
  typography: {
    fontFamily: {
      sans: "'Inter', system-ui, sans-serif",
    },
    fontSize: {
      sm: '0.875rem',
      base: '1rem',
      lg: '1.125rem',
    },
  },
  spacing: {
    1: '0.25rem',
    2: '0.5rem',
    4: '1rem',
    8: '2rem',
  },
  borderRadius: {
    sm: '0.125rem',
    md: '0.375rem',
    lg: '0.5rem',
  },
} as const;

export type Tokens = typeof tokens;

Common Patterns

Pattern 1: Multi-Source Token Detection

The skill automatically merges tokens from multiple sources:

project/
├── src/
│   ├── styles/
│   │   ├── tokens.css        ← CSS variables
│   │   └── globals.css       ← Additional variables
│   └── theme/
│       └── config.ts         ← TypeScript tokens
└── tailwind.config.js        ← Tailwind tokens

All sources are parsed and consolidated into one design.md.

Pattern 2: Framework-Specific Usage

React with CSS Modules:

import styles from './Button.module.css';

export function Button({ children }: { children: React.ReactNode }) {
  return <button className={styles.button}>{children}</button>;
}

// Button.module.css
.button {
  color: var(--color-text-primary);
  padding: var(--spacing-2) var(--spacing-4);
  border-radius: var(--radius-md);
}

Vue with Tailwind:

<template>
  <button class="bg-primary-500 text-white px-4 py-2 rounded-md">
    {{ label }}
  </button>
</template>

<script setup lang="ts">
defineProps<{ label: string }>();
</script>

Svelte with CSS Variables:

<script lang="ts">
  export let variant: 'primary' | 'secondary' = 'primary';
</script>

<button class="btn {variant}">
  <slot />
</button>

<style>
  .btn {
    padding: var(--spacing-2) var(--spacing-4);
    border-radius: var(--radius-md);
  }
  .primary {
    background: var(--color-blue-500);
    color: white;
  }
</style>

Pattern 3: Semantic Color Roles

The skill automatically classifies color tokens into semantic roles:

/* Detected as "text" role */
--color-text-primary
--color-text-secondary
--text-default

/* Detected as "surface" role */
--color-surface-primary
--color-bg-default
--background-primary

/* Detected as "border" role */
--color-border-default
--border-subtle
--divider-color

/* Detected as "icon" role */
--color-icon-default
--icon-primary

Pattern 4: Responsive Breakpoints

Automatically extracts breakpoint config:

// tailwind.config.js
module.exports = {
  theme: {
    screens: {
      sm: '640px',
      md: '768px',
      lg: '1024px',
      xl: '1280px',
    },
  },
};

Generated in design.md:

## Responsive

### Breakpoints
- Mobile: < 640px
- Tablet: 640px (`sm`)
- Desktop: 1024px (`lg`)
- Wide: 1280px (`xl`)

### Approach
Mobile-first with `min-width` breakpoints

Troubleshooting

Issue: No tokens detected

Symptom: Plugin says "No token files found"

Solutions:

1. Verify token files exist in common paths
2. Use explicit path: /figma-design-system-to-design-md --tokens-dir ./src/styles
3. Check file patterns match (e.g., rename variables.css to tokens.css)

Issue: CSS variables not parsed correctly

Symptom: Colors or spacing values are missing/incorrect

Solutions:

1. Ensure CSS variables use standard format:

   /* ✅ Good */
   --color-blue-500: #3b82f6;
   --spacing-4: 1rem;
   
   /* ❌ Bad (calc not supported yet) */
   --spacing-4: calc(0.25rem * 4);
   

2. Use clear semantic naming:

   /* ✅ Detected as semantic role */
   --color-text-primary: #000;
   
   /* ❌ Not detected as semantic */
   --black: #000;
   

Issue: Figma MCP not working

Symptom: Component data not appearing in design.md

Solutions:

1. Verify Figma desktop app is latest version
2. Enable MCP Server: Preferences → Dev Mode → Enable MCP Server
3. Restart Claude Code after enabling MCP
4. Open the correct Figma design file
5. Check Figma file has components (not just frames)

Issue: Tailwind config not detected

Symptom: Tailwind tokens missing from design.md

Solutions:

1. Ensure config is in project root or config/ directory
2. Check file extension (.js, .ts, .mjs all supported)
3. Verify config exports theme.extend:

   // ✅ Good
   export default {
     theme: {
       extend: { colors: {...} }
     }
   }
   
   // ❌ Bad (missing extend)
   export default {
     colors: {...}
   }
   

Issue: Generated design.md is incomplete

Symptom: Some sections are missing

Solutions:

1. Some sections require manual input (Overview, Do's and Don'ts)
2. Component data requires Figma MCP (optional)
3. Elevation/shadows may need Tailwind config or MCP
4. Run with --verbose to see what was detected:

   /figma-design-system-to-design-md --verbose
   

Best Practices

Token Naming Conventions

Use clear, semantic names for better detection:

/* ✅ Recommended */
--color-text-primary
--color-surface-primary
--color-border-default
--spacing-4
--font-size-base
--radius-md

/* ❌ Avoid */
--blue
--padding
--size
--round

Project Structure

Organize tokens for easy detection:

project/
├── src/
│   └── styles/
│       ├── tokens.css          ← Main tokens
│       ├── theme-light.css     ← Light theme
│       └── theme-dark.css      ← Dark theme
├── tailwind.config.ts          ← Framework config
└── design.md                   ← Generated docs

Keep Tokens DRY

Use variables that reference other variables:

:root {
  /* Base palette */
  --color-blue-500: #3b82f6;
  
  /* Semantic roles */
  --color-text-link: var(--color-blue-500);
  --color-border-focus: var(--color-blue-500);
}

The skill will resolve references and document the relationships.

Environment Variables

If using Figma MCP with authentication:

# .env
FIGMA_ACCESS_TOKEN=figd_your_token_here

Reference in code:

const figmaToken = process.env.FIGMA_ACCESS_TOKEN;

Never commit real tokens — use .env.local and add to .gitignore.

Advanced Usage

Custom Token Parsers

If your tokens use a non-standard format, you can specify a custom parser pattern:

/figma-design-system-to-design-md --parser-config ./parser-config.json

parser-config.json:

{
  "colorPattern": "COLOR_([A-Z_]+): '(#[0-9a-f]{6})'",
  "spacingPattern": "SPACE_([A-Z_]+): '([0-9.]+(?:rem|px))'",
  "typographyPattern": "FONT_([A-Z_]+): '([^']+)'"
}

Continuous Integration

Generate design.md automatically on token changes:

# .github/workflows/design-md.yml
name: Update design.md
on:
  push:
    paths:
      - 'src/styles/**'
      - 'tailwind.config.*'

jobs:
  update-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: anthropics/setup-claude@v1
      - run: claude /figma-design-system-to-design-md
      - uses: stefanzweifel/git-auto-commit-action@v4
        with:
          commit_message: 'chore: update design.md'
          file_pattern: 'design.md'

---

Resources:

• Web Version
• GitHub Repository
• Google Stitch design.md Spec
• MIT License