276ed71f31
Migrated from design-system-swarm with fresh git history.
Old project history preserved in /home/overbits/apps/design-system-swarm
Core components:
- MCP Server (Python FastAPI with mcp 1.23.1)
- Claude Plugin (agents, commands, skills, strategies, hooks, core)
- DSS Backend (dss-mvp1 - token translation, Figma sync)
- Admin UI (Node.js/React)
- Server (Node.js/Express)
- Storybook integration (dss-mvp1/.storybook)
Self-contained configuration:
- All paths relative or use DSS_BASE_PATH=/home/overbits/dss
- PYTHONPATH configured for dss-mvp1 and dss-claude-plugin
- .env file with all configuration
- Claude plugin uses ${CLAUDE_PLUGIN_ROOT} for portability
Migration completed: $(date)
🤖 Clean migration with full functionality preserved
189 lines
4.2 KiB
Markdown
189 lines
4.2 KiB
Markdown
---
|
|
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
|