Design Tokens - Figma Integration

This guide describes the comprehensive design tokens extracted from Figma and available in multiple formats for seamless integration with your components and styles.

Overview

Design tokens extracted from Figma are available in multiple formats to support different use cases:

SCSS

CSS custom properties + utility classes

File: src/styles/_design-tokens-figma.scss

TypeScript

Type-safe token definitions

File: src/styles/tokens/tokens.ts

JSON

W3C DTCG standard format

File: src/styles/tokens/tokens.json

CSS

Raw CSS custom properties

File: src/styles/tokens/tokens.css

Token Summary

Total Tokens: 35+

• Colors: 18 tokens (primary, secondary palette, greys, blacks, semantic)
• Spacing: 5 tokens (4px, 8px, 16px, 24px, 28px)
• Typography: 4 composite styles (body small, label, input, text 12)
• Font Families: 2 (Inter, Poppins)
• Font Weights: 1 (Regular 400)

---

Colors

Primary Colors

Token	Value	Description
--figma-color-primary-brand	#044076	Primary brand color

Secondary Colors

Token	Value	Description
--figma-color-secondary-indigo	#9f9ff8	Secondary indigo
--figma-color-secondary-mint	#96e2d6	Secondary mint
--figma-color-secondary-blue	#92bfff	Secondary blue
--figma-color-secondary-cyan	#aec7ed	Secondary cyan
--figma-color-secondary-green	#94e9b8	Secondary green
--figma-color-secondary-sky-blue	#56CCF2	Secondary sky blue

Grey Scale

Token	Value	Description
--figma-color-grey-white	#FFFFFF	Grey white (100%)
--figma-color-grey-50	#D0D1D2	Grey 50
--figma-color-grey-40	#A2A3A5	Grey 40
--figma-color-grey-2	#909090	Grey 2

Black Variations

Token	Value	Description
--figma-color-black-100	#000000	Black 80% opacity
--figma-color-black-40	#00000066	Black 40% opacity
--figma-color-black-light	#11263C	Light black
--figma-color-black-font	#303030	Black font color

White

Token	Value	Description
--figma-color-white-100	#FFFFFF	White 100%

Semantic Colors

Token	Value	Description
--figma-color-error	#EB5757	Error red color

---

Spacing

Based on a 4px grid system:

Token	Value	Multiplier	Description
--figma-spacing-1	4px	1×	Base unit
--figma-spacing-2	8px	2×	Small spacing
--figma-spacing-4	16px	4×	Medium spacing
--figma-spacing-6	24px	6×	Large spacing
--figma-spacing-7	28px	7×	Extra large spacing

---

Typography

Font Families

Token	Value	Description
--figma-font-family-inter	Inter, system-ui, -apple-system, sans-serif	Inter with fallbacks
--figma-font-family-poppins	Poppins, system-ui, -apple-system, sans-serif	Poppins with fallbacks

Font Weights

Token	Value	Description
--figma-font-weight-regular	400	Regular weight

Letter Spacing

Token	Value	Description
--figma-letter-spacing-normal	0	Normal spacing

Typography Styles

Each typography style is expanded into individual properties for easier CSS usage:

Body Small (12px, Poppins)

• --figma-typography-body-small-font-family
• --figma-typography-body-small-font-size (12px)
• --figma-typography-body-small-font-weight (400)
• --figma-typography-body-small-line-height (20px)

Body Label (8px, Poppins)

• --figma-typography-body-label-font-family
• --figma-typography-body-label-font-size (8px)
• --figma-typography-body-label-font-weight (400)
• --figma-typography-body-label-line-height (12px)

Body Input (14px, Poppins)

• --figma-typography-body-input-font-family
• --figma-typography-body-input-font-size (14px)
• --figma-typography-body-input-font-weight (400)
• --figma-typography-body-input-line-height (22px)

Text 12 Regular (12px, Inter)

• --figma-typography-text-12-regular-font-family
• --figma-typography-text-12-regular-font-size (12px)
• --figma-typography-text-12-regular-font-weight (400)
• --figma-typography-text-12-regular-line-height (16px)

---

Usage

SCSS

@use "../styles/design-tokens-figma";

.my-component {
  background-color: var(--figma-color-secondary-mint);
  padding: var(--figma-spacing-6);
  color: var(--figma-color-black-font);
}

TypeScript

import { tokens } from '#styles/tokens/tokens'

const MyComponent = () => {
  return (
    <div style={{
      backgroundColor: tokens.color.secondary.mint,
      padding: tokens.spacing['6']
    }}>
      Content
    </div>
  )
}

Astro

---
import '#styles/design-tokens-figma.scss'
---

<div class="card">
  <h2 class="figma-body-input">Card Title</h2>
  <p class="figma-body-small">Card content</p>
</div>

<style>
  .card {
    background-color: var(--figma-color-white-100);
    border: 1px solid var(--figma-color-grey-50);
    padding: var(--figma-spacing-6);
    border-radius: 8px;
  }
</style>

Typography with Individual Properties

.my-text {
  font-family: var(--figma-typography-body-small-font-family);
  font-size: var(--figma-typography-body-small-font-size);
  font-weight: var(--figma-typography-body-small-font-weight);
  line-height: var(--figma-typography-body-small-line-height);
}

Typography with Utility Classes

The SCSS file includes pre-built utility classes:

<p class="figma-body-small">Small body text</p>
<label class="figma-body-label">Label text</label>
<input class="figma-body-input" type="text" />
<span class="figma-text-12-regular">Regular text</span>

---

Integration with Existing Design Tokens

The Figma tokens use a --figma- prefix to avoid conflicts with existing design tokens in _design-tokens.scss.

Creating Semantic Aliases

You can create aliases to map Figma tokens to your design system:

:root {
  /* Map Figma tokens to semantic names */
  --brand-primary: var(--figma-color-primary-brand);
  --brand-accent-mint: var(--figma-color-secondary-mint);
  --brand-accent-blue: var(--figma-color-secondary-blue);

  /* Typography shortcuts */
  --text-small: var(--figma-typography-body-small-font-size);
  --font-body: var(--figma-font-family-poppins);
  --font-heading: var(--figma-font-family-inter);
}

---

Re-generating Tokens from Figma

Tip

Make sure you’re using Figma Desktop (not the web version) for token extraction to work properly.

To extract updated tokens from Figma:

1. Open Figma Desktop (must be desktop app, not web)
2. Navigate to your design file
3. Select the frame/component containing your design tokens
   • Look for frames named “Design Tokens”, “Design System”, “Variables”, etc.
   • Or select the entire page if variables are file-level
4. In Claude Code, invoke the figma-design-tokens skill
5. The skill will:
   • Extract all variables
   • Transform to W3C DTCG format
   • Generate CSS, TypeScript, and JSON files
   • Update the SCSS file
   • Validate compliance

Automation Tips

• Organize tokens in Figma: Create a dedicated “Design Tokens” page or frame
• Use Figma Variables: Define colors, spacing, and typography as Figma Variables for better extraction
• Consistent naming: Use consistent naming in Figma (e.g., “Primary/Brand”, “Secondary/Mint”)
• Update regularly: Re-extract tokens whenever your design system changes

---

W3C Design Tokens Format

The tokens.json file follows the W3C Design Tokens Community Group specification:

{
  "color": {
    "primary": {
      "brand": {
        "$type": "color",
        "$value": "#044076",
        "$description": "Primary brand color"
      }
    }
  },
  "spacing": {
    "6": {
      "$type": "dimension",
      "$value": "24px",
      "$description": "Spacing 6 (24px)"
    }
  }
}

Benefits:

• Cross-tool compatibility
• Design token transformation pipelines
• Integration with Style Dictionary and other build tools
• Token aliasing and references

---

TypeScript Type Safety

The TypeScript definitions provide type-safe access to tokens:

import { tokens } from '#styles/tokens/tokens'

// Fully typed - autocomplete works!
const brandColor = tokens.color.primary.brand     // '#044076'
const mintColor = tokens.color.secondary.mint     // '#96e2d6'
const spacing = tokens.spacing['6']                // '24px'
const fontFamily = tokens.fontFamily.poppins      // 'Poppins'

Benefits:

• IDE autocomplete
• Type checking catches errors
• Refactoring safety
• Documentation via types

---

Token Naming Conventions

Figma tokens follow a semantic naming convention:

Colors

• Primary: --figma-color-primary-{name}
• Secondary: --figma-color-secondary-{name}
• Grey: --figma-color-grey-{scale}
• Black: --figma-color-black-{variant}
• Semantic: --figma-color-{semantic}

Spacing

• Pattern: --figma-spacing-{multiplier}
• Example: --figma-spacing-6 = 24px (6 × 4px base)

Typography

• Font Family: --figma-font-family-{name}
• Composite: --figma-typography-{style}-{property}
• Example: --figma-typography-body-small-font-size

---

Validation

All generated tokens are validated for W3C DTCG specification compliance:

✅ Validation Checks:

• Required $type and $value properties present
• Token type consistency
• No circular references
• Correct value formats
• Valid color hex codes
• Proper dimension units

---

File Structure

src/styles/
├── _design-tokens-figma.scss    # Main Figma tokens file (35+ tokens)
├── tokens/
│   ├── tokens.css               # CSS custom properties
│   ├── tokens.ts                # TypeScript definitions
│   └── tokens.json              # W3C DTCG format
└── _design-tokens.scss          # Existing design tokens (kept separate)

---

Next Steps

Expand Token Coverage

Extract additional token types from Figma:

• More colors: Success, warning, info states
• Border radius: Card, button, input radius values
• Shadows: Elevation system
• More spacing: Complete the spacing scale
• Font sizes: Complete typography scale
• Line heights: Additional line height values

Theme Support

If your Figma file uses variable modes (light/dark themes):

1. Extract each mode separately
2. Generate theme-specific token files
3. Use CSS or JavaScript to switch themes

Build Integration

Integrate tokens into your build pipeline:

• Style Dictionary: Transform tokens for multiple platforms
• PostCSS: Process tokens with design token plugins
• Theme Generation: Auto-generate theme variants

---

Troubleshooting

No Variables Found

Problem: Extraction returns empty or limited results

Solutions:

1. Check if your Figma file has Variables defined (Variables panel in Figma)
2. Ensure you’ve selected a frame that uses or contains the variables
3. Try selecting the entire page or canvas
4. Verify you’re using Figma Desktop (not web)

Missing Tokens

Problem: Some expected tokens aren’t extracted

Solutions:

1. Variables must be defined in Figma’s Variables panel
2. Select the frame/component that contains all tokens
3. Check variable scopes and visibility settings in Figma

Typography Not Working

Problem: Typography tokens don’t apply correctly

Solutions:

1. Use individual properties instead of composite tokens
2. Use the provided utility classes (.figma-body-small)
3. Import the SCSS file in your component

---

Resources

• W3C Design Tokens Specification
• Figma Variables Documentation
• Style Dictionary
• Design Tokens Community Group
• Figma MCP Server Guide

---

Last Updated: 2025-01-22 Extraction Source: Figma Desktop MCP Server Format: W3C Design Tokens Community Group (DTCG) Total Tokens: 35+ Categories: Colors, Spacing, Typography, Fonts