🧱CSS Variables

CSS variables allow you to attach a value to a variable and reuse that variable throughout the Style Panel inputs.

Hint: Data Variables are different than CSS Variables. They enable the reuse of data in the Settings tab.

Why Use CSS variables?

• Consistency – Define a value once, like a color, and access that variable in every style input field.

• Speed – Design quickly by selecting predefined variables from autocomplete.

• Experimentation – Arrow through autocomplete and get real-time rendering of that variable to see which value looks best in your design.

• Parent-child interactions – Have full control over the styles of all child instances when interacting with the parent.

CSS variables vs. Tokens

The concept of “reusability” is present in both CSS variables and Tokens, but they are different and complement each other exceptionally well.

CSS variables and Tokens

Let’s think of these two concepts as layers or building blocks.

Layer 1: CSS Variables

CSS variables are the bottom layer. They comprise individual variable names and values often used for sizes, colors, and other styles with many input options.

For example, you can create one variable per color in your design system. Those colors are going to be used throughout your site and in Tokens.

Layer 2: Tokens

Tokens are the next layer. They package up multiple styles. A Card Token may include padding, color, and gap styles, for example.

The values you enter for each style should be defined as variables. This approach ensures consistent designs and allows you to update a value in one place, with the change automatically reflected wherever the variable is used.

With CSS variables, Tokens now often take a more semantic approach, such as calling them Card, Team Member, or Testimonial. Without CSS variables, Tokens were a blend between semantic and utility, such as padding-medium, font-size-small, and Card.

Tip: While some utility Tokens will still be present, the majority of Tokens should be semantic.

Creating variables

Before you create custom variables, be sure to check out Craft — the standard guideline for building with Webstudio. It contains a library of expertly crafted CSS variables.

A CSS variable is defined in the Advanced section by using two dashes followed by the variable name, like this:

--gray-5

This syntax is not unique to Webstudio. It’s the official CSS variable syntax.

Then, the variable's value can be anything such as a color, gradient, duration, size, or number.

Creating a variable and assigning a value

Using variables

Once the variable is defined, you can use it on the instance it was defined on and any of its children.

The variables are available in the autocomplete, so you can access variables by typing them in.

The autocomplete search algorithm is very flexible, letting you search by any of the following:

• --

• var

• gray (variable name)

You can search any part of your variable, and autocomplete will show you the proper results.

The syntax for displaying a variable isvar(--my-var), though it's much faster to search using --. Webstudio automatically handles the conversion to ensure proper output.

Scope

CSS variables, by nature, are available in the current instance and any of the children.

Global Variables

Global Root

Most variables should be defined on the Global Root, which is the highest level of the page and the same for every page. That way, you can define --my-color, and it's available on every instance on every page.

Local variables

Some variables are only needed on a specific section or page. You can define these variables on a common ancestor of where they need to be accessed, such as a Box/wrapper.

Here are some use cases for local variables:

• Changing a child's design when interacting with the parent (see Parent-child interactions for more info).
• Doing an A/B test without modifying the entire design system

• Running a seasonal promotion and modifying colors for a section

Parent-child interactions

With CSS variables, you can interact with the parent and modify the styles of any of the children.

Hovering the link and the children change (icon color, icon bg, and arrow appears)

Video tutorial

Here are the high-level steps to accomplish this pattern:

1. Take note of the various properties you want to change such as color and background color.

2. Create a variable on the parent for each style property such as --child-color and --child-bg. Leave the values empty for now.

3. Add the variables to the various children's style inputs, such as setting background to --child-bg (no style changes will happen yet because the variables don't have values).

4. Go back to the parent, where the variables are defined, and give them values for the default state.

5. Switch to the other state, such as hover, and change the variables' values.

6. Interact with the parent and see the child change!

For step 2, it's possible to define variables and assign values all at once, but it's better to add the variables to the children first. If the variables aren't added to the children, the assigned values won't render anywhere, which makes it difficult to determine things like which color to use.

You can define as many variables as you want and use them on any children where they are defined to create more complex interactions.