figma-design-md-generator

# Figma DESIGN.md Generator > Skill by [ara.so](https://ara.so) — Design Skills collection. A Figma plugin that extracts local style guidelines, variables, and component families from Figma files and generates `DESIGN.md` and `SKILL.md` files. These outputs provide AI tools (Claude Code, Cursor, Codex) with structured design-system blueprints for building consistent interfaces. ## What It Does The plugin reads Figma's local styles and variables—colors, typography, spacing, radius, effects, grids, and component sets—and converts them into editable markdown files following the [TypeUI DESIGN.md](https://www.typeui.sh/design-md) format. **Key capabilities:** - Auto-extracts color tokens (paint styles + variables) - Auto-extracts typography tokens (text styles + scales) - Auto-extracts spacing, radius, motion tokens - Auto-extracts effect styles (shadows, blur) - Auto-extracts grid styles and component families - Generates human-editable `DESIGN.md` (reference documentation) - Generates AI-optimized `SKILL.md` (agent instructions) ## Installation ### As a Figma Plugin (Development Mode) 1. **Clone the repository:** ```bash git clone https://github.com/bergside/design-md-figma.git cd design-md-figma ``` 2. **Install dependencies:** ```bash npm install ``` 3. **Build the plugin:** ```bash npm run build ``` 4. **Import into Figma Desktop:** - Open Figma Desktop - Go to **Plugins → Development → Import plugin from manifest...** - Select `manifest.json` from the project directory - Run **Design MD Skill Generator** from the plugins menu ### Development Workflow ```bash # Watch mode for live development npm run watch # Type checking npm run typecheck # Production build npm run build ``` ## Key Plugin Actions | Action | Description | |--------|-------------| | **Auto-extract** | Reads local styles and variables from active Figma file | | **Generate DESIGN.md** | Creates design-guideline markdown from extracted signals | | **Generate SKILL.md** | Creates agent-ready markdown with implementation rules | | **Toggle view** | Switches between DESIGN.md and SKILL.md in editor | | **Refresh** | Re-runs extraction for current file state | | **Download** | Saves generated output as `.md` file | ## Plugin Architecture ### Main Entry Points **`code.ts`** – Plugin backend (runs in Figma sandbox): ```typescript figma.showUI(__html__, { width: 800, height: 600 }); // Listen for extraction requests figma.ui.onmessage = (msg) => { if (msg.type === 'extract-styles') { const styles = extractLocalStyles(); const variables = extractVariables(); const components = extractComponentFamilies(); figma.ui.postMessage({ type: 'extraction-complete', data: { styles, variables, components } }); } }; function extractLocalStyles() { const paintStyles = figma.getLocalPaintStyles(); const textStyles = figma.getLocalTextStyles(); const effectStyles = figma.getLocalEffectStyles(); const gridStyles = figma.getLocalGridStyles(); return { colors: paintStyles.map(s => ({ name: s.name, type: s.paints[0]?.type, value: paintToHex(s.paints[0]) })), typography: textStyles.map(s => ({ name: s.name, fontFamily: s.fontName.family, fontSize: s.fontSize, lineHeight: s.lineHeight })), effects: effectStyles.map(s => ({ name: s.name, effects: s.effects })), grids: gridStyles.map(s => ({ name: s.name, layoutGrids: s.layoutGrids })) }; } function extractVariables() { const collections = figma.variables.getLocalVariableCollections(); return collections.map(collection => ({ name: collection.name, modes: collection.modes, variables: collection.variableIds.map(id => { const variable = figma.variables.getVariableById(id); return { name: variable?.name, resolvedType: variable?.resolvedType, valuesByMode: variable?.valuesByMode }; }) })); } function extractComponentFamilies() { const components = figma.root.findAll(node => node.type === 'COMPONENT_SET' ) as ComponentSetNode[]; return components.map(comp => ({ name: comp.name, variantCount: comp.children.length, properties: Object.keys(comp.componentPropertyDefinitions || {}) })); } ``` **`ui.html`** – Plugin UI (React-based): ```typescript // Send extraction request window.parent.postMessage( { pluginMessage: { type: 'extract-styles' } }, '*' ); // Receive extraction results window.onmessage = (event) => { const msg = event.data.pluginMessage; if (msg.type === 'extraction-complete') { const designMd = generateDesignMd(msg.data); const skillMd = generateSkillMd(msg.data); setDesignContent(designMd); setSkillContent(skillMd); } }; ``` ## Generated File Structure ### DESIGN.md Format ```markdown # Design System – [File Name] ## Source - **File**: [Figma file name] - **Page**: [Current page] - **Extracted**: [ISO timestamp] ## Variable Collections - **Collection Name** (2 modes: Light, Dark) ## Color Tokens | Token | Value | Type | |-------|-------|------| | primary/500 | #3B82F6 | solid | | neutral/900 | #111827 | solid | ## Typography Tokens | Token | Font Family | Size | Line Height | Weight | |-------|-------------|------|-------------|--------| | heading/xl | Inter | 32px | 1.2 | 700 | | body/md | Inter | 16px | 1.5 | 400 | ## Spacing Tokens | Token | Value | |-------|-------| | spacing/xs | 4px | | spacing/md | 16px | ## Component Families - Button (variants: 8) - Input (variants: 6) - Card (variants: 4) ``` ### SKILL.md Format ```markdown # AI Design System Agent – [File Name] ## Mission Implement UI components that strictly follow the extracted design system from [File Name]. ## Brand - **Product**: [Inferred from file] - **Audience**: [Inferred context] - **Surface**: Web/Mobile ## Style Foundations ### Colors - Primary: #3B82F6 - Semantic: Success (#10B981), Error (#EF4444) ### Typography - Heading scale: 32/24/20/16px - Body scale: 16/14/12px - Font stack: Inter, system-ui, sans-serif ## Accessibility - WCAG 2.2 AA contrast (4.5:1 text, 3:1 UI) - Minimum touch target: 44×44px - Focus indicators required ## Rules: Do - Use extracted color tokens exactly - Apply typography tokens for all text - Respect spacing scale for layout - Implement all component variants ## Rules: Don't - Don't invent new colors outside token set - Don't use arbitrary font sizes - Don't skip accessibility requirements ``` ## Common Usage Patterns ### Extract and Download ```typescript // In plugin code async function extractAndGenerate() { // Extract all design tokens const styles = extractLocalStyles(); const variables = extractVariables(); const components = extractComponentFamilies(); // Generate markdown const designMd = formatDesignMd({ styles, variables, components }); const skillMd = formatSkillMd({ styles, variables, components }); // Send to UI for download figma.ui.postMessage({ type: 'download-ready', designMd, skillMd }); } ``` ### Convert Paint to Hex ```typescript function paintToHex(paint: Paint): string { if (paint.type === 'SOLID') { const r = Math.round(paint.color.r * 255); const g = Math.round(paint.color.g * 255); const b = Math.round(paint.color.b * 255); return `#${r.toString(16).padStart(2, '0')}${g.toString(16).padStart(2, '0')}${b.toString(16).padStart(2, '0')}`.toUpperCase(); } return 'gradient'; } ``` ### Format Typography Token ```typescript function formatTypographyToken(style: TextStyle) { const lineHeight = style.lineHeight.unit === 'PIXELS' ? `${style.lineHeight.value}px` : style.lineHeight.value; return { name: style.name, fontFamily: style.fontName.family, fontSize: `${style.fontSize}px`, fontWeight: style.fontWeight, lineHeight, letterSpacing: style.letterSpacing }; } ``` ### Extract Component Variants ```typescript function extractComponentVariants(componentSet: ComponentSetNode) { const variants = componentSet.children.map(child => { if (child.type === 'COMPONENT') { return { name: child.name, properties: child.variantProperties || {} }; } }).filter(Boolean); return { family: componentSet.name, count: variants.length, variants }; } ``` ## Using Generated Files with AI Tools ### Claude Code / Cursor 1. Place `DESIGN.md` and `SKILL.md` in project root 2. Reference in agent context: ``` @SKILL.md implement a button component following the design system ``` ### Prompt Engineering ``` Using the design tokens in DESIGN.md, create a React component for [Component Name] that: - Uses color tokens from primary palette - Applies typography token heading/md - Respects spacing/md for padding - Implements all variants listed in Component Families ``` ## Configuration The plugin reads Figma's native structures—no external configuration required. All extraction is based on: - Local paint styles - Local text styles - Local effect styles - Local grid styles - Variable collections - Component sets in current file ## Troubleshooting ### No Styles Extracted **Problem**: Plugin returns empty DESIGN.md **Solution**: Ensure you have local styles created in Figma. Shared library styles are not extracted—only local file styles. ```typescript // Check for local styles const paintStyles = figma.getLocalPaintStyles(); if (paintStyles.length === 0) { console.warn('No local paint styles found in this file'); } ``` ### Variables Not Showing **Problem**: Variable collections missing from output **Solution**: Verify variables are created as local collections, not external libraries. ```typescript const collections = figma.variables.getLocalVariableCollections(); console.log('Found collections:', collections.length); ``` ### Build Errors **Problem**: TypeScript compilation fails **Solution**: Ensure Figma plugin types are installed: ```bash npm install --save-dev @figma/plugin-typings ``` Update `tsconfig.json`: ```json { "compilerOptions": { "types": ["@figma/plugin-typings"] } } ``` ### Plugin Won't Load **Problem**: "Failed to load manifest" error **Solution**: Check `manifest.json` structure: ```json { "name": "Design MD Skill Generator", "id": "YOUR_PLUGIN_ID", "api": "1.0.0", "main": "code.js", "ui": "ui.html", "editorType": ["figma"] } ``` ## Best Practices 1. **Run extraction on finalized designs** – Ensure your local styles and variables are complete before generating files 2. **Name tokens consistently** – Use `/` separators for token hierarchy (e.g., `color/primary/500`) 3. **Version control generated files** – Commit `DESIGN.md` and `SKILL.md` alongside design system code 4. **Update after design changes** – Re-run extraction when design tokens change 5. **Combine with component library** – Use generated files as source of truth for design token implementation ## Resources - [TypeUI DESIGN.md format](https://www.typeui.sh/design-md)