Variables
Variables in Webflow and how Client-First uses them - strategies, naming conventions, and practical usage tips.
What are the benefits of using variables in your website?
Consistency across the project
Variables help unify styling throughout a project. All the reused element styling - spacing, text colors, background colors, gaps, border radius, and more - derives its value from variables. By defining a value once and using it in multiple places, we keep that value consistent across the entire site.
This is how we make sure the color scheme, spacing, and other crucial styles stay consistent everywhere they're used.
Ease of maintenance
If we need to change a value, we only have to update it in one place - the Variables panel. Because variables are reused site-wide, any global style change - button colors, background colors, spacing - is quick and convenient to apply. Updating a variable changes that value everywhere in the project, making maintenance more straightforward and reducing errors.
Theming
Using color variables will simplify the creation of different themes, including dark/light modes. By changing the set of color variables, we can easily switch between themes, allowing for more dynamic and customizable designs.
Improved readability and organization
When variables are named on purpose, we no longer need to remember or search for their underlying CSS values. Appropriate names make the styles more readable and organized to work with. For example, when we want to find the color used on the body, we can search for the word primary inside the group Text instead of recalling a specific hex code.
Context for usage
Organized semantic variables help us understand which style to use during the building process. The name of the variable gives us a lot of information about how it's used in the project.
If we need to add a text color to a heading, we can quickly find the project's text colors in the Text group under the Theme collection.
Key concepts for variables
Variable collections
Client-First organizes variables into the following collections:
- Base - Contains all primitive variables (tokens) used throughout the project, including colors, typography values, and others.
- Theme - Contains semantic color variables used across the project.
- Typography - Contains semantic typography variables used throughout the project.
- Layout - Contains layout and spacing-related variables.
- Sizes - Contains variables related to element sizing.
Variable groups
Inside each collection, we can create groups to further organize variables. With Client-First, the Theme collection includes groups like Background, Border, Text, and Link, while the Size and Layout collections include groups like Spacing, Max Width, and Container.
You're free to create more groups or edit existing ones based on your project's requirements.
Responsive variables
With Webflow's Variable modes, we can now change the value of any variable based on the breakpoint. Client-First currently uses this feature for the Typography and Layout (spacing) variables, but it can be applied to other variable collections whenever a project needs it.
With responsive variables, you no longer need to adjust values manually on each element across breakpoints. The values are managed automatically through the responsive variable modes.
Variable modes for theming
Webflow's native Variable modes feature also lets us create multiple themes for a website - for example, light mode and dark mode. A robust variable setup makes this process smooth, since the semantic structure lets us define the values for each theme easily.
Once a theme is set up, you can switch it directly from the Style panel, or create a utility class like theme-dark or theme-light to apply on top of individual elements or sections.
Primitive and semantic tokens
Primitive tokens
Primitive tokens are the foundational building blocks of the website's styles. They carry the actual CSS values that every other variable on the site references to derive its own value. Client-First currently uses primitives mostly for color tokens, along with some font-related values.
Primitive tokens are named based on their actual CSS value and generally do not represent a purpose in their name, since they're used across multiple purposes and places.
For example, colors are named as red-light or red-100, blue-dark or blue-600`
How to use primitives
In practical terms, primitives are used to create the semantic variables that get implemented in the project. Rather than applying a primitive directly to an element, we point a semantic variable at the primitive, and use the semantic variable when building.
⚠️ Avoid directly linking primitives to classes unless there is a strong reason to do so.
It's only recommended to link a style directly to a primitive if you don't plan to reuse that primitive anywhere else. In almost every case, go through a semantic variable instead - this keeps theming and global changes possible without reworking individual elements.
Semantic tokens
Semantic tokens derive their value from primitive tokens and are created to be reused for a specific purpose on the website. Client-First currently uses these mostly for the Theme and Typography collections.
Semantic tokens are named based on their purpose, with the group and variable name working together. For example: Background › primary, Text › secondary, Button › text - where "Background", Text, and Button" are group names, and primary, secondary, and text are the variable names themselves. Read together, the group and variable name tell you exactly what the variable is for.
How to use semantic tokens
Semantic tokens are the variables we use to style the elements of our website according to their use. Reading the group and variable name of a semantic token tells us exactly where it belongs - background tokens for backgrounds, text tokens for text, spacing tokens for padding and gaps, and so on.
In the examples below, we can see specific use cases where these tokens should be used. These examples are from the Theme variable collection.
For background color, use the Background semantic tokens:
For text color, use the Text semantic tokens:
For border color, use the Border semantic tokens:
Variable naming
Group naming - Variables can be organized into groups for better usage. Groups are named in sentence case, for example: Background, Border, Text". These groups contain the variables themselves.
Variable naming - All variables are named in lowercase with a hyphen (-) instead of spaces. This difference in naming creates a visual distinction between the groups and the actual variables.
Variable names should not include the name of their group
Variable names shouldn't include the name of their group. For example, avoid background-primary inside a Background group. It makes the name longer and creates readability issues in the Designer.
Exception to this guideline
The only exception to this guideline is when you need more detail about the variable visible inside the Style panel. Let's look at two examples:
Use case 1: You have a paragraph, and the Style panel shows the variable name primary" on it. Since a paragraph is text, "primary" should refer to the text color only, not the background color.
Use case 2: You have an H3 heading, and the default variable name for font size is font-size" You know it's H3's font size, but what if you want to add a font size from H2 or H4? If all of them share the same variable name font-size, you'll lose context on where it's coming from inside the Style panel. In this case, we prefer adding the group name to the variable name, like h2-font-size` or h3-font-size`.
If you come across similar cases where more context matters, feel free to add the group name to the variable name. The reason for keeping names short by default is better searchability and readability in the Designer, as long as you're following that principle, you're good.
Searching variables in the Style panel
When searching for variables in the Style panel, Webflow lets you search by name, group, or value. For the best results, we recommend searching by the group name to narrow the results down to exactly what you need.
For example, if you're looking for the primary color used on text, searching primary will also surface other variables that include primary in their name - like background or border. Instead, search for the group, Text`, so the results show only Text-related variables. See an example below where searching for Spacing shows all spacing related variables:
Do not name a semantic variable with the name of the color
If we name a variable simply by its color, any change in color schemes or themes would require renaming the token. This defeats the purpose of semantic tokens, which is to abstract the design from specific color values. This allows us to manage theming and global changes without renaming variables.
The naming convention is important for theming in the future
The names of the variables should be generic enough to accommodate different values for themes, such as light or dark mode.
If the name of the color is included in the variable, the naming convention will not be compatible with the other color names used in different modes:
Using Variable with Utility and Custom Classes
Variables work as a bridge between utility classes and custom classes. Both types of classes can derive their values from a variable to maintain consistency.
For example, the background-color-primary class gets its value from a variable present inside the "Background" group. However, if you want to apply a background color directly to a section instead of using a utility class, you can connect the section's background to the same variable the utility class is connected to. The same concept applies to font styles, layout spacing, and sizes.
By default, we recommend using utility classes where possible. That said, you can apply styles directly to a custom class and connect it to a variable as the second-best option, if your build demands it.
FAQ
[fs-toc-omit]Should I follow my client's color system and naming conventions?
Absolutely. If your client has an established style guide, it's best to adhere to their color system and naming conventions. This ensures consistency and aligns with their established branding standards.
[fs-toc-omit]What if the design file is a mess and there is no organized color system?
This is likely to happen frequently. Some designers or clients may not structure their colors well, and it becomes our job to organize them for a more structured project. To understand how to do this, check the sections Primitives and semantic tokens and Variable naming above.
[fs-toc-omit]Can I just use the color name for a semantic variable?
This is not recommended. If you name a variable simply by its color, any change in color schemes or themes would require renaming the token. The whole point of semantic tokens is to keep things flexible and easy to update. So, it's better to go with names that describe the variable's role, not just its color.