---
name: Figma Sync
description: Synchronize design tokens from Figma files using the Figma API
globs:
  - "**/figma-tokens/**"
  - "**/design-tokens/**"
  - "**/*.figma.json"
alwaysApply: 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:
```bash
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