Prevent collisions between utility classes generated by Tailwind

[ChucKN0risK]

Context

Specify aims to streamline the delivery of design tokens over many sources and destinations. Our approach is to provide maximum flexibility for our users to configure their own pipelines.

TailwindCSS is a utility-first CSS framework that provides a large panel of utility classes to avoid writing your own CSS. Tailwind's configuration allows a deep level of customisation.

Thus, Specify can provide tokens to be included into the Tailwind's default theme. Nevertheless, Tailwind's approach to tokens declaration is opinionated and requires well thought naming conventions.

Let's take an example using our main source: Figma.

Let's consider you define a shape with some border and radius:

By defining such a simple artefact, we already imply various tokens to Tailwind:

• border-style: solid
• border-width: 3px
• border-color: #3760C9
• border-radius: 5px

For that matter, Specify uses the name of the shape/layer (border-primary in that case) to name border design tokens. This will create a .border-primary CSS class within a default CSS context.

However, Tailwind treats each token as a separated category and apply some magic to generate many utilities classes to ease the development process.

Tailwind "explodes" composite design tokens to create individual design tokens used in utility classes.

Let's have a look at the Tailwind theme configuration generated by the Specify to-tailwind parser:

{
    colors: {
        "border-primary": "#3760C9",
    },
    borderWidth: {
        "border-primary": "3px",
    },
    borderRadius: {
        "border-primary": "5px",
    }
}

Which will get parsed by Tailwind as:

.text-border-primary {
    --tw-text-opacity: 1;
    color: rgba(55, 96, 201, var(--tw-text-opacity));
}
.bg-border-primary {
    --tw-bg-opacity: 1;
    background-color: rgba(55, 96, 201, var(--tw-bg-opacity));
}
.border-border-primary {
    border-width: 3px;
    --tw-border-opacity: 1;
    border-color: rgba(55, 96, 201, var(--tw-border-opacity));
}
.rounded-border-primary {
    border-radius: 5px;
}

🤯 What happened here?

A bit of Tailwind first. The colors key used by Tailwind generates 3 types of utility classes:

1. text for the color CSS property
2. bg for the background-color CSS property
3. border for the border-color CSS property

In our case, both the colors and borderWidth share the same name: border-primary. Tailwind interprets it as an intent for factoring those two values within the same scope: .border-border-primary.

Hence, the border-width and border-color are not accessible independently through CSS classes.

Because we're dealing with divergent ways of conceiving how configuration must be generated (Figma) and how it must be implemented for a framework to work (Tailwind), there isn't any one-size-fits-all solution.

Our solution: extend the to-tailwind parser configuration

If we can't impact nor on Figma, nor on Tailwind directly, we can still expose a configuration for users to set up their desired overrides.

We would add a renameKeys map to provide a pattern replacement feature for each key of the Tailwind theme.

Example:

{
	"name": "to-tailwind",
	"options": {
		"renameKeys": {
			"colors": "color-{{name}}",
			"borderWidth": "bw-{{name}}"
		}
	}
}

Where {{name}} refers to the name of your design token coming from Specify.

Therefore, the parser would generate:

{
	colors: {
	  "color-border-primary": "#3760C9",
	},
	borderWidth: {
	  "bw-border-primary": "3px",
	},
	borderRadius: {
	  "border-primary": "5px",
	}
}

Which will get parsed by Tailwind as:

.text-color-border-primary {
    --tw-text-opacity: 1;
    color: rgba(55, 96, 201, var(--tw-text-opacity));
}
.bg-color-border-primary {
    --tw-bg-opacity: 1;
    background-color: rgba(55, 96, 201, var(--tw-bg-opacity));
}
.border-color-border-primary {
    --tw-border-opacity: 1;
    border-color: rgba(55, 96, 201, var(--tw-border-opacity));
}
.border-bw-border-primary {
    border-width: 3px;
}
.rounded-border-primary {
    border-radius: 5px;
}

Resources

• https://tailwindcss.com/docs/theme#core-plugins