Synkio

Sync Figma variables to code. No Enterprise plan required.

Synkio is a developer-friendly CLI that bridges the gap between Figma design variables and your codebase. It bypasses the need for Figma's Enterprise REST API by utilizing the Plugin API, giving you a powerful sync workflow on any Figma plan.

Requirements

• Node.js: v18 or later
• Figma Plugin: Synkio Sync (optional - see Plugin-free Import)

Why Synkio?

Most token sync tools require expensive Figma Enterprise licenses to access variables via the REST API. Synkio takes a smarter approach:

• 🔓 No Enterprise Needed — Works with Free, Professional, and Organization plans
• 🛡️ Breaking Change Protection — Intelligent diffing based on permanent Variable IDs prevents accidental production breaks
• ⚡ Developer Experience — A simple CLI workflow that lives in your terminal, not a 3rd party dashboard
• 📦 Standard Output — Generates W3C DTCG-compliant tokens ready for Style Dictionary or direct use

Quick Start

1. Install

npm install synkio --save-dev

2. Initialize

npx synkio init

This creates:

• synkio.config.json - Configuration file with your Figma file ID
• .env - Contains your FIGMA_TOKEN (must be in project root)

The .env file is automatically added to your .gitignore to keep your token secure.

Important: The CLI loads .env from your current working directory (where you run the command). Do not place it in subdirectories like synkio/.

3. Install Style Dictionary (Optional)

If you're using Style Dictionary output mode (output.mode: "style-dictionary"), install it as a peer dependency:

npm install -D style-dictionary

For simple projects using JSON or CSS output, this is not required.

4. Prepare Figma File

1. Open your Figma file
2. Install and run the Synkio Sync plugin
3. Click "Prepare for Sync"

This snapshots your variables so the CLI can access them.

5. Pull and Build

npx synkio pull   # Fetch from Figma, update baseline
npx synkio build  # Generate token files

Your tokens are now in your project!

Commands

| Command | Description | |---------|-------------| | synkio --version | Show CLI version | | synkio init | Initialize project with Figma credentials | | synkio pull | Fetch tokens from Figma, update baseline | | synkio pull --preview | Preview changes without updating baseline | | synkio pull --watch | Poll for changes automatically | | synkio pull --collection=<name> | Pull specific collection(s) | | synkio build | Generate token files from baseline | | synkio build --force | Apply changes despite breaking change warnings | | synkio build --rebuild | Regenerate all files from existing baseline | | synkio rollback | Revert to previous sync | | synkio rollback --preview | Preview rollback changes | | synkio validate | Check config and connection | | synkio docs | Generate documentation site | | synkio docs --open | Generate and open in browser | | synkio import <path> | Import from Figma native JSON export |

See the User Guide for all options and configuration.

Smart Safety Checks

Synkio acts as a gatekeeper for your design system. Unlike simple exporters, it understands the difference between a rename and a deletion:

• Renames — If a designer changes Brand Blue to Primary Blue, Synkio sees the ID match and reports it as a rename, not a deletion
• Deletions — Blocks sync if a variable used in your code has been deleted in Figma
• Mode Changes — Detects if a theme mode (e.g., "Dark Mode") was added or removed

Use npx synkio pull --preview to see a full report of changes without updating baseline.

Configuration

Synkio is configured via synkio.config.json:

{
  "version": "1.0.0",
  "figma": {
    "fileId": "your-file-id",
    "accessToken": "${FIGMA_TOKEN}"
  },
  "output": {
    "dir": "tokens"
  },
  "css": {
    "enabled": true,
    "utilities": true,
    "transforms": { "useRem": true }
  },
  "docs": {
    "enabled": true
  }
}

Output Modes

Synkio supports three output modes:

| Mode | Description | |------|-------------| | JSON (default) | W3C DTCG-compliant token files | | CSS | Zero-dependency CSS custom properties | | Style Dictionary | Full platform support (SCSS, JS, TS, iOS, Android, etc.) |

For simple projects, use css.enabled: true. For advanced needs, enable Style Dictionary mode:

{
  "output": {
    "mode": "style-dictionary",
    "styleDictionary": {
      "configFile": "./sd.config.js"
    }
  }
}

Then install Style Dictionary as a peer dependency:

npm install style-dictionary --save-dev

Per-Collection Configuration

You can configure each collection individually with custom output directories and mode splitting:

{
  "output": {
    "dir": "tokens"
  },
  "collections": {
    "colors": {
      "dir": "src/styles/tokens/colors",
      "splitModes": false
    },
    "primitives": {
      "dir": "src/styles/tokens/primitives",
      "splitModes": false
    },
    "typography": {
      "dir": "src/styles/tokens/typography",
      "splitModes": true
    }
  }
}

| Option | Type | Default | Description | |--------|------|---------|-------------| | dir | string | output.dir | Output directory for this collection | | splitModes | boolean | true | Split modes into separate files (colors.light.json, colors.dark.json) | | includeMode | boolean | true | Include mode as first-level key in output |

Use synkio build --rebuild to regenerate files after changing collection config.

See the User Guide for full configuration options.

Plugin-free Import

Synkio can import tokens directly from Figma's native JSON export — no plugin required.

How It Works

1. In Figma, select your variable collection
2. Export via File → Export → Variables → JSON
3. Import into Synkio:

npx synkio import ./figma-exports/ --collection=theme

This preserves Figma's variableId for full breaking change protection, just like the plugin workflow.

When to Use Import vs Sync

| Workflow | Use Case | |----------|----------| | synkio pull + synkio build | Automated CI/CD, real-time sync with Figma | | synkio import | Manual handoff, offline workflows, no plugin needed |

Both workflows support the same breaking change detection and output generation.

See the User Guide for detailed import options.

Documentation

• User Guide — Complete reference for all commands and options
• Hosting Guide — Deploy your design tokens docs to GitHub Pages, Netlify, Vercel, and more

License

MIT © rgehrkedk