Figma Token Extractor

What this skill does

Parses a Figma file's variables export (or a styles export) and produces a CSS custom-properties file with tokens grouped by category: color, spacing, typography, radius, shadow.

Inputs

• figma_export: path to a JSON file containing variables and/or styles from the Figma API (GET /v1/files/<key>/variables/local or GET /v1/files/<key>/styles).
• Optional out_path: defaults to tokens.css.
• Optional prefix: CSS variable prefix (default --).
• Optional scope: collection name to scope to (e.g., Brand).

Steps

1. Validate JSON: confirm the file has a variables or styles key. Abort otherwise.
2. Parse variable collections from variables.meta.variables. Each variable has id, name, resolvedType, valuesByMode.
3. Parse classic styles from styles if present (older files): FILL, TEXT, EFFECT, GRID types.
4. Map type to category: COLOR -> color, FLOAT named like space* or padding* -> spacing, FLOAT named radius* -> radius, STRING named like font* -> typography token.
5. Slugify token names using a path/to/Token -> --path-to-token rule.
6. Resolve color values: Figma RGBA (0..1 floats) -> hex with optional alpha. Convert via Math.round(value * 255).toString(16).padStart(2, '0').
7. Group output by category under a :root { ... } block; emit a comment header per group.
8. If a collection has multiple modes (e.g., light/dark), emit a [data-theme="dark"] { ... } block per non-default mode with overrides only for changed tokens.
9. Write to out_path.

Output

tokens.css containing :root { --... } blocks per category and per-mode overrides. Stdout prints the count of tokens per category and any tokens whose category was inferred (not explicitly tagged).

Verification

Open the produced file and confirm every group's variable names are valid CSS identifiers (regex [a-zA-Z][a-zA-Z0-9-]*). Validate with npx stylelint tokens.css --no-config. Re-import the CSS into a sandbox HTML and confirm browsers compute the expected colors via getComputedStyle(document.documentElement).getPropertyValue('--<name>'). If the Figma export contains alias references that resolve to other variables, ensure the emitted CSS preserves the alias (using var(--other)).

Edge cases

• Figma file with no variables (older files using only styles): fall back to the styles export and warn.
• Token names containing slashes vs spaces: normalize both to hyphens.
• Modes named with non-ASCII characters: transliterate or fall back to mode index (mode-1).
• Overlapping token names across collections: prefix tokens with collection name to disambiguate.