Master of the universe

CSS Tokens And Variables - Make Your Web Designs Scalable (And Flexible)


In the world of web development, having scalable and flexible designs is essential for creating websites that can adapt to various devices, screen sizes, and user preferences. One of the tools that can help achieve this is the use of CSS tokens and variables. This article will provide an in-depth look at CSS tokens and variables, their benefits, and how to properly implement them in your projects. By the end of this article, you'll have a deep understanding of these powerful features and how they can make your web designs more scalable and flexible.

Understanding CSS Tokens and Variables

What are CSS Variables?

CSS variables, also known as CSS custom properties, allow developers to store values that can be reused throughout a stylesheet. They make it easy to update values in one place without having to search and replace multiple instances of the same value. The basic syntax for declaring a CSS variable is as follows:

:root {
  --variable-name: value;

And to use the variable in a style rule, you can reference it using the var() function:

selector {
  property: var(--variable-name);

What are CSS Tokens?

CSS tokens are a concept that goes a step further than CSS variables. While variables allow you to store and reuse values, tokens focus on abstracting design decisions into meaningful and reusable tokens. The idea is to define a set of named tokens that represent design decisions (such as colors, font sizes, or spacing units) and use them throughout your project. This creates a consistent and maintainable styling system that can be easily updated and scaled.

While CSS does not have built-in support for tokens, you can use tools like Style Dictionary or Theo to manage and generate tokens as CSS variables, making it easier to work with them in your stylesheets.

Benefits of Using CSS Tokens and Variables

There are several benefits to using CSS tokens and variables in your projects:

  • Versatility and reusability: Variables and tokens can be reused throughout your stylesheets, making it simpler to maintain consistency and make updates.
  • Easier maintenance and updates: Changing a single variable or token value can update multiple instances of that value in your stylesheets.
  • Improved readability and organization: Using meaningful names for variables and tokens can make your stylesheets more readable and easier to understand.
  • Faster development time: By reusing variables and tokens, you can reduce the amount of repetitive code, making your development process more efficient.

Implementing CSS Variables

Declaring and Using CSS Variables

To declare a CSS variable, you need to specify a custom property with a double hyphen (--) followed by the variable name. You can set the variable's value and scope by declaring it within a selector. For example, to declare a global variable, you can use the :root selector:

:root {
  --primary-color: #1e90ff;

To use the variable in a style rule, you can reference it using the var() function:

button {
  background-color: var(--primary-color);

Variables declared within a specific selector have a local scope and are only accessible within that selector or its descendants:

.container {
  --container-padding: 16px;

.container > .item {
  padding: var(--container-padding);

Working with Fallback Values

In cases where a variable may not be defined or supported, you can provide a fallback value using the second argument of the var() function:

button {
  background-color: var(--primary-color, #1e90ff);

This ensures that if the --primary-color variable is not defined or supported, the button's background color will default to #1e90ff.

Implementing CSS Tokens

Defining and Applying CSS Tokens

As mentioned earlier, you can use tools like Style Dictionary or Theo to manage and generate tokens as CSS variables. Here's an example of defining tokens using Style Dictionary:

  "color": {
    "primary": {
      "value": "#1e90ff"
    "secondary": {
      "value": "#ff7f50"
  "spacing": {
    "small": {
      "value": "8px"
    "medium": {
      "value": "16px"
    "large": {
      "value": "24px"

This JSON file defines a set of color and spacing tokens. Style Dictionary can then generate a CSS file with the corresponding variables, which you can use in your stylesheets:

:root {
  --color-primary: #1e90ff;
  --color-secondary: #ff7f50;
  --spacing-small: 8px;
   --spacing-medium: 16px;
  --spacing-large: 24px;

/* Using tokens */
button {
  background-color: var(--color-primary);
  padding: var(--spacing-small) var(--spacing-medium);

Creating Responsive Designs with CSS Tokens

CSS tokens can be used to create responsive designs by adjusting token values based on media queries. For example, you can create fluid typography by defining font size tokens and updating them for different screen sizes:

:root {
  --font-size-small: 14px;
  --font-size-medium: 18px;
  --font-size-large: 24px;

@media (min-width: 768px) {
  :root {
    --font-size-small: 16px;
    --font-size-medium: 20px;
    --font-size-large: 28px;

/* Using font-size tokens */
body {
  font-size: var(--font-size-medium);

Similarly, you can use tokens to manage spacing and layouts, as well as create responsive color schemes.

Best Practices and Tips

  • Organize and name variables and tokens: Use a consistent naming convention and organize your variables and tokens in a way that makes them easy to find and understand. This can include categorizing tokens by type (e.g., colors, font sizes, spacing) and using a naming convention like BEM or ITCSS.
  • Leverage CSS preprocessors: If you're using a CSS preprocessor like Sass or Less, you can leverage their features to work with variables and tokens more efficiently. This can include using nested variables or mixins to simplify your stylesheets.
  • Browser compatibility and graceful degradation: While CSS variables are widely supported in modern browsers, older browsers like Internet Explorer don't support them. Make sure to test your styles in different browsers and provide fallbacks or alternative styles for unsupported features.

Common Mistakes to Avoid

  • Incorrect syntax and naming conventions: Ensure that you're using the correct syntax for declaring and using variables and tokens, and follow a consistent naming convention throughout your project.
  • Overusing global variables and tokens: While global variables and tokens can be useful for defining values that are used across your entire project, overusing them can make your stylesheets harder to maintain and less flexible. Use local variables and tokens when appropriate to keep your styles modular and maintainable.
  • Lack of planning and organization: Before diving into implementing variables and tokens, take the time to plan out your design system and consider how you want to organize and categorize your tokens. This will make it easier to maintain and scale your styles as your project grows.
  • Ignoring accessibility considerations: When defining and using tokens, keep accessibility in mind to ensure that your designs are usable by all users. This can include using sufficient color contrast, flexible font sizes, and adequate spacing between elements.

Testing Compatibility Across Different Browsers

Cross-browser compatibility is important to ensure that your designs look and function as expected in different browsers and devices. To test compatibility, you can use tools like BrowserStack or Sauce Labs to run your stylesheets in various browsers and devices.

When working with CSS variables and tokens, you may need to provide fallback styles for older browsers that don't support these features. This can be achieved through strategies like graceful degradation (providing an acceptable baseline experience for older browsers) or progressive enhancement (building up from a basic experience and adding enhancements for newer browsers).

Real-World Examples

  • CSS tokens in design systems: Many design systems, like Material-UI or Tailwind CSS, use tokens to manage and distribute design decisions across projects.
  • Implementing dark mode with variables: By using CSS variables to define colors, you can easily implement dark mode by updating the values of these variables based on user preferences or system settings. Check out this guide on implementing dark mode with CSS variables.
  • Component-based design using tokens and variables: When building components for a library or design system, using tokens and variables can help ensure consistency and reusability across different components and projects.


CSS tokens and variables are powerful tools for creating scalable and flexible web designs. By understanding their benefits, how to implement them, and following best practices, you can create a maintainable and adaptable styling system for your projects. With this knowledge, you'll be well-equipped to explore and experiment with CSS tokens and variables in your own work.

Frequently Asked Questions

Can I use CSS variables and tokens in inline styles?

While CSS variables can be used in inline styles, there are some limitations. You cannot declare a CSS variable within an inline style, but you can reference existing variables that have been declared elsewhere in your stylesheets:

<!-- This will NOT work -->
<div style="--primary-color: #1e90ff; background-color: var(--primary-color);">Hello, world!</div>

<!-- This will work if --primary-color has been declared in a stylesheet -->
<div style="background-color: var(--primary-color);">Hello, world!</div>

CSS tokens, on the other hand, are an abstraction that relies on tools like Style Dictionary or Theo to generate CSS variables. Therefore, they're not meant to be used directly in inline styles.

Can I use CSS variables with CSS preprocessors like Sass or Less?

Yes, you can use CSS variables alongside preprocessor variables in Sass or Less. However, it's important to note that there are differences between the two. Preprocessor variables are compiled into CSS during the build process, while CSS variables are resolved by the browser at runtime.

Using CSS variables in conjunction with preprocessor variables can provide additional flexibility and dynamic styling capabilities. For example, you can use Sass variables for static values and CSS variables for dynamic or themeable properties:

$base-color: #1e90ff;

:root {
  --primary-color: $base-color;
  --secondary-color: darken($base-color, 20%);

button {
  background-color: var(--primary-color);
  border-color: var(--secondary-color);

How can I use CSS variables with JavaScript?

You can use JavaScript to interact with CSS variables, making it possible to create dynamic styling based on user input, preferences, or other factors. To get the value of a CSS variable, you can use the getComputedStyle() method:

const element = document.querySelector('.some-element');
const primaryColor = getComputedStyle(element).getPropertyValue('--primary-color');

To set the value of a CSS variable, you can use the setProperty() method:

const element = document.querySelector('.some-element');'--primary-color', '#ff7f50');

Can I use CSS variables in pseudo-elements and pseudo-classes?

Yes, CSS variables can be used with pseudo-elements and pseudo-classes, just like any other CSS property. For example, you can use variables to style ::before and ::after pseudo-elements or to create custom hover effects:

:root {
  --primary-color: #1e90ff;
  --hover-color: #ff7f50;

button::before {
  content: '';
  background-color: var(--primary-color);

button:hover {
  background-color: var(--hover-color);

Do CSS variables impact performance?

CSS variables have minimal impact on performance, especially in modern browsers. While there may be a slight performance overhead compared to using static values, the benefits of using variables in terms of maintainability, scalability, and flexibility generally outweigh any potential performance concerns.

However, it's important to use CSS variables judiciously and avoid unnecessary complexity in your stylesheets. For example, avoid using a large number of nested variables or creating circular dependencies, as these can make your stylesheets harder to maintain and understand.

Sign up for the Artisan Beta

Help us reimagine WordPress.

Whether you’re a smaller site seeking to optimize performance, or mid-market/enterprise buildinging out a secure WordPress architecture – we’ve got you covered. 

We care about the protection of your data. Read our Privacy Policy.