@joaodotwork/figma-tokens-pyramid

Extract, transform, and build design tokens from Figma Variables API

Transform Figma variables into production-ready design tokens for web, React Native, and other platforms. Includes automated developer package generation.

Features

• 🎨 Extract from Figma - Pull variables directly from Figma's Variables API
• 🔄 Transform tokens - Convert to Style Dictionary format and other standards
• 🏗️ Build for platforms - Generate CSS, SCSS, JavaScript, and React Native outputs
• 📦 Developer packages - Auto-generate distributable token packages
• ⚙️ Configurable - Customize collections, modes, and output formats
• 🧪 Validated - Built-in token validation and health checks

Installation

npm install @joaodotwork/figma-tokens-pyramid

Or install globally for CLI usage:

npm install -g @joaodotwork/figma-tokens-pyramid

Install from GitHub Packages

The package is also available on GitHub Packages:

# Configure npm to use GitHub Packages for @joaodotwork scope
echo "@joaodotwork:registry=https://npm.pkg.github.com" >> .npmrc

# Install the package
npm install @joaodotwork/figma-tokens-pyramid

Quick Start

1. Initialize Configuration

figma-tokens init

This creates a figma-tokens.config.js file.

2. Configure Your Figma File

Edit figma-tokens.config.js:

export default {
  figma: {
    fileKey: process.env.FIGMA_FILE_KEY,
    accessToken: process.env.FIGMA_ACCESS_TOKEN,
    collections: {
      reference: 'VariableCollectionId:xxx:xxx',
      system: 'VariableCollectionId:xxx:xxx',
      component: 'VariableCollectionId:xxx:xxx'
    },
    modes: {
      reference: 'modeId:xxx',
      system: 'modeId:xxx',
      component: 'modeId:xxx'
    }
  },
  output: {
    directory: './tokens',
    formats: ['json', 'js', 'css', 'scss']
  },
  platforms: ['web', 'react-native']
}

3. Extract and Build Tokens

# Extract from Figma, transform, and build all outputs
figma-tokens sync

# Or run steps individually
figma-tokens extract
figma-tokens transform
figma-tokens build --platform web

CLI Commands

figma-tokens init

Initialize configuration file

figma-tokens init

figma-tokens extract

Extract tokens from Figma

figma-tokens extract [options]

Options:
  -c, --config <path>   Path to config file (default: figma-tokens.config.js)
  -o, --output <path>   Output directory

figma-tokens transform

Transform tokens to Style Dictionary format

figma-tokens transform [options]

Options:
  -c, --config <path>   Path to config file
  -i, --input <path>    Input tokens file
  -o, --output <path>   Output directory

figma-tokens build

Build platform-specific outputs (coming soon)

figma-tokens build [options]

Options:
  -p, --platform <platform>  Platform to build (web, react-native)
  -o, --output <path>        Output directory

figma-tokens sync

Run extract + transform in one command

figma-tokens sync [options]

Options:
  -c, --config <path>    Path to config file
  --create-package       Also create developer package

figma-tokens create-package ⭐

Create distributable developer package

figma-tokens create-package [options]

Options:
  -c, --config <path>   Path to config file
  -v, --version <ver>   Package version
  --no-zip              Skip creating archive

Example output:

✔ Configuration loaded
✔ Tokens loaded
✔ Developer package created

✓ Developer package created successfully!

Package Details:
  Path: developer-packages/20251205-optimized/developer-package
  Archive: developer-packages/20251205-optimized/20251205-design-tokens-package.zip

Token Statistics:
  reference: 120 tokens
  system: 162 tokens
  component: 199 tokens
  Total: 481 tokens

figma-tokens validate

Validate token structure and references (coming soon)

Programmatic API

import { FigmaTokenExtractor } from '@joaodotwork/figma-tokens-pyramid';

const extractor = new FigmaTokenExtractor({
  figmaToken: process.env.FIGMA_ACCESS_TOKEN,
  fileKey: 'your-file-key',
  collections: {
    reference: 'VariableCollectionId:xxx:xxx',
    system: 'VariableCollectionId:xxx:xxx'
  }
});

// Extract tokens
const tokens = await extractor.extract();

// Transform tokens
const transformed = await extractor.transform(tokens);

// Build for web
await extractor.build(transformed, { platform: 'web' });

// Create developer package
await extractor.createDeveloperPackage(transformed);

Configuration

See the Configuration Guide for detailed configuration options.

Developer Package Configuration

export default {
  // ... other config ...

  developerPackage: {
    enabled: true,
    output: './developer-packages',
    packageName: 'design-tokens-hb25-optimized',
    version: '1.0.0',
    autoVersion: {
      strategy: 'datestamp' // 'datestamp' | 'semver' | 'git-tag'
    },
    archive: {
      enabled: true,
      format: 'zip'
    }
  }
}

Examples

Basic Workflow

# 1. Initialize
figma-tokens init

# 2. Configure (edit figma-tokens.config.js)
# Add your Figma file key, access token, collection IDs, and mode IDs

# 3. Extract and transform
figma-tokens sync

# Output:
# ✔ Tokens extracted from Figma
# ✔ Tokens transformed
# Files written:
#   ./tokens/index.json
#   ./style-dictionary/tokens.json

Create Developer Package

# Enable in config first
# developerPackage.enabled = true

figma-tokens create-package

# Creates:
# - developer-packages/YYYYMMDD-optimized/developer-package/
# - Auto-generated package.json
# - Auto-generated README.md
# - .zip archive ready for distribution

Full Workflow with Package

figma-tokens sync --create-package

# Runs:
# 1. Extract from Figma
# 2. Transform to Style Dictionary
# 3. Create developer package

See the examples directory for more:

• Basic usage
• Custom configuration
• Programmatic API usage

Development

# Clone the repository
git clone https://github.com/joaodotwork/figma-tokens-pyramid.git
cd figma-tokens-pyramid

# Install dependencies
npm install

# Run tests
npm test

# Watch mode for development
npm run dev

Contributing

Contributions are welcome! Please read our Contributing Guide.

License

MIT © joaodotwork

Related

• Figma Variables API Documentation
• Style Dictionary

Support

• Documentation
• Issues
• Discussions