cris-achiardi/claude-skills/figma-variables-generator

Figma Variables Generator

Generate properly formatted JSON files for creating Figma variable collections from text descriptions, existing design token data, or images showing design systems.

Core Capabilities

This skill helps designers create Figma variable collections by generating the JSON format required by Figma variable import/export plugins. The output can be directly imported into Figma using plugins like "Variables Import Export" or similar tools.

Supported Variable Types

Figma supports only 4 core variable types:

• Color ($type: "color") - RGB hex values, rgba, or variable references
• Number ($type: "number") - Numeric values (spacing, sizes, radius, weights, etc.)
• String ($type: "string") - Text values (font families, names, etc.)
• Boolean ($type: "boolean") - True/false values

Important: Types like spacing, borderRadius, fontSize, fontWeight should use number type. Use semantic naming in your variable paths to indicate their purpose (e.g., spacing.xs, radius.md, fontSize.body)

Key Features

1. Multiple Modes: Support for different modes (e.g., Light/Dark themes)
2. Variable References: Use {collection.subcategory.variableName} syntax to reference other variables
3. Code Syntax: Optional platform-specific naming conventions (WEB, iOS, ANDROID)
4. Hierarchical Organization: Group variables into collections, categories, and subcategories
5. Flexible Input: Accept design tokens from text, structured data, or images

Workflow

Step 0: Check for Existing JSON (For Updates or Reformatting)

CRITICAL: When the user asks to update, add to, or reformat an existing JSON file, you MUST:

1. Read the existing file first - Use the Read tool to load the current JSON
2. Preserve all naming exactly - Collection names, category names, subcategory names, and variable names must match EXACTLY
3. Understand Figma's behavior: Figma uses names as unique identifiers:

• Same name = overwrites/updates the variable
• Different name = creates a new variable/collection/category

1. Maintain hierarchy - Keep the exact same nesting structure
2. Reorder for readability - If JSON is messy or poorly organized, reorder it following the guidelines in Step 2.5

Example Scenario:

• Existing: {"Spacing": {"space": {"sm": {"$type": "number", "$value": 8}}}}
• User asks: "Add a medium spacing value"
• ✅ Correct: Add to existing structure: {"Spacing": {"space": {"sm": {...}, "md": {...}}}}
• ❌ Wrong: Create new structure: {"Spacing": {"spacing": {"md": {...}}}} (creates duplicate category)

Step 1: Gather Information

Before generating the JSON, ask the user:

1. New or Update: Is this a new collection or updating an existing one?

• If updating: Request the existing JSON file to preserve naming

1. Collection Name: What should the variable collection be named?
2. Variable Content: What variables need to be created? (Accept text descriptions, existing JSON, or analyze uploaded images)
3. Modes: Does this collection need multiple modes (e.g., Light/Dark)? What should they be named?
4. Code Syntax: Should code syntax be included? If yes:

• Which platforms? (WEB, iOS, ANDROID)
• What naming convention? (camelCase, snake_case, kebab-case, PascalCase)

1. Organization: How should variables be organized? (category/subcategory structure)

Step 2: Generate JSON Structure

Create a JSON file following this structure:

Step 2.5: Format and Order for Readability

When generating or reformatting JSON, follow these ordering principles for maximum human readability:

1. Property Order within Each Variable:

{
  "variableName": {
    "$type": "color",           // 1. Type first
    "$value": "#ffffff",         // 2. Value second
    "$description": "...",       // 3. Description (if present)
    "$extensions": {...}         // 4. Extensions last
  }
}

2. Variable Ordering within Categories:

• Size-based: Order by size (xs → sm → md → lg → xl)
• Numeric: Order numerically (0 → 1 → 2 → 3...)
• Semantic priority: Order by importance (primary → secondary → tertiary)
• Alphabetical: Use as fallback when no other logic applies

3. Category Ordering: Order categories logically:

1. Primitives/base values first (colors, raw values)
2. Semantic/functional tokens second (text, background, border)
3. Component-specific tokens last (button, card, modal)

4. Indentation and Formatting:

• Use 2-space indentation
• Each property on its own line
• Consistent spacing between objects
• No trailing commas

Example of Well-Ordered JSON:

{
  "Design System": {
    "primitives": {
      "gray": {
        "100": {"$type": "color", "$value": "#f7f7f7"},
        "200": {"$type": "color", "$value": "#e1e1e1"},
        "300": {"$type": "color", "$value": "#cfcfcf"}
      }
    },
    "semantic": {
      "text": {
        "primary": {"$type": "color", "$value": "{Design System.primitives.gray.300}"},
        "secondary": {"$type": "color", "$value": "{Design System.primitives.gray.200}"}
      }
    },
    "spacing": {
      "xs": {"$type": "number", "$value": 4},
      "sm": {"$type": "number", "$value": 8},
      "md": {"$type": "number", "$value": 16},
      "lg": {"$type": "number", "$value": 24},
      "xl": {"$type": "number", "$value": 32}
    }
  }
}

Step 3: Generate the JSON File

Create a JSON file following this structure:

{
  "Collection Name": {
    "category": {
      "subcategory": {
        "variableName": {
          "$type": "color",
          "$value": {
            "Light": "#ffffff",
            "Dark": "#000000"
          },
          "$extensions": {
            "codeSyntax": {
              "WEB": "categorySubcategoryVariableName"
            }
          }
        }
      }
    }
  }
}

Step 4: Apply Naming Conventions

When code syntax is requested:

camelCase (default for WEB):

• foreground.base → foregroundBase
• background.interactive.primary → backgroundInteractivePrimary

snake_case (common for Python, some backend systems):

• foreground.base → foreground_base
• background.interactive.primary → background_interactive_primary

kebab-case (common for CSS):

• foreground.base → foreground-base
• background.interactive.primary → background-interactive-primary

PascalCase (common for some component systems):

• foreground.base → ForegroundBase
• background.interactive.primary → BackgroundInteractivePrimary

Step 5: Convert Units to Pixels

CRITICAL: Figma only works with pixel values. Always convert relative units to pixels:

Common Conversions (assuming 16px base font size):

• 1rem → 16 (pixels)
• 2rem → 32 (pixels)
• 0.875rem → 14 (pixels)
• 1em → 16 (pixels, context-dependent)
• 1.5em → 24 (pixels, context-dependent)

Percentage/Viewport Units (ask user for context if needed):

• 100% → ask for parent container size
• 50vw → ask for viewport width or use common breakpoint
• 10vh → ask for viewport height or use common breakpoint

Other Units:

• 1pt → 1.333 (pixels)
• 1pc → 16 (pixels, 1 pica = 12 points)

When encountering unit-based values, automatically convert to pixels without units in the JSON output.

Example:

• Input: font-size: 1.5rem → Output: "$value": 24
• Input: spacing: 2rem → Output: "$value": 32
• Input: line-height: 1.5em → Output: "$value": 24

Step 6: Handle Variable References

For variables that reference other variables (aliases), use the reference syntax:

{
  "Semantic Colors": {
    "text": {
      "primary": {
        "$type": "color",
        "$value": {
          "Light": "{Color Primitives.gray.gray900}",
          "Dark": "{Color Primitives.gray.gray100}"
        }
      }
    }
  }
}

The reference format is: {CollectionName.category.subcategory.variableName}

Examples

Example 1: Simple Color Tokens

Input: "Create a collection called 'Brand Colors' with primary (#389fba), secondary (#c9a0dc), and white (#ffffff) colors for light and dark modes"

Output:

{
  "Brand Colors": {
    "primary": {
      "$type": "color",
      "$value": {
        "Light": "#389fba",
        "Dark": "#389fba"
      }
    },
    "secondary": {
      "$type": "color",
      "$value": {
        "Light": "#c9a0dc",
        "Dark": "#c9a0dc"
      }
    },
    "white": {
      "$type": "color",
      "$value": {
        "Light": "#ffffff",
        "Dark": "#ffffff"
      }
    }
  }
}

Example 2: Spacing Scale with Code Syntax

Input: "Create a spacing scale collection with values 0, 8, 16, 24, 32px. Use camelCase for web."

Output:

{
  "Spacing": {
    "space": {
      "0": {
        "$type": "number",
        "$value": 0,
        "$extensions": {
          "codeSyntax": {
            "WEB": "space0"
          }
        }
      },
      "1": {
        "$type": "number",
        "$value": 8,
        "$extensions": {
          "codeSyntax": {
            "WEB": "space1"
          }
        }
      },
      "2": {
        "$type": "number",
        "$value": 16,
        "$extensions": {
          "codeSyntax": {
            "WEB": "space2"
          }
        }
      },
      "3": {
        "$type": "number",
        "$value": 24,
        "$extensions": {
          "codeSyntax": {
            "WEB": "space3"
          }
        }
      },
      "4": {
        "$type": "number",
        "$value": 32,
        "$extensions": {
          "codeSyntax": {
            "WEB": "space4"
          }
        }
      }
    }
  }
}

Example 3: Unit Conversion from rem to pixels

Input: "Create typography tokens: body is 1rem, heading-sm is 1.25rem, heading-md is 1.5rem, heading-lg is 2rem"

Output:

{
  "Typography": {
    "fontSize": {
      "body": {
        "$type": "number",
        "$value": 16,
        "$extensions": {
          "codeSyntax": {
            "WEB": "fontSizeBody"
          }
        }
      },
      "headingSm": {
        "$type": "number",
        "$value": 20,
        "$extensions": {
          "codeSyntax": {
            "WEB": "fontSizeHeadingSm"
          }
        }
      },
      "headingMd": {
        "$type": "number",
        "$value": 24,
        "$extensions": {
          "codeSyntax": {
            "WEB": "fontSizeHeadingMd"
          }
        }
      },
      "headingLg": {
        "$type": "number",
        "$value": 32,
        "$extensions": {
          "codeSyntax": {
            "WEB": "fontSizeHeadingLg"
          }
        }
      }
    }
  }
}

Example 4: Semantic Colors with References

Input: "Create semantic colors that reference primitives. Text primary should use gray900 in light mode and gray100 in dark mode."

Output:

{
  "Semantic Colors": {
    "text": {
      "primary": {
        "$type": "color",
        "$value": {
          "Light": "{Primitives.gray.gray900}",
          "Dark": "{Primitives.gray.gray100}"
        },
        "$extensions": {
          "codeSyntax": {
            "WEB": "textPrimary"
          }
        }
      }
    }
  }
}

Example 5: Updating an Existing Collection

Existing JSON:

{
  "Spacing": {
    "space": {
      "xs": {
        "$type": "number",
        "$value": 4
      },
      "sm": {
        "$type": "number",
        "$value": 8
      }
    }
  }
}

User Request: "Add medium (16px) and large (24px) spacing values"

Correct Output (preserves naming and structure):

{
  "Spacing": {
    "space": {
      "xs": {
        "$type": "number",
        "$value": 4
      },
      "sm": {
        "$type": "number",
        "$value": 8
      },
      "md": {
        "$type": "number",
        "$value": 16
      },
      "lg": {
        "$type": "number",
        "$value": 24
      }
    }
  }
}