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 .

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: . 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 (I'm most active here), and/ or Twitter.