Quick Start

Bash
# 1. Initialize project structure
mkdir design-tokens-pipeline && cd design-tokens-pipeline
npm init -y
npm install style-dictionary @figma/rest-api-spec axios semver

# 2. Create basic token structure
mkdir -p tokens/{global,brands/{brand-a,brand-b}} build config

Workflow

Progress:

• Step 1: Export Figma variables to JSON
• Step 2: Configure Style Dictionary transformation
• Step 3: Set up GitHub Actions automation
• Step 4: Implement token versioning
• Step 5: Configure multi-brand overrides

Manual setup:

1. Install "Variables to JSON" plugin in Figma
2. Export variables to tokens/figma-export.json

tokens/figma-export.json (example structure):

JSON
{
  "collections": {
    "primitives": {
      "color": {
        "blue-500": { "value": "#3B82F6", "type": "color" },
        "spacing-md": { "value": "16px", "type": "dimension" }
      }
    }
  }
}

config/style-dictionary.config.js:

JavaScript
const StyleDictionary = require('style-dictionary');

module.exports = {
  source: ['tokens/**/*.json'],
  platforms: {
    css: {
      transformGroup: 'css',
      buildPath: 'build/css/',
      files: [{
        destination: 'variables.css',
        format: 'css/variables'
      }]
    },
    tailwind: {
      transformGroup: 'js',
      buildPath: 'build/tailwind/',
      files: [{
        destination: 'config.js',
        format: 'javascript/module-flat'
      }]
    },
    js: {
      transformGroup: 'js',
      buildPath: 'build/js/',
      files: [{
        destination: 'tokens.js',
        format: 'javascript/es6'
      }]
    }
  }
};

Transform tokens script (scripts/transform-figma-tokens.js):

JavaScript
const fs = require('fs');

function transformFigmaToTokens(figmaJson) {
  const tokens = {};
  
  Object.entries(figmaJson.collections).forEach(([collectionName, collection]) => {
    Object.entries(collection).forEach(([categoryName, category]) => {
      Object.entries(category).forEach(([tokenName, token]) => {
        const path = `${categoryName}.${tokenName}`;
        tokens[path] = {
          value: token.value,
          type: token.type
        };
      });
    });
  });
  
  return tokens;
}

const figmaData = JSON.parse(fs.readFileSync('tokens/figma-export.json'));
const transformedTokens = transformFigmaToTokens(figmaData);
fs.writeFileSync('tokens/global/base.json', JSON.stringify(transformedTokens, null, 2));

.github/workflows/sync-tokens.yml:

YAML
name: Sync Design Tokens
on:
  schedule:
    - cron: '0 */6 * * *'  # Every 6 hours
  workflow_dispatch:

jobs:
  sync-tokens:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
          
      - name: Install dependencies
        run: npm ci
        
      - name: Fetch Figma tokens
        run: node scripts/fetch-figma-tokens.js
        env:
          FIGMA_TOKEN: ${{ secrets.FIGMA_TOKEN }}
          FIGMA_FILE_KEY: ${{ secrets.FIGMA_FILE_KEY }}
          
      - name: Generate token diff
        run: node scripts/generate-diff.js
        
      - name: Build tokens
        run: npm run build:tokens
        
      - name: Create PR if changes
        uses: peter-evans/create-pull-request@v5
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          commit-message: 'Update design tokens from Figma'
          title: 'Design Tokens Update'
          body: 'Automated sync from Figma variables'
          branch: tokens/figma-sync

scripts/fetch-figma-tokens.js:

JavaScript
const axios = require('axios');
const fs = require('fs');

async function fetchFigmaVariables() {
  const response = await axios.get(
    `https://api.figma.com/v1/files/${process.env.FIGMA_FILE_KEY}/variables/local`,
    {
      headers: {
        'X-Figma-Token': process.env.FIGMA_TOKEN
      }
    }
  );
  
  return response.data.meta.variables;
}

async function main() {
  try {
    const variables = await fetchFigmaVariables();
    fs.writeFileSync('tokens/figma-variables.json', JSON.stringify(variables, null, 2));
    console.log('Figma variables fetched successfully');
  } catch (error) {
    console.error('Error fetching variables:', error);
    process.exit(1);
  }
}

main();

package.json scripts:

JSON
{
  "scripts": {
    "version:patch": "node scripts/version-tokens.js patch",
    "version:minor": "node scripts/version-tokens.js minor",
    "version:major": "node scripts/version-tokens.js major",
    "build:tokens": "node scripts/build-tokens.js"
  }
}

scripts/version-tokens.js:

JavaScript
const semver = require('semver');
const fs = require('fs');

const versionType = process.argv[2] || 'patch';
const currentVersion = JSON.parse(fs.readFileSync('package.json')).version;
const newVersion = semver.inc(currentVersion, versionType);

// Update package.json
const packageJson = JSON.parse(fs.readFileSync('package.json'));
packageJson.version = newVersion;
fs.writeFileSync('package.json', JSON.stringify(packageJson, null, 2));

// Create version metadata
const versionMetadata = {
  version: newVersion,
  timestamp: new Date().toISOString(),
  changes: versionType === 'major' ? 'breaking' : 'non-breaking'
};

fs.writeFileSync('build/version.json', JSON.stringify(versionMetadata, null, 2));
console.log(`Version bumped to ${newVersion}`);

tokens/brands/brand-a/overrides.json:

JSON
{
  "color": {
    "primary": { "value": "#FF6B6B", "type": "color" },
    "secondary": { "value": "#4ECDC4", "type": "color" }
  },
  "typography": {
    "font-family-primary": { "value": "Custom Brand Font", "type": "fontFamily" }
  }
}

config/multi-brand.config.js:

JavaScript
const StyleDictionary = require('style-dictionary');

const brands = ['brand-a', 'brand-b'];

brands.forEach(brand => {
  const config = {
    source: [
      'tokens/global/**/*.json',
      `tokens/brands/${brand}/**/*.json`
    ],
    platforms: {
      css: {
        transformGroup: 'css',
        buildPath: `build/${brand}/css/`,
        files: [{
          destination: 'variables.css',
          format: 'css/variables'
        }]
      }
    }
  };
  
  const sd = StyleDictionary.extend(config);
  sd.buildAllPlatforms();
});

Examples

Example 1: Complete token transformation Input: Figma Variables export with colors and spacing Output: CSS variables, Tailwind config, JS constants for each brand

Example 2: Automated sync workflow Input: Figma file changes detected Output: GitHub PR with updated tokens and version bump

Best Practices

• Use semantic versioning: patch for token value changes, minor for new tokens, major for removed/renamed tokens
• Implement token validation schema to catch breaking changes
• Use atomic commits for each token category (colors, typography, spacing)
• Set up staging environment for token previews before production
• Include visual regression tests in CI/CD pipeline
• Document token usage guidelines in README

Common Pitfalls

• Don't export all Figma variables at once - filter by collection/mode
• Don't skip the transformation step - raw Figma JSON isn't production-ready
• Don't ignore semantic versioning - breaking changes need major version bumps
• Don't hardcode brand names in base tokens - use override architecture
• Don't forget to handle token deletions in diff generation
• Don't commit large token files without Git LFS if over 100MB