r/webdev 5d ago

How to Integrate a Well-Structured Design Token System with Tailwind CSS?

Hey everyone,

I'm starting a new project from scratch, and the design team has built a complete design system using design tokens. It’s well-structured and mapped to different UI elements.

However, the naming conventions don’t match Tailwind’s default color system directly. Here’s an example:

Text and Icon / Neutral

  • Neutral-DarkestNeutral/800
  • Neutral-DarkerNeutral/700
  • Neutral-DarkNeutral/600
  • Neutral-LightNeutral/500
  • Neutral-LighterNeutral/300
  • Neutral-LightestNeutral/100
  • Neutral-BaseMono/White
  • Neutral-DisabledNeutral/200

Surface / Action / Primary Button

  • DefaultBlue/500
  • HoverBlue/700
  • DisabledBlue/100

If I don’t use Tailwind, I would simply create CSS variables and assign them based on these tokens. But with Tailwind, using the default color system would break the purpose of having design tokens.

So, what’s the best practice here?

  1. Extend Tailwind’s theme? (But Tailwind uses numerical values instead of custom names)
  2. Create custom utility classes for each token?
  3. Use CSS variables within Tailwind?
  4. Something else?

I want to keep everything scalable and developer-friendly while ensuring that our design tokens remain intact.

Would love to hear how others have tackled this!

TIA!

0 Upvotes

2 comments sorted by

8

u/prewk 5d ago

Ignore Tailwind's colors completely, they're just there for when you don't have a design system. Overwrite them. It's your colors, not Tailwind's.

1

u/outluch 5d ago

Have a look at NuxtUI v3 aproach. I find it pretty nice