Properties, styles, and tokens

Choose your track

Read this module through your lens

The combinatorial trap

Variants are so satisfying that beginners use them for everything, and that leads straight into a wall. Model a button’s size (3) times icon-or-not (2) times state (3) as variants and you already have 18; add one more option and it doubles. The properties panel becomes an unnavigable grid, and every new dimension multiplies the work. This is the combinatorial explosion, and it is the classic intermediate failure.

The escape is a distinction. Some choices are mutually exclusive states of one thing — a button is default OR hover OR disabled, never two at once. Those are variants. Other choices are independent options that combine freely — size, whether an icon shows, what the label says. Those should be component properties, not variants. Get this split right and the same button that needed 18 variants needs 3 variants and a handful of properties.

Properties: options without explosion

Component properties let an instance expose adjustable options in the panel without creating new variants. There are a few kinds, and each replaces a whole axis of variants. A boolean property toggles a layer — “show icon?” — instead of doubling your variant count. A text property exposes a label for editing without diving into the layer. An instance-swap property lets you choose which icon or sub-component goes in a slot. An exposed nested property surfaces a child component’s controls on the parent.

The mental model: variants are the states the component can be in; properties are the knobs you turn on any state. Size becomes a property, icon visibility a boolean, the label a text property — and suddenly the component is both more flexible and far simpler, because options multiply additively in the panel instead of multiplicatively in the variant grid.

Styles and tokens: change once, theme everything

The other intermediate leap is getting values out of the components. A button with the colour typed in as a hex value, padding as a magic number, and a font set inline is a button that must be edited by hand to change anything global. Multiply by a real system and a brand tweak or a dark mode becomes days of work.

Styles and variables fix this. A colour style or a colour variable is a named, central value — “brand/primary”, “surface/raised” — that components reference instead of hard-coding. Text styles do the same for type. Variables (design tokens) go further: spacing, radius, and colour become named tokens grouped in collections, and you can swap the whole collection — a light set for a dark set — to re-theme the entire product without touching a single component.

This is also the cleanest bridge to engineering: these tokens are essentially the design tokens the codebase will consume, so a tokenised Figma file is already speaking the build’s language.

Hands-on exercise

Take your button component and refactor it: keep variants only for true states, and convert size and icon-visibility into properties (a size property, a boolean for the icon, an instance-swap for which icon, a text property for the label). Move every colour to a colour variable and the type to a text style. Then build a second variable collection for dark mode and prove you can re-theme the whole thing with one swap. Capture the before/after of the component panel.

Second case · a button with size and icon options

The same lesson, a different object

Common failures · spot them fast

The failure gallery

Each of these is caught by a quality gate — keep the cheatsheet open while you work.

Worked example

See the journey

Cheatsheet

Reflection