Figma + Tokens Studio Setup Guide

For CloudAlt Monorepo Design Token Workflow
Last Updated: 2025-10-10

Overview

This guide walks you through setting up Figma with the Tokens Studio plugin to manage design tokens that will be consumed by your monorepo’s packages/theme system.

Goal: Define tokens in Figma → Export JSON → Import to packages/theme/tokens/ → Build → Propagate to all 30+ apps

Prerequisites

Figma Account (Free or paid)
Figma Desktop App or browser access
A Figma file for your design system (create new or use existing)

About Costs

Tokens Studio Plugin:

✅ FREE for core features (create, edit, export tokens)
✅ FREE for local storage and manual JSON export
Pro version ($8-12/month): Only needed for advanced features like:
- GitHub/GitLab auto-sync
- Multi-file token libraries
- Token aliases across multiple sets
- Team collaboration features

For this project: You only need the FREE version. We’ll export tokens manually (Steps 7-8), so no subscription required.

Figma Dev Mode (the popup you saw):

✅ FREE on Figma Free plan (basic features)
Paid on Professional/Organization plans
Not required for Tokens Studio - separate feature for design handoff

Step 1: Install Tokens Studio Plugin

For macOS Figma Desktop App

Method 1: Via Browser (Easiest)

Open this link in your web browser (Safari/Chrome): https://www.figma.com/community/plugin/843461159747178978/Tokens-Studio-for-Figma
Log into Figma if prompted
Click “Try it out” or “Install”
If you see “Welcome to Dev Mode” popup:
- This is Figma’s separate developer features (not Tokens Studio)
- For Dev Mode settings, choose:
  - Platform: iOS (since you’re on macOS and building React Native apps)
  - Unit: pt (points - standard for iOS/mobile)
- Click “Next, Theme” → Select whatever, doesn’t matter for tokens
- Click through to finish Dev Mode setup
- ✅ Now the plugin will install
It will open in your Figma desktop app
✅ Plugin is now installed

About Dev Mode (the popup you saw):

This is Figma’s built-in developer handoff tool (separate from Tokens Studio)
It shows CSS/iOS/Android code for designs
Not required for Tokens Studio - you can skip/dismiss it
If it asks for settings, choose iOS/pt to match your mobile apps

Method 2: From Inside Figma (Alternative)

Open any Figma file (or create a new one)
Click in the canvas area (to ensure a file is active)
Go to Menu Bar → Plugins → Find more plugins
- OR use keyboard shortcut: ⌘ / (Command + Slash) → type “plugins”
Search for “Tokens Studio”
Click “Install” on the Tokens Studio plugin card
✅ Plugin installed

Why your search failed:

Plugins menu only appears when you have an active file open (not from the home screen)
The Help menu search doesn’t index plugins—you need the Plugins menu or Community search

Step 2: Open Tokens Studio in Your Figma File

On macOS:

Method 1: Quick Command (Fastest)

Open your Figma design file (or create a new one: File → New Design File)
Press ⌘ / (Command + Slash)
Type: tokens studio
Hit Enter
✅ Plugin panel opens on the right side

Method 2: Menu Bar

Open your Figma design file
Menu Bar → Plugins → Tokens Studio for Figma
✅ Plugin panel opens

Method 3: Right-Click

Right-click anywhere on canvas
Plugins → Tokens Studio for Figma
✅ Plugin panel opens

First Time Setup:

Plugin will prompt you to choose storage location
Select “Local” for now (we’ll export manually)
Later you can sync to GitHub directly (optional in Step 10)

Step 3: Understand Token Organization

Tokens Studio organizes tokens into Sets (like folders). Match your monorepo structure:

📁 Core Tokens (shared across all brands)
  ├── colors
  ├── spacing
  ├── typography
  ├── borderRadius
  ├── shadows
  └── motion

📁 Semantic Tokens (light/dark modes)
  ├── light
  └── dark

📁 Brand Tokens (per-brand overrides)
  ├── pinkGuest
  ├── orangeGuest
  └── purpleGuest

Step 4: Create Token Sets

4.1 Create Core Color Tokens

In Tokens Studio panel, click ”+ Add set”
Name it: core-colors
Click on core-colors to open it
Click ”+ Add token” → Select “Color”

Define your base palette:

Token Name             | Value
-----------------------|----------
pink.50                | #FFF5F9
pink.100               | #FFE6F1
pink.200               | #FFCDE3
pink.300               | #FFB3D6
pink.400               | #FF8AC4
pink.500               | #F90772   ← Primary pink
pink.600               | #E5066A
pink.700               | #CC0560
pink.800               | #B30456
pink.900               | #99034C

orange.50              | #FFF7ED
orange.100             | #FFEDD5
orange.200             | #FED7AA
orange.300             | #FDBA74
orange.400             | #FB923C
orange.500             | #FF8C00   ← Primary orange
orange.600             | #EA7C00
orange.700             | #C66900
orange.800             | #A35700
orange.900             | #7C4300

(Continue with purple, gray, etc.)

How to add each token:

Click ”+ Add token”
Name: pink.500 (use dot notation)
Type: Color
Value: #F90772 (hex code)
Click Create

4.2 Create Spacing Tokens

Add new set: core-spacing
Add tokens with type “Sizing”

Token Name    | Value
--------------|-------
spacing.0     | 0
spacing.1     | 4px
spacing.2     | 8px
spacing.3     | 12px
spacing.4     | 16px
spacing.5     | 20px
spacing.6     | 24px
spacing.8     | 32px
spacing.10    | 40px
spacing.12    | 48px
spacing.16    | 64px
spacing.20    | 80px
spacing.24    | 96px

4.3 Create Typography Tokens

Add new set: core-typography
Add tokens with type “Font Size”, “Font Weight”, “Line Height”

Font Families:

Token Name                  | Value
----------------------------|------------------
fontFamily.sans             | Inter, sans-serif
fontFamily.mono             | 'Courier New', monospace

Font Sizes:

fontSize.xs                 | 12px
fontSize.sm                 | 14px
fontSize.base               | 16px
fontSize.lg                 | 18px
fontSize.xl                 | 20px
fontSize.2xl                | 24px
fontSize.3xl                | 30px
fontSize.4xl                | 36px

Font Weights:

fontWeight.light            | 300
fontWeight.normal           | 400
fontWeight.medium           | 500
fontWeight.semibold         | 600
fontWeight.bold             | 700

Line Heights:

lineHeight.tight            | 1.25
lineHeight.normal           | 1.5
lineHeight.relaxed          | 1.75

4.4 Create Border Radius Tokens

Add new set: core-radius
Type: “Border Radius”

Token Name       | Value
-----------------|-------
radius.none      | 0
radius.sm        | 4px
radius.md        | 8px
radius.lg        | 12px
radius.xl        | 16px
radius.2xl       | 24px
radius.full      | 9999px

4.5 Create Shadow Tokens

Add new set: core-shadows
Type: “Box Shadow”

Token Name       | Value
-----------------|---------------------------------------
shadow.sm        | 0 1px 2px 0 rgba(0, 0, 0, 0.05)
shadow.md        | 0 4px 6px -1px rgba(0, 0, 0, 0.1)
shadow.lg        | 0 10px 15px -3px rgba(0, 0, 0, 0.1)
shadow.xl        | 0 20px 25px -5px rgba(0, 0, 0, 0.1)
shadow.2xl       | 0 25px 50px -12px rgba(0, 0, 0, 0.25)

Step 5: Create Semantic Tokens (Reference Core Tokens)

Semantic tokens reference core tokens using aliases.

5.1 Create Semantic Light Mode

Add new set: semantic-light
Click ”+ Add token” → Type: “Color”

Use references with {} syntax:

Token Name              | Value (Reference)
------------------------|------------------
color.primary           | {pink.500}
color.secondary         | {pink.300}
color.accent            | {pink.700}
color.success           | {green.500}
color.error             | {red.500}
color.warning           | {orange.400}

color.background        | {gray.50}
color.surface-1         | #FFFFFF
color.surface-2         | {gray.100}
color.surface-3         | {gray.200}

color.text-primary      | {gray.900}
color.text-secondary    | {gray.600}
color.text-tertiary     | {gray.400}
color.text-on-primary   | #FFFFFF

How to add a reference:

Add token, name: color.primary
In value field, type: {pink.500}
Tokens Studio will auto-complete from existing tokens
✅ Token now references pink.500 instead of hardcoding

5.2 Create Semantic Dark Mode (Optional for Sprint 2)

Add new set: semantic-dark
Override values for dark mode:

Token Name              | Value (Reference)
------------------------|------------------
color.background        | {gray.900}
color.surface-1         | {gray.800}
color.surface-2         | {gray.700}
color.text-primary      | {gray.50}
color.text-secondary    | {gray.300}

Step 6: Create Brand-Specific Tokens

Brand tokens override semantic tokens for each brand.

6.1 Create pinkGuest Brand

Add new set: brand-pinkGuest
Add overrides:

Token Name              | Value (Reference)
------------------------|------------------
color.primary           | {pink.500}        ← #F90772
color.secondary         | {pink.300}
color.accent            | {pink.700}

6.2 Create orangeGuest Brand

Add new set: brand-orangeGuest
Add overrides:

Token Name              | Value (Reference)
------------------------|------------------
color.primary           | {orange.500}      ← #FF8C00
color.secondary         | {orange.300}
color.accent            | {orange.700}

6.3 Create purpleGuest Brand

Add new set: brand-purpleGuest
Add overrides:

Token Name              | Value (Reference)
------------------------|------------------
color.primary           | {purple.500}      ← #8B42FF
color.secondary         | {purple.300}
color.accent            | {purple.700}

Step 7: Export Tokens to JSON

Manual Export (For Now)

In Tokens Studio panel, click “Export” button (bottom)
Select all token sets you want to export
Click “Export JSON”
Save file to your computer (e.g., design-tokens.json)

Output structure:

{
  "core-colors": {
    "pink": {
      "500": {
        "value": "#F90772",
        "type": "color"
      }
    }
  },
  "semantic-light": {
    "color": {
      "primary": {
        "value": "{pink.500}",
        "type": "color"
      }
    }
  },
  "brand-pinkGuest": {
    "color": {
      "primary": {
        "value": "{pink.500}",
        "type": "color"
      }
    }
  }
}

Step 8: Import to Monorepo

Option A: Paste the JSON content in chat
Option B: Commit to a branch and share the file path
Option C: Upload the file

8.2 I’ll Convert to Style Dictionary Format

I’ll transform your Tokens Studio export into the monorepo structure:

packages/theme/tokens/
├── core/
│   ├── colors.json
│   ├── spacing.json
│   ├── typography.json
│   ├── radius.json
│   └── shadows.json
├── semantic/
│   ├── light.json
│   └── dark.json
└── brands/
    ├── pinkGuest.json
    ├── orangeGuest.json
    └── purpleGuest.json

8.3 Build & Verify

cd packages/theme
yarn build:tokens

# Outputs generated:
# dist/web/tokens.css
# dist/native/tokens.json
# dist/ts/tokens.ts

Step 9: Apply Tokens in Figma Designs

Now that tokens are defined, use them in your designs:

Select any element (rectangle, text, etc.)
Instead of picking a color manually, click the ”🎨” icon in Tokens Studio
Select a token (e.g., color.primary)
✅ Element now uses the token value

Benefits:

Change {pink.500} once → all elements using it update
Export designs with token references, not hardcoded values

Step 10: Sync to GitHub (Optional - Advanced)

For automatic sync instead of manual export:

In Tokens Studio, click Settings (gear icon)
Select “Sync providers” → “GitHub”
Authenticate with GitHub
Select your repository: xavierdurant/cloudalt
Choose branch: feat/design-tokens (or main)
Set path: packages/theme/tokens/figma-export/
Click “Save”

Now when you edit tokens:

Click “Push to GitHub”
Tokens Studio commits JSON directly to your repo
✅ Automatic sync, no manual export needed

Note: Requires repo write access and careful branch management.

Best Practices

✅ DO:

Use references ({pink.500}) in semantic/brand tokens, not hardcoded values
Organize tokens in sets that match your monorepo structure
Start with ONE brand (pinkGuest), validate, then add others
Document token usage in descriptions (Tokens Studio supports this)
Version your token exports (commit to git with meaningful messages)

❌ DON’T:

Don’t hardcode colors in brand tokens (use references)
Don’t duplicate tokens across sets (centralize in core)
Don’t skip semantic layer (core → semantic → brand hierarchy is important)
Don’t export incomplete token sets to production

Troubleshooting

Issue: Can’t find Tokens Studio plugin

Solution: Make sure you’re using Figma Desktop app or latest browser version. Try direct link: https://www.figma.com/community/plugin/843461159747178978

Issue: References not resolving

Solution: Check token name syntax. Must match exactly, including dots: {pink.500} not {pink-500}

Issue: Export JSON is empty

Solution: Make sure token sets are not empty and at least one set is selected before export

Issue: Colors look different after import

Solution: Verify hex codes match. Check if alpha/opacity is included (e.g., #F9077280 = 50% opacity)

Quick Reference: Token Naming Conventions

Category	Pattern	Example
Core Colors	`{color}.{scale}`	`pink.500`, `gray.900`
Semantic	`color.{role}`	`color.primary`, `color.text-primary`
Spacing	`spacing.{size}`	`spacing.4` (16px)
Typography	`fontSize.{scale}`	`fontSize.xl`
Radius	`radius.{size}`	`radius.md`
Shadows	`shadow.{size}`	`shadow.lg`

Next Steps

Complete this setup in Figma
Export your first token set (start with pinkGuest)
Share JSON with me → I’ll convert to monorepo format
Build tokens → Verify outputs work
Apply to ONE app → Test end-to-end
Scale to remaining brands

Resources

Tokens Studio Docs: https://docs.tokens.studio/
Style Dictionary Docs: https://amzn.github.io/style-dictionary/
Design Tokens W3C Spec: https://design-tokens.github.io/community-group/format/

Questions? Drop them in chat and I’ll help troubleshoot or clarify any step.