Exploring Typesafe design tokens in Tailwind 4

Tailwind 4 has been on the horizon for a while, with the team first open-sourcing their progress in March 2024. One of the most noteworthy changes, in my opinion, is the shift from a JavaScript-based configuration to a CSS-based one. Tailwind 4 is currently in beta, and from what I gather, the team is still dealing with some challenges, especially with Safari compatibility.

NOTE: Later in the article, we'll assume you're using a component-based framework / library, but the concepts discussed are easily transferable to other approaches.

Changes in Tailwind 4

The move to a CSS config

I've heard some complaints about this, especially from TypeScript users. However, the roadmap for Tailwind 4.0 does include support for the classic tailwind.config.js as its top priority:

Support for JavaScript configuration files — reintroducing compatibility with the classic tailwind.config.js file to make migrating to v4 easy.

That said, it seems like this is intended primarily for migration purposes and may not be a sustainable long-term solution.

What does this mean for Typesafety

Under the hood Tailwind 4 uses the new @property CSS rules to to define internal custom properties.

We use @property to define our internal custom properties with proper types and constraints

As it stands I'm unable to find decent syntax highlighting support for @property rules in VS code, I have reached out on Bluesky to see if anyone has had more luck than me.

I'm hoping better @property support can aide us in future, more on that later.

What is the @property CSS rule

The @property rule represents a custom property registration directly in a stylesheet without having to run any JavaScript. Valid @property rules result in a registered custom property, which is similar to calling registerProperty() with equivalent parameters.

What are design tokens

Now that we've covered the upcoming changes in Tailwind 4 and their potential impact, let's take a moment to talk about design tokens. If you're not familiar with the term, here's a quick explanation: Design tokens are a method of storing and managing design decisions in a consistent, reusable format, typically as variables. They represent key visual properties of a design system, like colours, typography, spacing, shadows, in a structured way. The goal is to centralise these design values so they can be easily updated, maintained, and shared across different platforms and tools.

Design systems are typically made up of two main types of values: System values and Component values. For example, your system values might look something like this:

const SYSTEM_TOKENS: ISystemTokens = {
  /* ... */
  COLORS: {
    /* ... */
    GREEN: {
      LIGHT: "#E0E5D9",
      MEDIUM: "#3F6212",
      DARK: "#28331A",
    }
    /* ... */
  },
  TYPOGRAPHY: {
    /* ... */
  }
  /* ... */
}

You can then reference your system values within your component tokens like this:

import { SYSTEM_TOKENS } from "...";

const BUTTON_VALUES: IButtonTokens = {
  /* ... */
  COLORS: {
    /* ... */
    BACKGROUND: SYSTEM_TOKENS.COLORS.GREEN.DARK,
    /* ... */
  },
  TYPOGRAPHY: {
    /* ... */
  }
  /* ... */
}

If you're interested in learning more about design systems, it's worth exploring well-known systems likeMaterial Design.

Structuring component design tokens with Tailwind

About a week ago, I wrote an article discussing an alternative approach I’ve been using for creating component variants with Tailwind CSS. In brief, the article explores how we can leverage CSS variables alongside Tailwind to manage complex variants, setting variant values inline through dynamic component props and variable mapping. If you're curious about how I arrived at this approach, you can read more about it here: A different approach to writing component variants with Tailwind CSS.

We should start by identifying the parts of our component that depend on design tokens. As mentioned earlier, this will include colors, typography, spacing, and any other fixed system values that are integral to your design. Let's take a look at the following Button component, without design tokens:

<button class="p-4 bg-red text-white rounded-lg relative flex justify-center">Click me</button>

In the example above, we can pinpoint several values that can be tokenized. Each of the following classes could correspond to a value in our design system:

• p-4
• bg-red
• text-white

Now that we've identified the values that can be tokenised, we can categorise them into two groups: static values and dynamic values. Static values are those in your component that remain constant, while dynamic values are those that can change based on the props passed to the component. For our example we'll make the padding (p-4) static, while the text colour (text-white) and background (bg-red) should be set dynamically via a theme prop.

Creating the tokens

Tailwind 4 config

First we need to define our System tokens in the new Tailwind CSS config:

@import "tailwindcss";

@theme {
  --color-white: #FFFFFF;
  --color-green-light: #E0E5D9;
  --color-green-medium: #3F6212;
  --color-green-dark: #28331A;
  --color-red-light: #F4CCCC;
  --color-red-medium: #D50000;
  --color-red-dark: #640000;

  --spacing-sm: 1rem;
  --spacing-md: 2rem;
}

System tokens

Next we need to create our system.tokens.ts file:

export type TColor = "--color-white" | "--color-green-light" | "--color-green-medium" | "--color-green-dark" | "--color-red-light" | "--color-red-medium" | "--color-red-dark";

export type TSpacing = "--spacing-sm" | "--spacing-md";


interface ISystemTokens {
  COLORS: {
    WHITE: TColor;
    GREEN: {
      LIGHT: TColor;
      MEDIUM: TColor;
      DARK: TColor;
    },
    RED: {
      LIGHT: TColor;
      MEDIUM: TColor;
      DARK: TColor;
    }
  },
  SPACING: {
    SMALL: TSpacing;
    MEDIUM: TSpacing;
  }
}

export const  SYSTEM_TOKENS: ISystemTokens {
  COLORS: {
    WHITE: "--color-white";
    GREEN: {
      LIGHT: "--color-green-light";
      MEDIUM: "--color-green-light";
      DARK: "--color-green-light";
    },
    RED: {
      LIGHT: "--color-red-light";
      MEDIUM: "--color-red-medium";
      DARK: "--color-red-dark";
    }
  },
  SPACING: {
    SMALL: "--spacing-sm";
    MEDIUM: "--spacing-md";
  }
}

System design tokens can be referenced in designs like so:
$system.COLORS.GREEN.LIGHT.

In an ideal world, we could directly export types from our CSS file’s @property rules into our TColor and TSpacing types, much like how SCSS imports can be transformed into JavaScript. Unfortunately, as of now, to the best of my knowledge, this isn't possible.

Component tokens

Now that we’ve implemented our system tokens, we can start integrating them into our components. The first step is to set up our <Component>.tokens.ts file. To illustrate this, let’s take the example of the Button component we looked at earlier, and create a corresponding Button.tokens.ts file.

To recap, here’s how our Button component was structured:

<button class="p-4 bg-red text-white rounded-lg relative flex justify-center">Click me</button>

Earlier, we discussed the distinction between static values (like p-4) and dynamic values (like bg-red and text-white). This distinction will guide how we organise our design tokens. Static properties, like p-4, should be grouped under STATIC, while dynamic properties, like bg-red and text-white, should be grouped under the appropriate prop identifier. In this case, since we’re controlling bg-red and text-white through a theme prop, they should be placed under the THEME section in our tokens file. For our example we'll assume 2 theme variables - PRIMARY and SECONDARY.

import { SYSTEM_TOKENS, TColor, TSpacing } from "./system.tokens.ts";
import { TTheme } from "./Button"; // PRIMARY, SECONDARY

interface IButtonStaticTokens {
  padding: TSpacing;
}

interface IButtonThemeTokens {
  backgroundColor: TColor;
  textColor: TColor;
}

export const STATIC: IButtonStaticTokens {
  padding: "--spacing-sm";
}

export const THEME: IButtonStaticTokens {
  PRIMARY: {
    backgroundColor: "--color-red-dark";
    textColor: "--color-red-light";
  },
  SECONDARY: {
    backgroundColor: "--color-green-dark";
    textColor: "--color-green-light";
  };
}

Component design tokens can be referenced in designs like so: $component.Button.THEME.PRIMARY.backgroundColor. My preference for naming conventions is to use:
$component.<ComponentName>.<PROP_NAME><PROP_VALUE>.tokenName

$component: Differentiate between $system and $component tokens
<ComponentName>: Follow internal file naming convention for components
PROP_NAME: Constant case
PROP_VALUE: Should follow internal prop value casing
Token name (backgroundColor): Camel case*

This is ultimately a matter of personal preference, and it's up to you to decide what works best for your workflow.

• When naming tokens, I slightly deviate from Camel case if I need to specify a token for an element's state, such as :hover. In those cases, I prefix the token name with the state followed by two underscores, like so: hover__backgroundColor.

Using design tokens in components

As I mentioned earlier in the article, I previously wrote about exploringa different approach to writing component variants with Tailwind CSS. I'll be referencing that approach here, so if you haven't read it yet, it might be helpful to check it out first to understand the context behind this method.

This part of the article will assume you are using a Javascript framework or library to build your components.

Updating the Button component

We need to replace the existing tokenisable classes with Tailwind classes powered by css variables. Note the variable names match those in our 2 Button component token interfaces, IButtonStaticTokens and IButtonThemeTokens;

<button class="p-[--padding] bg-[--backgroundColor] text-[--textColor] rounded-lg relative flex justify-center">Click me</button>

Now that we've updated our classes, we need to dynamically apply the component styles and update the variables. To achieve this, we'll use a variableMap function on the component. Essentially, this function maps our tokens from Button.tokens.ts to inline CSS variables directly on the component, which our classes can then reference. For an example of a variable map please see the end of this article.

<template>
  <button
    :style="[variableMap(STATIC), variableMap(THEME[props.THEME])]"
    class="p-[--padding] bg-[--backgroundColor] text-[--textColor] 
    rounded-lg relative flex justify-center"
  >
    Click me
  </button>
</template>
<script setup lang="ts">
import { variableMap } from "...";
import { STATIC, THEME } from "Button.tokens.ts";

const props = /*THEME*/
</script>

Conclusion

I'm looking forward to the release of Tailwind 4 and what changes the team make between now and then. I've enjoyed experimenting with ideas to deal with some of the challenges around design tokens, variants and typesafety.

This is an experimental approach on which I'm sure there will be some strong opinions.

If you've found this article interesting or useful, please follow me on Bluesky (I'm most active here), Medium, Dev and/ or Twitter.