---
name: dss-figma
description: Sync design tokens from Figma files
arguments:
  - name: file_key
    description: Figma file key from the file URL
    required: true
---

# DSS Figma Command

Synchronize design tokens from Figma files using the Figma API.

## Usage

```
/dss-figma <file_key>
```

Example:
```
/dss-figma abc123xyz456
```

## Finding Your File Key

The file key is in your Figma URL:
```
https://www.figma.com/file/abc123xyz456/Design-System
                            ^^^^^^^^^^^^
                            This is the file key
```

## Prerequisites

Set your Figma token as an environment variable:
```bash
export FIGMA_TOKEN=your-figma-personal-access-token
```

## What This Does

1. **Connects to Figma API**
   - Authenticates with your token
   - Fetches file data
   - Handles rate limiting

2. **Extracts Tokens**
   - Colors from fill styles
   - Typography from text styles
   - Spacing from auto-layout
   - Shadows from effects
   - Border radii

3. **Normalizes Output**
   - Converts Figma naming to tokens
   - Organizes by category
   - Adds metadata

4. **Returns Token Collection**
   - Ready for theme generation
   - Merge-able with other sources

## Instructions for Claude

When the user runs this command:

1. Check if file_key is provided
2. Use `dss_sync_figma` tool with file_key
3. If error about missing token:
   - Explain how to get Figma token
   - Show how to set environment variable
4. On success:
   - Display extracted tokens by category
   - Show token count
   - Offer to generate theme files
5. Handle rate limiting gracefully

## Example Output

```
Figma Sync: abc123xyz456

CONNECTING TO FIGMA...
File: Design System v2.0
Last modified: 2024-01-15

TOKENS EXTRACTED

Colors (24 tokens):
  primary/500: #0066CC
  primary/400: #3385D6
  primary/600: #0052A3
  secondary/500: #6C757D
  success/500: #28A745
  warning/500: #FFC107
  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/large: Inter Regular 18px/28px
  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

Effects (3 shadows):
  shadow/sm: 0 1px 2px rgba(0,0,0,0.05)
  shadow/md: 0 4px 6px rgba(0,0,0,0.1)
  shadow/lg: 0 10px 15px rgba(0,0,0,0.1)

TOTAL: 41 tokens extracted

Next: Run /dss-generate css to create theme files
```

## Error Handling

```
ERROR: FIGMA_TOKEN not set

To sync with Figma, you need a Personal Access Token:

1. Go to Figma > Settings > Personal Access Tokens
2. Create a new token
3. Set it in your environment:
   export FIGMA_TOKEN=your-token-here

Then run /dss-figma again.
```