Figma Design Tokens Sync Tool

Automated tool to sync design tokens from Figma to your codebase. Extracts colors from your Figma design system and automatically updates your website's CSS/Tailwind configuration.

Features

• 🎨 Automatic Color Extraction - Fetches all published color styles from Figma
• 🔄 Auto-Updates Code - Automatically updates Tailwind CSS configuration
• 📦 Fallback Support - Works with published libraries or document parsing
• 🛠️ Easy Setup - Simple Node.js script, no build tools required
• 📝 Comprehensive Docs - Includes workflow guides and troubleshooting

Quick Start

Prerequisites

• Node.js installed
• Figma Personal Access Token
• Figma file with published color styles

Installation

1. Clone this repository:

git clone https://github.com/JDHalpin/figma-design-tokens.git
cd figma-design-tokens

2. Copy the example environment file:

cp .env.example .env

3. Add your Figma credentials to .env:

FIGMA_TOKEN=your_figma_token_here
FIGMA_FILE_ID=your_figma_file_id

Getting Your Figma Credentials

Personal Access Token:

1. Go to https://www.figma.com/settings
2. Scroll to "Personal access tokens"
3. Click "Generate new token"
4. Select these scopes:
   • File content: Read
   • File metadata: Read
   • Design systems library assets: Read
5. Copy the token immediately

File ID: From your Figma URL: https://www.figma.com/design/FILE_ID/... Example: vFzy38cYS83Xj5CCqdTvi4

Usage

Run the sync script:

export $(cat .env | xargs) && node sync-design-tokens.js

What it does:

1. Fetches your Figma file data
2. Extracts all published color styles
3. Converts RGB to hex codes
4. Saves color data to JSON
5. Updates your HTML/CSS files (configurable)

Output Files

File	Description
figma_colors.json	Extracted color tokens with hex and RGB values
figma_data.json	Complete Figma file structure

Configuration

The script can be customized to update different file formats:

• Tailwind CSS config
• CSS custom properties
• SCSS variables
• JSON design tokens
• And more...

See SYNC_WORKFLOW.md for detailed customization options.

How It Works

The tool uses the Figma REST API to:

1. Fetch Published Styles - Queries /v1/files/:id/styles for published color styles
2. Get Color Values - Fetches node data to extract actual RGB values
3. Convert & Format - Transforms RGB (0-1 range) to hex codes
4. Update Code - Automatically updates your configuration files

Important: Uses X-Figma-Token header (not Authorization: Bearer)

Use Cases

• Design Systems - Keep design tokens in sync between Figma and code
• Component Libraries - Automatically update theme colors
• Documentation - Generate color palettes from Figma
• CI/CD Integration - Automate design updates in build pipelines

Example Output

[
  {
    "id": "8:62",
    "name": "Accent",
    "description": "Primary accent color",
    "hex": "#079E87",
    "rgb": { "r": 0.027, "g": 0.619, "b": 0.530, "a": 1 }
  },
  {
    "id": "9:68",
    "name": "Text/Primary",
    "description": "Body copy",
    "hex": "#181818",
    "rgb": { "r": 0.094, "g": 0.094, "b": 0.095, "a": 1 }
  }
]

Troubleshooting

"Invalid token" error

• Regenerate your token at https://www.figma.com/settings
• Ensure all required scopes are selected
• Use the "Copy the token" button when it's displayed

No colors extracted

• Publish your color styles in Figma (right-click file → "Publish styles and components")
• Ensure color styles are FILL type (not text or effect styles)
• Check that your token has "Design systems library assets: read" scope

File not found

• Move file from Drafts to a team project folder
• Verify the file ID is correct
• Ensure you have access to the file

See SYNC_WORKFLOW.md for more detailed troubleshooting.

Documentation

• SYNC_WORKFLOW.md - Complete workflow guide with setup and troubleshooting
• DESIGN_TOKENS.md - Design token reference and documentation

Example Project

See the tool in action: JDHalpin/portfolio

This portfolio uses the sync tool to keep its design system in sync with Figma.

Contributing

Issues and pull requests welcome! This tool was built to solve a real workflow problem - if you have suggestions or improvements, please share them.

License

MIT

Author

Jeff Halpin

• GitHub: @JDHalpin
• Portfolio: Built with this tool!

---

Built with Claude Code