Overview

The Figma Sync command transforms Figma variables into design tokens that can be consumed by your application. It connects to the Figma Variables API, fetches your variable collections, and outputs them as JSON or TypeScript files.

Quick start

npx @uhg-abyss/cli figma sync

This launches an interactive wizard that guides you through:

1. Entering your Figma API key (stored securely for future use)
2. Selecting a Figma file
3. Choosing which collections to export
4. Specifying an output directory

Commands

figma sync

Sync Figma variables to design tokens.

npx @uhg-abyss/cli figma sync [options]

Options

Option	Description
--file-key <key>	Figma file key (or FIGMA_FILE_KEY env var)
--api-key <key>	Figma API key (or FIGMA_API_KEY env var)
--output <dir>	Output directory (default: ./tokens)
--format <type>	Output format: ts or json (default: json)
--collections <names>	Comma-separated collection names to export
--ci	Run in CI mode (no interactive prompts)

figma set-key

Store your Figma API key for future use.

npx @uhg-abyss/cli figma set-key [api-key]

If no key is provided, you'll be prompted to enter one interactively.

figma reset-key

Clear the stored Figma API key.

npx @uhg-abyss/cli figma reset-key

Getting your Figma API key

1. Go to Figma Account Settings
2. Scroll to Personal access tokens
3. Select the file_variables:read scope
4. Click Generate new token
5. Copy the token (starts with figd_)

Getting your file key

The file key is the unique identifier in your Figma file URL:

https://www.figma.com/design/[FILE_KEY]/Your-File-Name

For example, in https://www.figma.com/design/OIRuAL0M8vcdTpgofuYG9Y/Design-Tokens, the file key is OIRuAL0M8vcdTpgofuYG9Y.

Output formats

JSON (default)

{
  "colors": {
    "core.color.brand.100": "#002677",
    "semantic.color.text.primary": "$core.color.neutral.900"
  },
  "radii": {
    "semantic.border-radius.sm": 4
  }
}

TypeScript

export default {
  colors: {
    'core.color.brand.100': '#002677',
    'semantic.color.text.primary': '$core.color.neutral.900',
  },
  radii: {
    'semantic.border-radius.sm': 4,
  },
} as const;

Token categories

Variables are automatically categorized based on their names and types:

Category	Detected by
colors	Name contains "color" or type is COLOR
radii	Name contains "border-radius" or "radii"
borderWidths	Name contains "border-width"
sizes	Name contains "sizing"
space	Name contains "spacing"
opacities	Name contains "opacity"
fontSizes	Name contains "font-size"
fontWeights	Name contains "font-weight"
lineHeights	Name contains "line-height"

Extended collections

The CLI supports Figma's extended collections (brand overrides). When you select an extended collection, only the overridden values are exported, keeping your token files lean.

File naming:

• Base collection: brand-mobile.json
• Extended collection: surest__brand-mobile.json

Multiple modes

Collections with multiple modes (e.g., Light/Dark) generate separate files:

• brand-mobile_light.json
• brand-mobile_dark.json

CI/CD usage

For automated pipelines, use the --ci flag with environment variables:

FIGMA_API_KEY=${{ secrets.FIGMA_API_KEY }} \
FIGMA_FILE_KEY=${{ secrets.FIGMA_FILE_KEY }} \
npx --yes @uhg-abyss/cli figma sync --ci --output ./tokens

GitHub Actions example

name: Sync Figma Tokens

on:
  workflow_dispatch:
  schedule:
    - cron: '0 0 * * *'

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

      - uses: actions/setup-node@v4
        with:
          node-version: '18'

      - name: Sync Figma tokens
        env:
          FIGMA_API_KEY: ${{ secrets.FIGMA_API_KEY }}
          FIGMA_FILE_KEY: ${{ secrets.FIGMA_FILE_KEY }}
        run: npx --yes @uhg-abyss/cli figma sync --ci --output ./tokens

      - name: Create branch and push tokens
        run: |
          git config --local user.email "github-actions[bot]@users.noreply.github.com"
          git config --local user.name "github-actions[bot]"
          git add tokens/
          if git diff --staged --quiet; then
            echo "No changes to commit"
            exit 0
          fi
          BRANCH_NAME="figma-sync/$(date +%Y%m%d-%H%M%S)"
          git checkout -b "$BRANCH_NAME"
          git commit -m "chore: sync Figma tokens"
          git push origin "$BRANCH_NAME"
          echo "Created branch: $BRANCH_NAME"
          echo "Create a PR from this branch to merge the changes"

Remembered settings

The CLI remembers your preferences per Figma file:

• API key - Stored securely, used across all files
• File key history - Quick access to recently used files
• Output directory - Last used output path
• Collection selections - Per-file collection preferences

These settings persist between sessions, making repeated syncs faster.

Output file usage

Use create theme or extend theme to consume the output files

To use the theme files, you can use the createTheme or extendTheme tools.

Create theme example

import overrideTokens from './tokens/override-tokens.json';
import { createTheme, ThemeProvider } from '@uhg-abyss/mobile';

const theme = createTheme('uhc', {
  theme: overrideTokens,
});

const App = () => {
  return <ThemeProvider theme={theme}>...</ThemeProvider>;
};

Extend theme examples

Example 1: Extend theme from createTheme

import overrideTokens from './tokens/override-tokens.json';
import { createTheme, extendTheme, ThemeProvider } from '@uhg-abyss/mobile';

const baseTheme = createTheme('uhc');

const theme = extendTheme(baseTheme, { theme: overrideTokens });

const App = () => {
  return <ThemeProvider theme={theme}>...</ThemeProvider>;
};

Example 2: Extend theme from ThemeProvider

import overrideTokens from './tokens/override-tokens.json';
import { extendTheme, ThemeProvider } from '@uhg-abyss/mobile';

const App = () => {
  return (
    <ThemeProvider
      theme={(currentTheme) =>
        extendTheme(currentTheme, { theme: overrideTokens })
      }
    >
      ...
    </ThemeProvider>
  );
};