Design Token Automation

This repository manages the automated workflow for transforming Figma design tokens into platform-specific formats (CSS) for our design system.

Overview

This project automates the process of:

1. Receiving design tokens from Figma (via Tokens Studio for Figma)
2. Resolving token references and relationships
3. Transforming tokens into CSS variables
4. Publishing the processed tokens as an npm package

Installation

npm install @beydesign/tokens

Usage

// Import CSS variables in your project
import '@beydesign/tokens/build/css/variables.css';

Or in CSS:

@import '@beydesign/tokens/build/css/variables.css';

Workflow

graph LR
    A[Figma] -->|Tokens Studio Plugin| B[tokens.json]
    B -->|GitHub Action| C[resolve-tokens.js]
    C -->|Transform| D[resolved-tokens.json]
    D -->|Style Dictionary| E[CSS Variables]

1. Designers update tokens in Figma using Tokens Studio plugin
2. Tokens Studio pushes updates to tokens.json
3. GitHub Action automatically:
   • Resolves token references
   • Transforms tokens into CSS variables
   • Commits the generated files

Generated Files

• /tokens/resolved-tokens.json: Processed tokens with resolved references
• /build/css/variables.css: CSS custom properties ready for consumption

Development

Prerequisites

• Node.js 18 or higher
• npm

Setup

1. Clone the repository:

git clone [repository-url]
cd [repository-name]

2. Install dependencies:

npm install

Local Development

To transform tokens locally:

# Transform tokens and resolve references
node scripts/resolve-tokens.js

# Generate CSS variables
node build.js

GitHub Actions

The repository includes an automated workflow (.github/workflows/transform-tokens.yml) that:

• Triggers on pushes to the main branch
• Processes the tokens
• Commits the generated files back to the repository

Contributing

1. Ensure you have Tokens Studio for Figma set up with the correct GitHub integration
2. Make token changes in Figma
3. Push changes using Tokens Studio
4. The automation will handle the rest!

Architecture

• scripts/resolve-tokens.js: Resolves token references and relationships
• build.js: Transforms tokens into CSS using Style Dictionary
• GitHub Actions workflow: Orchestrates the automated process

Releases

The project automatically:

1. Versions the package (patch version for each token update)
2. Creates a GitHub release
3. Publishes to npm

Each release contains:

• Updated design tokens from Figma
• Generated CSS variables
• Full token reference documentation

NPM Package Structure

@beydesign/tokens/
├── build/
│   └── css/
│       └── variables.css    # Generated CSS variables
└── tokens/
    └── resolved-tokens.json # Processed design tokens