Variables

Primitives

Primitives are raw values that form your brand’s aesthetics. Each primitive variable is named to describe the visual appearance of the value, rather than how it should be used. These variables do not have any meaning or context attached to them. Rather, they are low-level style values meant to be referenced by semantic variables.

Semantics

Semantics are variables that have a specific purpose and context. Each semantic variable is named to describe how it should be used, like “Primary Text” or “Card Border”, rather than the visual appearance of their values. These variables can use a raw value, but when multiple semantic variables have the same value, they should reference a shared primitive variable.

When to use a
variable mode

• Specific breakpoint values
• Light or dark color schemes
• Different site, page, or section themes unique to your brand and sub-brands
• Experimentation with different design treatments as part of a Webflow Optimize variation. Note: you’ll need to create your new variable modes before setting up a variation.

You may also pair variable modes with custom code to automatically support:

• Site visitor preferences for light, dark, or device color schemes
• Contrast, motion, or transparency preferences
• Device orientation and other characteristics

You can manually apply variable modes to any selector in the Style panel, or apply them automatically for specific breakpoints.

When not to use a variable mode

If you have a design token that never needs to change its value based on the context it’s in, don’t create a mode for that. A good test is: do you need to return to a selector or element and sometimes relink one of its style properties to a different value? That’s a good use case for a mode value.

If you need element or component-specific values, this is a better use case for variable groups, rather than modes.

Naming principles

Variable names follow these conventions as a best practice:

We recommend that variable names use title casing with words separated by a space. This ensures that variable names are human-readable, empowering everyone on your cross-functional team to contribute.

There are two most-common practices for naming size primitives: number-based steps, and t-shirt-based sizes. Whether you choose to adopt one of these common practices or another naming schema, the most important tenet is consistency.

Use the group name, such as Size/ or Spacing/, to indicate the purpose of the sizing ramp (e.g. spacing, type sizes, line heights). Use 1-based numbers to create a clear scale from smallest to largest value. You may also choose to use 100-based numbers if you’d like to match nomenclature for your color primitives.

The values of these variables should follow your visual language’s needs. In the absence of clear brand requirements, you could choose to scale each step by roughly the same multiplier, e.g. ×1.25 or ×1.5. Smaller multipliers between steps give you more flexibility but less control over consistent use; larger steps can encourage more intentional and consistent design choices but with less flexibility.

For a simpler sizing system: use the group name, such as Size/ or Spacing/, to indicate the purpose of the sizing ramp (e.g. spacing, type sizes, line heights). Use human-readable size abbreviations from smallest to largest to indicate relative size:

The guidance here differs from color ramp best practices. Sizing—particularly spacing and type size ramps—are more vulnerable to drift, clutter, and lack of rigor in enforcing a small set of consistent values. Define your size ramps carefully and commit to them.

Use a keyword describing the font-family’s frequency of use or role within your brand.

• Element
  If you need to reference a nested element, such as a button within a card, start from the parent or containing element, ending with the child, such as: Card Button
• Element variant identifiers if relevant
  If this is a primary button: Card Button Primary
• Property
  For example a background color: Card Button Primary BG
• Modifiers if relevant
  Like the element state: Card Button Primary BG Hover

Webflow enables you to organize variables into collections and groups.

• Use collections for the foundations of a design system.
• Rename the default collection to its purpose. Consider storing primitive variables here and naming the collection “Primitives”.
• Organize variables within a collection using groups. Variables should be grouped by “like” purpose:
  
  • Primitives: type, spacing, or color ramps (if not already placing primitives in the default collection)
  • Semantics: design-context-specific uses for variables
• Order variables within primitive groups from least to greatest values: smallest to largest size, lightest to darkest color
• Define auto variable modes in order of breakpoint: base mode followed by tablet, mobile landscape, and mobile portrait
• Define manual variable modes by specificity of use or frequency of use in your brand. For example: default (equivalent to light scheme), dark scheme, high contrast light, high contrast dark.

When working with custom code, Webflow variables are available as CSS custom properties — often called “CSS variables” — allowing you to easily extend beyond native styling.

The Variables panel in Webflow enables you to “copy CSS” for a variable. This can then be used in code blocks for custom CSS, SVG strokes and fills, and other styling needs specific to your brand and sites. This is a scalable approach to custom code as your CSS will pick up any value changes made to your variables.

Notes on variable naming in CSS:

• The variable name is converted to a lowercase-dash-separated string.
• The name is prefixed with the group, collection, and Library name, if applicable.
• If the variable name, group, or collection changes, you will need to update any references in custom code.