Figma to Markdown Generator

Generate structured markdown documentation from a Figma component using the existing documentation generation pipeline.

Usage

/figma-to-markdown <figma-url>
/figma-to-markdown https://figma.com/design/ABC123/File?node-id=1:234

What This Skill Does

Takes a Figma component URL and generates comprehensive markdown documentation including:

• YAML frontmatter with metadata, tokens, and accessibility info
• Component overview, variants, and states
• Design properties and styling tokens
• Tailwind configuration mappings
• CSS custom properties
• Accessibility guidelines
• Usage do's and don'ts

Template Reference

The generated documentation follows the structure defined in templates/component.md. Always ensure output matches this template format including:

• YAML frontmatter with all required fields
• All 12 standard sections in order
• Proper table formatting for variants, states, properties, styling

Step-by-Step Workflow

Step 1: Validate Input

Check that a Figma URL was provided as an argument:

• If no URL provided, ask the user for the Figma component URL
• Validate the URL format matches https://figma.com/... or https://www.figma.com/...
• Extract the file key and node-id from the URL

Valid URL formats:

• https://figma.com/design/ABC123/File-Name?node-id=1:234
• https://www.figma.com/file/ABC123/File-Name?node-id=1:234
• https://figma.com/design/ABC123/branch/XYZ/File?node-id=1:234

Step 2: Check Environment

Verify the FIGMA_TOKEN environment variable is set:

echo $FIGMA_TOKEN

If not set, inform the user:

FIGMA_TOKEN environment variable is required.
Set it with: export FIGMA_TOKEN=your_token_here

Step 3: Run Documentation Generator

Execute the generate script with the provided URL:

npm run docs:generate -- --url="<figma-url>"

The script will:

1. Connect to Figma API and extract component data
2. Analyze borders, variants, and design tokens
3. Generate markdown with YAML frontmatter
4. Auto-categorize into docs/components/{atoms|molecules|organisms}/
5. Save the file with kebab-case naming

Step 4: Verify Output

After generation completes:

1. Read the generated file to verify content
2. Check that frontmatter includes required fields:

- name, description, category, status, version, updated - tokens (colours, spacing, typography) - accessibility info

1. Confirm the file is in the correct category folder

Step 5: Update Changelog

Add an entry to CHANGELOG.md with today's date:

## {Date}

| Change | Type | JIRA | Figma | Notes |
|--------|------|------|-------|-------|
| Generated documentation for {ComponentName} | 🟢 Added | NA | [Figma]({figma-url}) | Auto-generated via /figma-to-markdown |

If updating existing documentation, use:

| Updated documentation for {ComponentName} | 🟡 Updated | NA | [Figma]({figma-url}) | Regenerated via /figma-to-markdown |

Step 6: Report Results

Summarize what was generated:

• File path: Location of the generated markdown file
• Component name: Name extracted from Figma
• Category: atoms/molecules/organisms
• Tokens found: Number of color, spacing, typography tokens
• Variants: Number of variants documented
• States: States included (default, hover, pressed, disabled, focus)

Output

Generated file: docs/components/{category}/{component-name}.md

The documentation follows the standard GDS format with:

• Self-contained sections (250-512 tokens) for optimal RAG chunking
• Tailwind utility class mappings
• CSS custom properties
• Design tokens prioritized over raw values

Error Handling

Common Errors

"FIGMA_TOKEN environment variable is required"

• Set the token: export FIGMATOKEN=yourtoken

"Invalid Figma URL"

• Ensure URL includes node-id parameter
• URL should start with https://figma.com or https://www.figma.com

"Node not found"

• Verify the node-id exists in the Figma file
• Check you have access to the Figma file

"Rate limit exceeded"

• Wait a few minutes and retry
• The generator includes automatic retry with backoff

Examples

Generate Button Documentation

/figma-to-markdown https://figma.com/design/ABC123/GDS?node-id=1:234

Output:

✓ Successfully generated: docs/components/atoms/button.md
  Component: Button
  Category: atoms

Generate Card Documentation

/figma-to-markdown https://figma.com/design/ABC123/GDS?node-id=5:678

Output:

✓ Successfully generated: docs/components/molecules/card.md
  Component: Card
  Category: molecules

Related Skills

• /figma-make-guidelines - Generate Tailwind configuration from foundations
• /project-summary - Update project summary with documentation coverage