figma-analyze-component-set — variant state machine → CSS
Take a Figma COMPONENT_SET (the purple dashed container holding all the variants of one component) and turn it into a code-generation blueprint: which property axes are state vs size, how each state maps to a CSS pseudo-class or ARIA attribute, and the minimal visual delta each state applies on top of the default variant. This is the bridge between "Figma has 12 button variants" and "emit one .btn rule + :hover/:disabled overrides."
Skill boundaries
use_figma rules — load the official figma-use skill first; it is the full Figma Plugin API reference. Essentials these scripts rely on: plain JS with top-level await + return (no IIFE, no figma.closePlugin(); console.log is not returned), inputs inlined as const at the top of each script, colors in 0–1 range, load fonts before any text op, await figma.getNodeByIdAsync(...), and atomic errors (a failed script applies nothing — read the error, fix, retry).- Full recursive tree (unlimited depth, reactions, instance refs) → use
figma-deep-component.
- Reorganizing variants into a labeled grid → use
figma-arrange-component-set.
- Adding/removing the properties themselves → use
figma-component-properties.
- This is a design-system code-gen capability that the native MCP's
getdesigncontext /
get_metadata do not provide — they return raw structure, not a variant→CSS state machine.
Workflow
- Get the COMPONENTSET id. From the user's selection (
figmaget_selection), a search, or a
node id they paste. It must be the set, not an individual variant — the script validates type.
- Run [
scripts/analyze-component-set.js](scripts/analyze-component-set.js) via use_figma
(skillNames: "figma-analyze-component-set"). Set const COMPONENTSETID at the top first.
- Read the result. It returns
variantAxes (each axis + its options), componentProps
(non-variant TEXT/BOOLEAN/INSTANCE_SWAP props → code props), a stateMachine with cssMapping (state name → CSS selector) and defaultSignature, and per-variant diffFromDefault.
- Generate code. Implement the default variant from
defaultSignature, then add one rule per
cssMapping entry applying only that variant's diffFromDefault. Map componentProps to framework props: BOOLEAN→boolean, TEXT→string, INSTANCE_SWAP→ReactNode/slot, VARIANT→union.
- Validate. Cross-check that every state in
stateMachine.states got a CSS rule, and that
token names in the diff (e.g. Color/Brand/Primary) resolve to your exported tokens.
How states map to CSS
The script normalizes the state axis value (case-insensitive) to a selector:
| Variant value |
CSS / ARIA selector |
default |
(base rule, no selector) |
hover |
:hover |
focus / focused / focus-visible |
:focus-visible |
active / pressed |
:active |
disabled |
:disabled, [aria-disabled="true"] |
error / invalid |
[aria-invalid="true"] |
selected |
[aria-selected="true"] |
checked |
:checked |
loading |
[aria-busy="true"] |
open / closed |
`[aria-expanded="true" |
"false"]` |
filled |
.has-value |
Notes
- Diffs are computed against the default variant, so a state's
diffFromDefault lists only the
properties that change (fill token, stroke, text color, opacity, effects, child visibility). Emit exactly those as overrides — don't re-specify unchanged properties.
- The script resolves
boundVariables (fills/strokes) to token names when available, falling
back to raw hex. Prefer the token name in generated code.
- Axis detection is heuristic: an axis named
state/status/interaction is the state axis;
size/scale is the size axis. If your set names axes differently, the cssMapping may be empty — read variantAxes and map states yourself.
