---

name: figma-ci-integration description: 'Automate Figma design token sync and asset export in CI/CD pipelines.

Use when setting up GitHub Actions for Figma, automating icon exports,

or validating design token changes in pull requests.

Trigger with phrases like "figma CI", "figma GitHub Actions",

"automate figma export", "figma CI pipeline".

' allowed-tools: Read, Write, Edit, Bash(gh:*) version: 1.6.0 license: MIT author: Jeremy Longshore jeremy@intentsolutions.io tags:

• saas
• figma compatibility: Designed for Claude Code

---

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

# .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

# .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

      - 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

# 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:

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

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

The diff shows exactly what changed in the design file:

- "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.