🎨 Quill Design System - Figma Token Automation

Automatically sync design tokens from Figma to code with one command

A powerful automation tool that bridges the gap between design and development by automatically extracting design tokens from Figma and generating production-ready CSS, TypeScript, and utility classes.

📋 Table of Contents

• Quick Start
• Features
• Prerequisites
• Installation
• Usage
• Component Development
• For Designers
• For Developers
• Common Tasks
• Documentation
• Troubleshooting
• Contributing

🚀 Quick Start

For Component Usage

# Install the package
npm install @deriv-com/quill-ui-v2

# Use components in your app
import { Button } from '@deriv-com/quill-ui-v2';

For Token Usage (Custom Styling)

# Install the package
npm install @deriv-com/quill-ui-v2

# Import tokens in your app
import '@deriv-com/quill-ui-v2/tokens.css';

# Use tokens in your CSS
.custom-element {
  padding: var(--quill-semantic-size-spacing-16);
  background: var(--quill-semantic-colour-background-canvas);
}

📖 See the Token Usage Guide for complete documentation.

For Development

Get up and running in 5 minutes:

# 1. Install dependencies
npm install

# 2. Set up credentials
cp .env.example .env
# Edit .env with your Figma token and file key

# 3. Sync tokens from Figma
npm run tokens

# 4. Build the package
npm run build

New to the project? Follow the detailed installation guide below.

✨ Features

Core Capabilities

• ✅ Automatic Sync - One command updates all tokens from Figma
• ✅ Multi-Collection Support - Handle multiple token collections (primitives, semantic, etc.)
• ✅ Multi-File Output - Organized CSS files by collection
• ✅ NPM Package Export - Tokens available as separate CSS files for custom styling
• ✅ TypeScript Support - Type-safe tokens with autocomplete
• ✅ Token Validation - Automatic error detection and warnings
• ✅ Version Tracking - Semantic versioning for changes
• ✅ Figma Styles - Import text, color, and effect styles
• ✅ Theme Support - Light/dark mode with system preference detection
• ✅ Watch Mode - Continuous monitoring for design changes
• ✅ Dry Run - Preview changes before applying
• ✅ CI/CD Ready - Automated token syncing in pipelines

Generated Outputs

| File | Purpose | Auto-Generated | | ------------------------------------------------- | ---------------------------------- | -------------- | | index.css | Main import file for all tokens | ✅ | | primitives.css | Base design tokens (colors, sizes) | ✅ | | semantic.css | Semantic tokens (spacing, radius) | ✅ | | figma-styles.css | Figma style tokens | ✅ | | tokens.d.ts | TypeScript definitions | ✅ | | tokens.js | JavaScript module | ✅ | | version.json | Version metadata | ✅ |

🔧 Prerequisites

Before you begin, ensure you have:

Required

• Node.js >= 18.0.0 (Download)
• npm >= 9.0.0 (comes with Node.js)
• Figma account with access to your design file
• Figma Personal Access Token (Get one here)

System Requirements

| Platform | Supported | Tested | | -------- | --------- | ------ | | macOS | ✅ Yes | ✅ | | Windows | ✅ Yes | ✅ | | Linux | ✅ Yes | ✅ |

📦 Installation

Step 1: Install Dependencies

npm install

This installs:

• dotenv (^17.2.3) - Environment variable management

Step 2: Configure Figma Access

2.1 Get Your Figma Personal Access Token

1. Go to Figma Settings
2. Navigate to Account → Personal Access Tokens
3. Click Generate new token
4. Give it a name (e.g., "Token Automation")
5. Copy the token (starts with figd_)

2.2 Get Your Figma File Key

1. Open your Figma file in the browser
2. Copy the file key from the URL:

   https://www.figma.com/design/FILE_KEY_HERE/...
                              ^^^^^^^^^^^^

2.3 Create Environment File

# Copy the example file
cp .env.example .env

# Edit with your credentials
nano .env

Add your credentials:

# Your Figma Personal Access Token
FIGMA_ACCESS_TOKEN=figd_your_token_here

# Your Figma File Key
FIGMA_FILE_KEY=your_file_key_here

Step 3: Verify Setup

# Test the connection
npm run tokens

Expected output:

🚀 Starting Figma token extraction...
📡 Fetching from Figma REST API...
✅ Fetched 497 variables from 2 collection(s)
   📁 Collection: "primitives"
      Modes: default
   📁 Collection: "semantic"
      Modes: default
✨ Done!

💻 Usage

Using the NPM Package

Install the Package

npm install @deriv-com/quill-ui-v2

Import Components (CSS Bundled)

import { Button, Textfield, SearchField } from '@deriv-com/quill-ui-v2';

// Components include their styles automatically
<Button variant="primary">Click me</Button>

Import Tokens for Custom Styling

// In your app entry point (main.tsx, App.tsx, etc.)
import '@deriv-com/quill-ui-v2/tokens.css';

// Now use tokens in your CSS

.custom-element {
  padding: var(--quill-semantic-size-spacing-16);
  background: var(--quill-semantic-colour-background-canvas);
  color: var(--quill-semantic-colour-text-prominent-default);
  border-radius: var(--quill-semantic-size-radius-8);
}

Import Tokens in JavaScript

import { tokens } from '@deriv-com/quill-ui-v2/tokens';

const styles = {
  padding: tokens['--quill-semantic-size-spacing-16'],
  background: tokens['--quill-semantic-colour-background-canvas']
};

Converting Figma MCP Output to Tokens

When Figma MCP generates code, it outputs hard-coded values with token names in comments:

/* ❌ Figma MCP Output */
.header {
  gap: 16px; /* Figma token: quill-semantic-spacing-16 */
  padding: 16px 0; /* Figma token: quill-semantic-spacing-16 */
  background-color: #ebecef; /* Figma token: tertiary/background/default */
  border-radius: 999px; /* Figma token: size/radius */
}

Convert to use design tokens:

/* ✅ With Design Tokens */
.header {
  gap: var(--quill-semantic-size-spacing-16);
  padding: var(--quill-semantic-size-spacing-16) 0;
  background-color: var(--quill-semantic-colour-button-tertiary-bg-default);
  border-radius: var(--quill-semantic-size-radius-999);
}

Common Token Patterns

/* Custom Button */
.custom-button {
  padding: var(--quill-semantic-size-spacing-12) var(--quill-semantic-size-spacing-20);
  background: var(--quill-semantic-colour-button-primary-bg-default);
  color: var(--quill-semantic-colour-button-primary-text);
  border-radius: var(--quill-semantic-size-radius-999);
  font-size: var(--quill-semantic-typography-body-standard-size);
}

/* Custom Card */
.custom-card {
  padding: var(--quill-semantic-size-spacing-24);
  background: var(--quill-semantic-colour-background-surface);
  border: 1px solid var(--quill-semantic-colour-border-default-default);
  border-radius: var(--quill-semantic-size-radius-8);
}

/* Custom Text */
.custom-heading {
  font-family: var(--quill-semantic-typography-font-family);
  font-size: var(--quill-semantic-typography-title-section-size);
  color: var(--quill-semantic-colour-text-prominent-default);
}

Available Token Categories

• Colors: --quill-semantic-colour-* (text, background, border)
• Spacing: --quill-semantic-size-spacing-* (4, 8, 16, 24, etc.)
• Sizing: --quill-semantic-size-width-height-* (32, 48, 56, etc.)
• Border Radius: --quill-semantic-size-radius-* (8, 16, 999)
• Typography: --quill-semantic-typography-* (font-size, font-family, font-weight)

Development Commands

Command Line

# Fetch from Figma and generate all files
npm run tokens

# Use cached data (skip API call)
npm run tokens:cached

# Preview changes without writing files
npm run tokens:dry-run

# Watch for changes continuously
npm run tokens:watch

# CI/CD mode with strict validation
npm run tokens:ci

In HTML (Development)

<!DOCTYPE html>
<html>
  <head>
    <!-- Import all tokens -->
    <link rel="stylesheet" href="./src/tokens/index.css" />
  </head>
  <body>
    <!-- Use CSS variables -->
    <div style="color: var(--quill-core-color-blue-500)">Custom styled element</div>
  </body>
</html>

In CSS

/* Import tokens */
@import "./src/tokens/index.css";

/* Use in your styles */
.my-button {
  background: var(--quill-core-color-blue-500);
  padding: var(--quill-core-spacing-md);
  border-radius: var(--quill-core-radius-lg);
}

In JavaScript/TypeScript

import { tokens } from "./src/tokens/tokens.js";
import type { TokenName, TokenValue } from "./src/tokens/tokens";

// Type-safe token access with autocomplete!
const primaryColor: string = tokens["--quill-core-color-blue-500"];
const spacing: string = tokens["--quill-core-spacing-md"];

// Use in dynamic styles
element.style.setProperty("background-color", primaryColor);
element.style.setProperty("padding", spacing);

In React

import "./src/tokens/index.css";
import { tokens } from "./src/tokens/tokens";

function Button({ children }: { children: React.ReactNode }) {
  return (
    <button
      style={{
        backgroundColor: tokens["--quill-core-color-blue-500"],
        padding: tokens["--quill-core-spacing-md"],
        borderRadius: tokens["--quill-core-radius-lg"],
      }}
    >
      {children}
    </button>
  );
}

🧩 Component Development

This design system includes comprehensive guidelines for building consistent, accessible components.

Getting Started with Components

All components must follow the standardized structure and patterns defined in our documentation:

• Component Guidelines - Complete standards for building components
• Component Prompt Template - Fill-in template for creating new components

Component Structure

Each component includes 6 required files:

src/components/{component-name}/
├── {ComponentName}.tsx           # React component
├── {ComponentName}.module.css    # Styles with design tokens
├── {ComponentName}.stories.tsx   # Storybook stories
├── {ComponentName}.spec.json     # Cross-platform specification
├── index.ts                      # Public exports
└── README.md                     # Documentation

Quick Component Creation

1. Sync design tokens: Run npm run tokens to sync from Figma
2. Review the guidelines: Read docs/guideline.md
3. Fill the prompt template: Use docs/prompt.md
4. Extract with Figma MCP: Use Figma MCP tools to get component specs
5. Create all 6 files: Generate from Figma data
6. Export component: Add to src/index.ts

Example: Creating a Button from Figma

# 1. Sync tokens from Figma Variables
npm run tokens

# 2. Get Figma component node ID (e.g., "2074:7")

# 3. Use Figma MCP tools to extract:
# - get_design_context(nodeId)
# - get_variable_defs(nodeId)
# - get_screenshot(nodeId)
# - get_metadata(nodeId)

# 4. Generate component files from Figma data

# 5. Export in src/index.ts

See docs/prompt.md for complete Figma-driven examples.

Design Token Integration

All components must use design tokens from src/tokens/:

/* ✅ CORRECT - Use design tokens */
.button {
  background: var(--quill-semantic-background-action-brand-normal);
  padding: var(--quill-semantic-spacing-24);
  border-radius: var(--quill-semantic-radius-999);
}

/* ❌ WRONG - Never hardcode values */
.button {
  background: #0066cc;
  padding: 24px;
  border-radius: 999px;
}

Component Checklist

Before submitting a component, verify:

• [ ] All 6 files created
• [ ] Uses design tokens (no hardcoded values)
• [ ] All states implemented (hover, active, focus, disabled)
• [ ] Storybook stories complete
• [ ] Accessibility requirements met
• [ ] TypeScript types exported
• [ ] Component exported in src/index.ts
• [ ] README documentation complete

🎨 For Designers

Setting Up Figma Variables

1. Create Collections in Figma's Variables panel

   • Primitives: Base colors, sizes, typography
   • Semantic: Contextual tokens (spacing, radius, etc.)

2. Name Variables using forward slashes for grouping:

   colour/blue/500
   size/spacing/md
   typography/heading/large

3. Use Modes for themes (optional):

   • Light mode
   • Dark mode
   • High contrast variants

Best Practices

✅ DO:

• Use consistent naming conventions
• Group related tokens together
• Document token purposes in descriptions
• Test tokens in Dev Mode before syncing

❌ DON'T:

• Use spaces or special characters in names
• Create circular references
• Delete tokens without coordinating with developers
• Mix different token types in one collection

Testing Your Changes

Before asking developers to sync:

1. Preview in Dev Mode - Check CSS variable names
2. Test References - Ensure all aliases resolve correctly
3. Verify Modes - Test light/dark theme switching
4. Document Changes - Note any breaking changes

Syncing Code Syntax to Figma

After developers generate tokens, update Figma with CSS syntax:

1. Open your Figma file
2. Open the plugin console: Option + Command + I (Mac) or Ctrl + Alt + I (Windows)
3. Copy contents of scripts/tokens/tokenVariableSyntaxAndDescriptionSnippet.js
4. Paste into console and press Enter
5. Wait for "DONE!" message

This allows you to see CSS variable names in Figma's Dev Mode.

👨‍💻 For Developers

Workflow

1. Sync tokens when designers notify you of changes:

   npm run tokens

2. Review changes before committing:

   git diff src/tokens/

3. Test in your application

4. Commit changes:

   git add src/tokens/
   git commit -m "chore: sync design tokens from Figma"
   git push

Integration Examples

Tailwind CSS

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: {
        primary: "var(--quill-core-color-blue-500)",
        secondary: "var(--quill-core-color-gray-500)",
      },
      spacing: {
        xs: "var(--quill-core-spacing-xs)",
        sm: "var(--quill-core-spacing-sm)",
        md: "var(--quill-core-spacing-md)",
      },
    },
  },
};

Styled Components

import styled from "styled-components";
import { tokens } from "./src/tokens/tokens";

const Button = styled.button`
  background: ${tokens["--quill-core-color-blue-500"]};
  padding: ${tokens["--quill-core-spacing-md"]};
  border-radius: ${tokens["--quill-core-radius-lg"]};
`;

CSS Modules

/* Button.module.css */
.button {
  background: var(--quill-core-color-blue-500);
  padding: var(--quill-core-spacing-md);
  border-radius: var(--quill-core-radius-lg);
}

Version Control

What to commit:

• ✅ All files in src/tokens/
• ✅ scripts/tokens/version.json (optional)

What to ignore:

• ❌ scripts/tokens/tokens.json (raw data, can be regenerated)
• ❌ .env (contains secrets)

📝 Common Tasks

Preview Changes Before Applying

# Dry run shows what would change without writing files
npm run tokens:dry-run

Output:

🔍 Dry Run - Preview of Changes:
════════════════════════════════════════════════════════════
⚠️  DRY RUN MODE - No files will be written
════════════════════════════════════════════════════════════

✨ Created (1):
   ./src/tokens/figma-styles.css (1.8 KB)

✏️  Modified (2):
   ./src/tokens/primitives.css
      22.7 KB → 22.5 KB (-188 B)
   ./src/tokens/tokens.d.ts
      53.2 KB → 53.8 KB (+648 B)

════════════════════════════════════════════════════════════
Total: 3 file(s) processed
📋 3 file(s) would be updated

Watch for Changes During Development

# Continuously monitor Figma for changes
npm run tokens:watch

The script will:

• Poll Figma every 30 seconds (configurable)
• Detect when tokens change
• Prompt you to regenerate
• Continue watching after updates

Use Cached Data for Faster Iteration

# Skip API call, use existing tokens.json
npm run tokens:cached

Useful when:

• Testing configuration changes
• Iterating on output formats
• Working offline

Automate in CI/CD

# CI mode with strict validation
npm run tokens:ci

Features:

• Exits with proper error codes
• Shows detailed error messages
• Prevents interactive prompts
• Validates tokens strictly

See CONFIGURATION.md for complete CI/CD setup.

📚 Documentation

| Document | Purpose | Audience | | ---------------------------------------- | -------------------------------- | ------------------- | | README.md (this file) | Quick start and overview | Everyone | | guideline.md | Figma-driven component standards | Developers | | prompt.md | Figma MCP prompt templates | Developers | | CONFIGURATION.md | Token extractor configuration | Developers | | API-REFERENCE.md | Technical API documentation | Advanced developers |

Quick Links

• Components: Figma-Driven Guidelines • Figma MCP Prompts • Component Structure
• Configuration: Environment Variables • Config Class • Collections
• Advanced: CI/CD Setup • Watch Mode • Batch API
• API: Architecture • Modules • Extending

🆘 Troubleshooting

"FIGMA_ACCESS_TOKEN is not defined"

Problem: Environment variables not loaded

Solution:

# 1. Verify .env file exists
ls -la .env

# 2. Check file contents
cat .env

# 3. Ensure proper format (no quotes needed)
FIGMA_ACCESS_TOKEN=figd_your_token_here
FIGMA_FILE_KEY=your_file_key_here

# 4. Restart your terminal/IDE

"Collection not found in tokens.json"

Problem: Collection name mismatch between Figma and configuration

Solution:

1. Check your Figma collection names
2. Names are normalized: "My Colors" → my_colors
3. Update COLLECTION_DATA in configuration
4. Run without --skip-rest-api to fetch fresh data:

   npm run tokens

"Failed to fetch from Figma API"

Problem: API connection or authentication issues

Solution:

# 1. Verify token is valid
curl -H "X-Figma-Token: YOUR_TOKEN" \
  https://api.figma.com/v1/files/YOUR_FILE_KEY/variables/local

# 2. Check token permissions
# Token must have "File content" read access

# 3. Verify file key is correct
# Should be from URL: figma.com/design/FILE_KEY/...

# 4. Check network connectivity
ping api.figma.com

TypeScript Errors with Token Imports

Problem: TypeScript can't find token definitions

Solution:

// 1. Ensure tokens.d.ts is generated
// Check: src/tokens/tokens.d.ts exists

// 2. Add to tsconfig.json
{
  "compilerOptions": {
    "types": ["./src/tokens/tokens"]
  }
}

// 3. Import correctly
import type { TokenName } from './src/tokens/tokens';
import { tokens } from './src/tokens/tokens';

More Help

• Check CONFIGURATION.md for configuration issues
• See API-REFERENCE.md for technical problems
• Review existing GitHub Issues

🤝 Contributing

Reporting Issues

When reporting issues, please include:

• Environment: OS, Node.js version
• Steps to reproduce: Exact commands run
• Expected behavior: What should happen
• Actual behavior: What actually happened
• Error messages: Full error output
• Screenshots: If applicable

Adding Features

1. Create feature branch

   git checkout -b feature/your-feature-name

2. Make changes

   • Update relevant files
   • Add tests for new functionality
   • Update documentation

3. Test thoroughly

   npm test
   npm run tokens

4. Submit PR

   • Provide clear description
   • Include before/after examples
   • Link related issues

Code Style

• Use ES modules (import/export)
• Add JSDoc comments for functions
• Follow existing naming conventions
• Keep functions focused and small
• Add console logging for user feedback

📊 Project Stats

• 497 Figma variables imported
• 508 total tokens generated
• 2 collections (primitives, semantic)
• 161 tests passing (100% pass rate)
• 6 core features enabled

📝 License

MIT License - see LICENSE file for details

🙏 Acknowledgments

• Built with Figma Variables API
• Follows W3C Design Tokens Format
• Inspired by design system best practices

📞 Support

• Quick questions: Check Troubleshooting section
• Setup help: See Installation guide
• Configuration: Read CONFIGURATION.md
• Technical details: Review API-REFERENCE.md
• Issues: Use GitHub Issues (if applicable)

Ready to sync your design system? Let's go! 🚀

npm run tokens