Figma CI Integration

Overview

Automate Figma API workflows in CI/CD: sync design tokens on schedule, export assets on PR, and validate design system consistency.

Prerequisites

• GitHub repository with Actions enabled
• FIGMA_PAT stored as GitHub secret
• Design token extraction script (from figma-core-workflow-a)

Instructions

Step 1: Scheduled Token Sync Workflow

yaml
# .github/workflows/figma-token-sync.yml
name: Sync Figma Design Tokens

on:
  schedule:
    - cron: '0 9 * * 1-5'  # Weekdays at 9am UTC
  workflow_dispatch:          # Manual trigger

jobs:
  sync-tokens:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - run: npm ci

      - name: Extract tokens from Figma
        env:
          FIGMA_PAT: ${{ secrets.FIGMA_PAT }}
          FIGMA_FILE_KEY: ${{ vars.FIGMA_FILE_KEY }}
        run: node scripts/extract-figma-tokens.mjs

      - name: Check for changes
        id: diff
        run: |
          git diff --quiet src/styles/tokens.css || echo "changed=true" >> $GITHUB_OUTPUT

      - name: Create PR with token updates
        if: steps.diff.outputs.changed == 'true'
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          BRANCH="figma/token-sync-$(date +%Y%m%d)"
          git checkout -b "$BRANCH"
          git add src/styles/tokens.css
          git commit -m "chore: sync design tokens from Figma"
          git push origin "$BRANCH"
          gh pr create \
            --title "Sync design tokens from Figma" \
            --body "Automated token sync from Figma file. Review the CSS changes." \
            --label "design-tokens,automated"

Step 2: Asset Export on PR

yaml
# .github/workflows/figma-asset-export.yml
name: Export Figma Assets

on:
  pull_request:
    paths:
      - 'figma-config.json'  # Trigger when asset config changes

jobs:
  export-assets:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20' }
      - run: npm ci

      - name: Export icons from Figma
        env:
          FIGMA_PAT: ${{ secrets.FIGMA_PAT }}
          FIGMA_FILE_KEY: ${{ vars.FIGMA_ICON_FILE_KEY }}
          FIGMA_ICON_FRAME: ${{ vars.FIGMA_ICON_FRAME_ID }}
        run: node scripts/export-figma-icons.mjs

      - name: Commit exported assets
        run: |
          git add assets/icons/
          if ! git diff --cached --quiet; then
            git config user.name "github-actions[bot]"
            git config user.email "github-actions[bot]@users.noreply.github.com"
            git commit -m "chore: export icons from Figma"
            git push
          fi

Step 3: Design System Validation

yaml
      - name: Validate design tokens
        run: |
          # Check that all CSS custom properties are valid
          node -e "
            const fs = require('fs');
            const css = fs.readFileSync('src/styles/tokens.css', 'utf-8');
            const vars = css.match(/--[\w-]+:/g) || [];
            console.log('Token count:', vars.length);
            if (vars.length < 10) {
              console.error('Too few tokens extracted -- possible Figma API error');
              process.exit(1);
            }
            // Check for duplicate variable names
            const dupes = vars.filter((v, i) => vars.indexOf(v) !== i);
            if (dupes.length > 0) {
              console.error('Duplicate tokens:', dupes);
              process.exit(1);
            }
          "

Step 4: Store Figma Secrets

bash
# Add PAT as repository secret
gh secret set FIGMA_PAT --body "figd_your-token-here"

# Add file key as repository variable (not secret -- it's not sensitive)
gh variable set FIGMA_FILE_KEY --body "abc123XYZdefaultFileKey"
gh variable set FIGMA_ICON_FILE_KEY --body "def456IconFileKey"
gh variable set FIGMA_ICON_FRAME_ID --body "123:456"

Output

• Scheduled CI job syncing design tokens from Figma
• Asset export triggered by config changes
• Token validation preventing broken deployments
• PR-based workflow for reviewing design changes

Error Handling

| Issue | Cause | Solution | |-------|-------|----------| | 403 in CI | PAT expired | Rotate secret: gh secret set FIGMA_PAT | | Empty token output | File key wrong | Verify FIGMA_FILE_KEY variable | | Rate limited in CI | Concurrent workflows | Add concurrency group to workflow | | Stale cache | Node modules cached | Clear with actions/cache invalidation |

Examples

Trigger the Step 1 token-sync workflow manually and verify it opens a PR only when tokens changed:

bash
gh workflow run figma-token-sync.yml
gh run watch && gh pr list --label design-tokens

text
#142  chore(tokens): sync design tokens from Figma  design-tokens  open

The diff shows exactly what changed in the design file:

diff
- "color-brand-primary": "#4338ca",
+ "color-brand-primary": "#4f46e5",

No-change runs exit green without a PR (idempotent by design). Asset export on PR and the validation gate: references/asset-export-on-pr.md, references/design-system-validation.md.

Resources

• GitHub Actions Documentation
• GitHub Secrets
• Figma REST API

Next Steps

For deployment patterns, see figma-deploy-integration.