Design tokens as Figma variables

Design systems express their tokens as CSS custom properties. When a component is imported, story.to.design turns the custom properties it depends on into Figma variables, and binds the fills, strokes, radii, gaps and font sizes of the imported layers to them.

Which custom properties become variables

A custom property is a token when it is declared outside the component itself: on :root, on body, on a theme class, in a stylesheet the component reads but does not own. Custom properties declared inside the component are implementation details and stay hardcoded values.

Properties whose name starts with --_ are skipped: this is the convention for private properties.

Use variables.ignores in the import defaults to leave out more of them.

Naming

The variable name is derived from the custom property name. A double dash separates groups, a single dash stays in the name:

A property whose value is another custom property, such as --button--background: var(--color--brand--500), becomes an alias of that variable rather than a copy of its value.

Modes

When your Storybook has a theme global, each of its values becomes a mode of the variable collection. The global is detected by its name (theme, mode or scheme), or named explicitly with variables.modeArg in the import defaults.

Every imported story is also captured once per other value of that global, so every mode gets its values even when you import a single theme. Without a theme global, a single Default mode holds every value.

The Variables tab

The Variables tab lists every token found in the imported components, next to the values the collection holds in Figma. Each row tells you whether applying would create the variable, update its value, or leave it as is.

All variables live in one collection, s2d unless variables.collection says otherwise. Apply in Figma creates or updates the variables, then re-processes the imported components so their layers bind to the new values.

Migrating from paint styles

Earlier versions created Figma paint styles instead of variables. Re-process your components to bind them to variables; the paint styles remain in the file as local styles and can be deleted from Figma’s style panel.

The styleMapping section of the import defaults became variables: styleMapping.ignores is now variables.ignores, and styleMapping.prefix is replaced by variables.collection.