Variables and themes

Variables store shared values such as colors, spacing, and fonts. Bind a property to a variable instead of entering the same value on every element. Changing the variable updates the elements that use it.

Themes give those variables different values. A surface color can be white in Light and near-black in Dark, while the same component uses surface in both themes.

What are Variables?

For variables shared through an imported library, save the source library and reopen the documents that import it to load changes.

Creating Variables

1. Click Variables in the toolbar
2. Choose Add variable, then Color, Number, String, or Boolean
3. Enter a name and value in the new row

Use the row menu to rename, duplicate, or delete a variable. Prefer names for purpose, such as surface and text-primary, when their values differ between themes.

Bring in existing tokens

For CSS tokens, give the agent access to your token file and ask it to create the corresponding pen.dev variables:

Read src/styles/tokens.css and create pen.dev variables for its colors,
spacing, and typography. Preserve the token names and light/dark values.

For values in Figma, copy individual values or attach a screenshot of the variables table and ask the agent to recreate them. Review the types, names, values, and theme assignments in Variables before using the result. An agent request copies the values; later source changes need another request.

Using Variables

Use Apply variable beside a supported property and choose a variable of the matching type. Apply color variables to fills and strokes, number variables to spacing and font sizes, string variables to font names, and boolean variables to visibility controls.

Bind the properties in a component origin so its instances inherit those bindings. A value entered directly on an instance overrides the inherited property; it will not follow changes to that property’s variable binding.

Theming

Use + beside the column headings in Variables to add a theme value, such as Dark. Rename a column from its menu, then set the variable values for that column. Keep values the same across columns when they should not change with the theme.

The + beside the theme tabs adds a separate axis, such as Device. An axis is a choice with its own values: Theme can have Light and Dark, while Device has its own choices.

To apply a theme:

1. Select the frame you want to change
2. In the properties panel, choose Theme → Add theme and select the axis
3. Select its value, such as Dark

Children inherit that choice unless they have their own setting for the same axis. Remove theme restores inheritance. The first value of each axis is the document default.

Variable aliases

A variable can reference another variable of the same type. For example, button-fill can reference accent, so changing accent also changes the button color. Use the variable picker in the value cell to create the reference.

If a value looks wrong, check the selected element’s Theme, its parents’ theme settings, and the referenced variable’s value in that theme. Define a value for every theme you use.

See copying between documents for variable conflicts when pasting.

Sync with Code

Use the design/code token workflow to bring code changes into your variables or apply design changes to CSS.