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.

The tokens of every imported story are also collected once per value of that global, with the story default args, so every mode gets its values even when you import a single theme. These captures only read the custom properties, they are not imported as components. When your variants declare their own tokens, set variables.perVariantModes to collect each variant in every mode instead. 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.

Once the collection exists, importing a component or updating your Storybook only adds the variables the collection is missing. Existing variables are never overwritten on import: a value that changed in your Storybook shows up as an update in the Variables tab, and only Apply in Figma writes it. One exception: a font-family variable holding a CSS family name Figma cannot load is rewritten to the matching Figma family, since Figma refuses the binding otherwise.

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.