Figma Integration

When to use this skill

Use this skill when you need to:

• Create Figma variables from design token data
• Generate Figma console scripts for automated variable creation
• Map CSS properties to correct Figma variable types and scopes
• Work with Figma variable collections and modes
• Convert token naming conventions to Figma-compatible formats

How Figma variables work

Variable types

Figma supports four variable types:

• COLOR: RGB color values with alpha
• FLOAT: Numeric values (dimensions, opacity, etc.)
• STRING: Text values (font names, text content)
• BOOLEAN: True/false values

Variable scopes

Scopes determine where variables can be applied:

Color scopes

• FRAME_FILL: Background fills for frames
• SHAPE_FILL: Fill colors for shapes
• TEXT_FILL: Text color
• STROKE_COLOR: Border and stroke colors
• EFFECT_COLOR: Shadow and effect colors

Float scopes

• WIDTH_HEIGHT: Element dimensions
• CORNER_RADIUS: Border radius values
• GAP: Spacing (padding, margin, gaps)
• STROKE_FLOAT: Border width
• OPACITY: Transparency values
• FONT_SIZE: Text size
• FONT_WEIGHT: Font weight values
• LINE_HEIGHT: Line height
• LETTER_SPACING: Character spacing
• EFFECT_FLOAT: Shadow blur, spread, offset

String scopes

• FONT_FAMILY: Font family names
• ALL_SCOPES: General text content

Property to type/scope mapping

The skill automatically maps CSS properties to Figma types and scopes:

const propertyMapping = {
  // Colors
  'background-color': { type: 'COLOR', scopes: ['FRAME_FILL', 'SHAPE_FILL'] },
  'text-color': { type: 'COLOR', scopes: ['TEXT_FILL'] },
  'border-color': { type: 'COLOR', scopes: ['STROKE_COLOR'] },
  'shadow-color': { type: 'COLOR', scopes: ['EFFECT_COLOR'] },
  
  // Dimensions
  'width': { type: 'FLOAT', scopes: ['WIDTH_HEIGHT'] },
  'height': { type: 'FLOAT', scopes: ['WIDTH_HEIGHT'] },
  'border-radius': { type: 'FLOAT', scopes: ['CORNER_RADIUS'] },
  'padding': { type: 'FLOAT', scopes: ['GAP'] },
  'margin': { type: 'FLOAT', scopes: ['GAP'] },
  'gap': { type: 'FLOAT', scopes: ['GAP'] },
  
  // Typography
  'font-family': { type: 'STRING', scopes: ['FONT_FAMILY'] },
  'font-size': { type: 'FLOAT', scopes: ['FONT_SIZE'] },
  'font-weight': { type: 'FLOAT', scopes: ['FONT_WEIGHT'] },
  
  // Effects
  'border-width': { type: 'FLOAT', scopes: ['STROKE_FLOAT'] },
  'opacity': { type: 'FLOAT', scopes: ['OPACITY'] }
};

Generating Figma console scripts

Basic usage

const tokens = [
  { name: 'button/primary/background-color', type: 'COLOR', scopes: ['FRAME_FILL'] },
  { name: 'button/primary/text-color', type: 'COLOR', scopes: ['TEXT_FILL'] },
  { name: 'spacing/md', type: 'FLOAT', scopes: ['GAP'] }
];

const script = generateFigmaScript(tokens, 'My Design System');

Script features

The generated script will:

1. Find or create collection: Searches for existing collection by name
2. Create variables: One variable per token with correct type
3. Set default values: Appropriate placeholder values by type
4. Apply scopes: Assigns correct scopes for each property
5. Handle errors: Graceful error handling with user feedback
6. Provide feedback: Console logging and Figma notifications

Default values by type

• COLOR: { r: 0.5, g: 0.5, b: 0.5, a: 1 } (medium gray)
• FLOAT: 1
• STRING: 'string'
• BOOLEAN: true

Running the script in Figma

1. Generate the script using this skill
2. Open Figma and navigate to your file
3. Open console (⌘ + ⌥ + I on Mac, Ctrl + ⌥ + I on Windows)
4. Paste and run the generated script
5. Variables created in the specified collection

Working with collections and modes

Collection management

• Script searches for existing collections by name (case-insensitive)
• Falls back to partial name matching if exact match not found
• Creates new collection if none found
• Uses the default mode for value assignment

Mode handling

• Script works with the collection's default mode
• Values are set using variable.setValueForMode(modeId, value)
• Additional modes can be configured manually after creation

Error handling

The script includes comprehensive error handling:

• Collection validation: Ensures collection exists and has modes
• Variable creation: Catches naming conflicts and invalid characters
• Value assignment: Handles type mismatches gracefully
• Scope assignment: Falls back to ALL_SCOPES if specific scopes fail

Examples

Creating button tokens

const buttonTokens = [
  { 
    name: 'button/primary/default/background-color', 
    type: 'COLOR', 
    scopes: ['FRAME_FILL', 'SHAPE_FILL'] 
  },
  { 
    name: 'button/primary/default/text-color', 
    type: 'COLOR', 
    scopes: ['TEXT_FILL'] 
  },
  { 
    name: 'button/primary/default/border-radius', 
    type: 'FLOAT', 
    scopes: ['CORNER_RADIUS'] 
  }
];

const script = generateFigmaScript(buttonTokens, 'Button System');
// Copy script to Figma console

Creating spacing tokens

const spacingTokens = [
  { name: 'spacing/xs', type: 'FLOAT', scopes: ['GAP'] },
  { name: 'spacing/sm', type: 'FLOAT', scopes: ['GAP'] },
  { name: 'spacing/md', type: 'FLOAT', scopes: ['GAP'] },
  { name: 'spacing/lg', type: 'FLOAT', scopes: ['GAP'] }
];

const script = generateFigmaScript(spacingTokens, 'Spacing Scale');

Best practices

1. Collection naming: Use clear, descriptive collection names
2. Token organization: Group related tokens in the same collection
3. Scope specificity: Use specific scopes rather than ALL_SCOPES when possible
4. Value setting: Update placeholder values with real design values after creation
5. Mode management: Configure additional modes (dark theme, etc.) manually after script execution
6. Testing: Run scripts on test files before production use