Tailwind v4 Design Tokens: From Hardcoded Classes to a Semantic System

Tailwind makes it easy to move fast. That speed can also create a codebase full of one-off UI decisions.

Hardcoded classes like text-[#181616], p-[18px], and text-[15px] solve the screen in front of you. They do not create a system. Tailwind v4 works best when teams pair utilities with semantic design tokens that explain intent.

Vois helps teams turn Tailwind values, Figma Variables, and CSS variables into one semantic system.

What changes with Tailwind v4 design tokens?

Tailwind v4 is CSS-first. The @theme directive and CSS variables make it easier to define design tokens close to the styles that use them.

That means teams can move from this:

text-[#181616] bg-[#f7f5f2] p-[18px]

To this:

text-foreground bg-background p-4

The second version is easier for humans to review and easier for AI agents to reuse.

Why are hardcoded Tailwind values a problem?

Hardcoded values are not always wrong. They are risky when they become the default.

They create several problems:

• Designers cannot tell which values are approved.
• Engineers cannot update a value across the app safely.
• Dark mode becomes harder because raw values miss semantic intent.
• AI coding agents copy one-off classes into new components.
• Code review turns into visual taste review instead of system review.

A semantic token gives the value a job.

What is a semantic token?

A semantic token names why a value exists.

Examples:

• --color-background
• --color-foreground
• --color-muted
• --color-border
• --type-body-default-size
• --radius-card

The raw value can change. The role stays stable. That is what makes a design system maintainable.

How should Tailwind teams organize tokens?

Start with roles that map to product UI, not color names alone.

Useful groups include:

1. Surface tokens for backgrounds, cards, popovers, and elevated panels.
2. Text tokens for foreground, muted copy, links, and destructive states.
3. Border tokens for default, strong, focus, and input borders.
4. Spacing tokens that follow the 8 pt grid.
5. Typography tokens for page headings, section headings, labels, captions, and body text.
6. Motion tokens for durations and easing.

This gives your team reusable decisions instead of reusable numbers.

How does Vois fit a Tailwind v4 workflow?

Vois helps teams create and enforce the token layer around Tailwind.

You can use Vois to:

• Import Figma Variables.
• Map raw values to semantic roles.
• Generate CSS variables for Tailwind v4.
• Audit hardcoded values in component files.
• Suggest token-safe fixes.
• Give AI coding agents token context through MCP.

Tailwind remains the implementation language. Vois keeps the design decisions consistent.

What should teams migrate first?

Start where drift is most visible.

1. Replace repeated hex colors with semantic color tokens.
2. Replace one-off spacing with the closest 4 pt or 8 pt value.
3. Map typography to a small set of text roles.
4. Audit dark mode gaps.
5. Add token checks before large UI refactors.

Do not start by naming every possible value. Start by replacing the values your team already repeats.

What does success look like?

Success is not a perfect token spreadsheet.

Success is a workflow where a designer can update intent, an engineer can review the code change, and an AI agent can build a component without inventing new visual rules.

That is the system Tailwind v4 makes possible. Vois helps teams maintain it.

Start with Vois

Use Vois to turn Tailwind v4, CSS variables, and Figma Variables into one semantic design token system.

Start with Vois