Quick Start

YAML
# tokens.config.js - Style Dictionary configuration
module.exports = {
  source: ['tokens/**/*.json'],
  platforms: {
    css: {
      transformGroup: 'css',
      buildPath: 'dist/css/',
      files: [{
        destination: 'variables.css',
        format: 'css/variables'
      }]
    },
    js: {
      transformGroup: 'js',
      buildPath: 'dist/js/',
      files: [{
        destination: 'tokens.js',
        format: 'javascript/es6'
      }]
    }
  }
}

Workflow

1. Install "Variables to JSON" plugin in Figma
2. Structure variables using semantic naming: brand/color/primary/500
3. Export initial token set to establish baseline

design-tokens/
├── tokens/
│   ├── global/           # Base tokens (primitives)
│   ├── semantic/         # Context tokens (components)
│   └── brands/          # Brand overrides
├── transforms/          # Custom Style Dictionary transforms
├── .github/workflows/   # Automation
└── dist/               # Generated files

transforms/custom.js:

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

StyleDictionary.registerTransform({
  name: 'size/pxToRem',
  type: 'value',
  matcher: token => token.type === 'dimension',
  transformer: token => `${parseFloat(token.value) / 16}rem`
});

StyleDictionary.registerFormat({
  name: 'tailwind/config',
  formatter: dictionary => {
    return `module.exports = {
  theme: {
    colors: ${JSON.stringify(dictionary.allTokens
      .filter(token => token.type === 'color')
      .reduce((acc, token) => {
        acc[token.name] = token.value;
        return acc;
      }, {}), null, 2)}
  }
}`;
  }
});

.github/workflows/sync-tokens.yml:

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

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Fetch Figma Tokens
        run: |
          curl -H "X-Figma-Token: ${{ secrets.FIGMA_TOKEN }}" \
               "https://api.figma.com/v1/files/${{ vars.FIGMA_FILE_ID }}/variables/local" \
               > figma-tokens.json
      
      - name: Compare & Generate Diff
        run: |
          if ! cmp -s figma-tokens.json tokens/figma-export.json; then
            echo "TOKENS_CHANGED=true" >> $GITHUB_ENV
            cp figma-tokens.json tokens/figma-export.json
          fi
      
      - name: Build Tokens
        if: env.TOKENS_CHANGED == 'true'
        run: |
          npm ci
          npm run build:tokens
      
      - name: Create PR
        if: env.TOKENS_CHANGED == 'true'
        uses: peter-evans/create-pull-request@v5
        with:
          title: 'chore: sync design tokens from Figma'
          body: 'Automated token sync detected changes'
          branch: 'tokens/sync-${{ github.run_id }}'

Progress:

• Figma Variables to JSON plugin installed
• Repository structure created
• Style Dictionary config implemented
• GitHub Actions workflow deployed
• Token versioning strategy defined
• Multi-brand architecture configured

Examples

Example 1: Global Token Structure Input (Figma JSON):

JSON
{
  "color": {
    "blue": {
      "500": { "value": "#3b82f6", "type": "color" }
    }
  }
}

Output (CSS):

CSS
:root {
  --color-blue-500: #3b82f6;
}

Example 2: Multi-Brand Override Input (Brand A override):

JSON
{
  "semantic": {
    "color": {
      "primary": { "value": "{color.red.500}" }
    }
  }
}

Output (Tailwind config):

JavaScript
colors: {
  primary: '#ef4444'  // Resolved red.500 value
}

Token Versioning Strategy

package.json semantic versioning:

• MAJOR: Breaking changes (token removal, structure changes)
• MINOR: New tokens, non-breaking additions
• PATCH: Value updates (color adjustments, spacing tweaks)

Version detection script:

JavaScript
// scripts/version-check.js
const semver = require('semver');
const oldTokens = require('./tokens-old.json');
const newTokens = require('./tokens-new.json');

function detectBreakingChanges(old, new) {
  // Check for removed tokens
  const removedTokens = Object.keys(old).filter(key => !(key in new));
  return removedTokens.length > 0 ? 'major' : 'patch';
}

Multi-Brand Architecture

tokens/brands/brand-a.json:

JSON
{
  "semantic": {
    "color": {
      "primary": { "value": "{global.color.blue.600}" },
      "secondary": { "value": "{global.color.gray.400}" }
    }
  }
}

Build script for multiple brands:

JavaScript
// scripts/build-brands.js
const brands = ['brand-a', 'brand-b', 'default'];

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

Best Practices

• Use semantic naming: semantic.color.primary vs color.blue.500
• Implement token aliasing: reference global tokens in semantic layer
• Set up staging environment for token testing before production
• Use TypeScript definitions for token consumption
• Implement token documentation generation
• Create design-dev handoff checklist for new token requests

Common Pitfalls

• Avoid direct primitive token usage in components
• Don't manually edit generated files
• Never commit Figma API tokens to repository
• Don't mix naming conventions between tools
• Avoid deeply nested token structures (>4 levels)
• Don't skip version control for token changes