Figma Integration

Sync Canon design tokens between code and Figma using Tokens Studio. The CSS tokens are the source of truth; Figma receives generated exports.

Architecture

Design tokens flow from code to Figma, ensuring consistency across engineering and design.

tokens.css Source of Truth
pnpm tokens:export Generate exports
tokens.figma.json Tokens Studio format
Figma Variables Via Tokens Studio

Quick Start

Get Canon tokens into Figma in three steps.

1

Install Tokens Studio

  1. Open Figma
  2. Go to Plugins > Browse plugins in Community
  3. Search for "Tokens Studio"
  4. Click Install
2

Import Canon Tokens

  1. Open Tokens Studio plugin
  2. Click Settings (gear icon)
  3. Under "Token Storage", select Local document
  4. Click Import > From file
  5. Select packages/components/src/lib/styles/tokens.figma.json
3

Apply to Figma

  1. In Tokens Studio, select the "core" token set
  2. Click Sync styles for typography and shadows
  3. Click Sync variables for colors and spacing

Token Sets

Canon tokens are organized into sets for different themes and use cases.

Set Description Use Case
core Default dark theme tokens Base design work
themes/light Light theme overrides Light mode designs
themes/high-contrast High contrast overrides Accessibility designs

Applying Themes

Theme sets override core values for the same token paths. Enable multiple sets to compose themes.

core

Always enabled. Provides base dark theme.

themes/light

Enable for light mode. Overrides color tokens.

themes/high-contrast

Enable for accessibility. Increases contrast ratios.

Sync Workflow

Keep tokens synchronized between code and Figma.

Code to Figma (Most Common)

When CSS tokens change, regenerate the Figma export and re-import.

# 1. Regenerate Figma tokens
pnpm --filter=components tokens:export

# 2. Commit updated token files
git add packages/components/src/lib/styles/tokens.figma.json
git commit -m "chore(tokens): sync design tokens"

# 3. In Figma, re-import tokens.figma.json via Tokens Studio

Figma to Code (Design Exploration)

When exploring new tokens in Figma, the process is manual to maintain source of truth.

1

Export tokens from Tokens Studio as JSON

2

Review changes with designer

3

Manually update tokens.css (source of truth)

4

Run pnpm tokens:export to regenerate all formats

Important: tokens.css is always the source of truth. Figma exports are for reference only. Never edit generated files directly.

Token Type Mapping

CSS token prefixes map to specific Tokens Studio types.

CSS Token Prefix Tokens Studio Type
color-* color
text-* fontSizes
font-sans/mono/serif fontFamilies
font-light/regular/... fontWeights
leading-* lineHeights
tracking-* letterSpacing
space-* spacing
radius-* borderRadius
shadow-* boxShadow
duration-* duration

Figma Variables vs Styles

Tokens Studio can create both Figma Variables and Figma Styles. Use the right one for each token type.

Variables

Recommended for colors, spacing

  • Support mode switching (dark/light)
  • Can be used in Auto Layout
  • Native Figma feature
  • Best for: color-*, space-*, radius-*

Styles

Required for shadows, typography

  • Support complex composite values
  • Required for multi-layer shadows
  • Better for typography presets
  • Best for: shadow-*, text-*

Use Sync variables for primitive values and Sync styles for composite values.

File Structure

Token files are organized in the components package.

packages/components/
├── figma/
│   ├── README.md                    # Figma integration docs
│   └── tokens-studio.config.json    # Tokens Studio configuration
├── scripts/
│   └── generate-exports.mjs         # Token export generator
└── src/lib/styles/
    ├── tokens.css                   # Source of truth
    ├── tokens.figma.json            # Tokens Studio format
    ├── tokens.dtcg.json             # W3C DTCG format
    ├── tokens.scss                  # SCSS variables
    └── canon.json                   # Categorized format

Remote Sync (Team Collaboration)

For team collaboration, configure remote storage to sync tokens automatically.

GitHub Sync

Tokens Studio can sync directly with the GitHub repository.

  1. In Tokens Studio settings, select GitHub storage
  2. Enter repository: createsomethingtoday/create-something-monorepo
  3. File path: packages/components/src/lib/styles/tokens.figma.json
  4. Branch: main
  5. Generate a GitHub personal access token with repo scope

Troubleshooting

Common issues and their solutions.

Tokens not appearing in Figma

  1. Ensure correct token set is enabled
  2. Click Refresh in Tokens Studio
  3. Try re-importing the JSON file

Colors look wrong

  1. Check if rgba values are supported
  2. Verify the correct theme set is applied
  3. Check for token reference errors

Typography not applying

  1. Ensure the font is installed in Figma
  2. Check font family name matches exactly
  3. Use Sync styles for typography

Shadows missing

  1. Shadows require Sync styles, not variables
  2. Multi-layer shadows may need manual adjustment
  3. Check rgba opacity values

Philosophy

Single Source of Truth

tokens.css defines all values. All other formats (Figma, SCSS, DTCG) are generated outputs. Never edit generated files directly.

Weniger, aber besser

Only tokens that earn their existence. No decorative variations, no unused semantic tokens.

Tool Transparency

The sync process should recede into use. Designers see tokens; engineers see CSS variables. The bridge is invisible.