dss/dss-claude-plugin/skills/figma-sync/SKILL.md

name, description, globs, alwaysApply

name	description	globs	alwaysApply
Figma Sync	Synchronize design tokens from Figma files using the Figma API	**/figma-tokens/** **/design-tokens/** **/*.figma.json	false

Figma Sync

Overview

This skill enables synchronization of design tokens from Figma files. It extracts colors, typography, spacing, and other design decisions from Figma and converts them to code-ready tokens.

When to Use

Use this skill when the user asks to:

• Import tokens from Figma
• Sync design decisions with code
• Extract colors from Figma file
• Update tokens from Figma changes
• Connect Figma to the design system

Prerequisites

Figma Token

Set the FIGMA_TOKEN environment variable:

export FIGMA_TOKEN=your-figma-personal-access-token

File Key

Get the file key from Figma URL:

https://www.figma.com/file/XXXXXXXXXXXXXX/Design-System
                            ^^^^^^^^^^^^^^
                            This is the file key

Extracted Token Types

Type	Figma Source	Token Output
Colors	Fill colors, Strokes	color.* tokens
Typography	Text styles	typography.* tokens
Spacing	Auto-layout gaps	spacing.* tokens
Shadows	Drop shadows	shadow.* tokens
Radii	Corner radius	radius.* tokens
Borders	Stroke weights	border.* tokens

Workflow

1. Get Figma File Key

   • Open Figma file in browser
   • Copy file key from URL

2. Sync Tokens

   Use dss_sync_figma with file_key
   

3. Review Extracted Tokens

   • Check token names
   • Verify values
   • Review categories

4. Generate Theme Files

   • Use theme generation skill
   • Export to CSS/SCSS/JSON

Example Interaction

User: "Sync design tokens from our Figma file"

Assistant Response:

I'll sync tokens from your Figma file.

First, I need the Figma file key. You can find it in the URL:
https://www.figma.com/file/[FILE_KEY]/Design-System

What's your file key?

**User:** abc123xyz456

[Uses dss_sync_figma with file_key: abc123xyz456]

**Figma Sync Results:**

**Extracted Tokens:**

Colors (24 tokens):
- primary/500: #0066CC
- primary/400: #3385D6
- primary/600: #0052A3
- secondary/500: #6C757D
- success/500: #28A745
- error/500: #DC3545

Typography (8 styles):
- heading/h1: Inter Bold 48px/56px
- heading/h2: Inter Bold 36px/44px
- heading/h3: Inter SemiBold 24px/32px
- body/regular: Inter Regular 16px/24px
- body/small: Inter Regular 14px/20px

Spacing (6 values):
- xs: 4px
- sm: 8px
- md: 16px
- lg: 24px
- xl: 32px
- 2xl: 48px

Shadows (3 styles):
- sm: 0 1px 2px rgba(0,0,0,0.05)
- md: 0 4px 6px rgba(0,0,0,0.1)
- lg: 0 10px 15px rgba(0,0,0,0.1)

**Total:** 41 tokens extracted

Would you like me to generate theme files from these tokens?

API Rate Limiting

The Figma API has rate limits:

• 30 requests per minute for free plans
• Higher limits for paid plans

DSS implements:

• Automatic retry with exponential backoff
• Request caching (1 hour TTL)
• Batch requests where possible

Token Naming

Figma names are converted to token format:

Figma: "Primary / 500"
Token: color-primary-500

Figma: "Heading / H1"
Token: typography-heading-h1

Figma: "Shadow / Medium"
Token: shadow-md

Error Handling

Error	Cause	Solution
403 Forbidden	Invalid token	Check FIGMA_TOKEN
404 Not Found	Invalid file key	Verify file key
429 Too Many Requests	Rate limited	Wait and retry

Related Tools

• dss_sync_figma - Main sync tool
• dss_extract_tokens - Merge with other sources
• dss_generate_theme - Generate from Figma tokens

Best Practices

1. Figma Organization

   • Use consistent naming in Figma
   • Organize styles in folders
   • Use descriptions for context

2. Sync Frequency

   • Sync after major design changes
   • Automate in CI/CD if possible
   • Version control token files

3. Conflict Resolution

   • Compare with existing tokens
   • Review changes before applying
   • Maintain changelog

Security Notes

• Never commit FIGMA_TOKEN to version control
• Use environment variables or secrets manager
• Rotate tokens periodically
• Use read-only tokens when possible