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
name: Sync Figma Design Tokens
on:
schedule:
- cron: '0 9 * * 1-5'
workflow_dispatch:
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
name: Export Figma Assets
on:
pull_request:
paths:
- 'figma-config.json'
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
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
gh secret set FIGMA_PAT --body "figd_your-token-here"
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
Next Steps
For deployment patterns, see figma-deploy-integration.
