April 23, 2026By Alain Ngeukeu8 min read1771 words

Design Tokens in Tailwind v4, A Four-Layer System for Scalable Frontend Architecture

Introduction, Why Design Tokens Matter
The Four-Layer System for Tailwind v4
Layer 1, Raw Values (:root and .dark)
Layer 2, Semantic Registration (@theme)
Layer 3, Global Defaults (@layer base)
Layer 4, Scoped Tokens for Isolated Sections
How the Four Layers Work Together
Defining Design Tokens in Tailwind v4
Upgrading Existing Projects to Tailwind v4
Complete Example, A Full Token Architecture
How Components Consume Tokens
Why This System Scales Over Time
Conclusion

1. Introduction, Why Design Tokens Matter

Every frontend project begins simply. A few components are styled, a handful of colors are chosen, and spacing decisions are made quickly to move development forward. At first, this approach feels efficient. Over time, however, the same project often becomes harder to maintain. Colors are duplicated across files, border radii become inconsistent, dark mode requires scattered overrides, and redesigns become expensive because values are hardcoded throughout the codebase.

Design tokens solve this problem by turning visual decisions into reusable named values. Instead of writing raw colors directly in components, developers reference names such as background, foreground, or brand. Instead of repeating measurements, they rely on shared radius and spacing tokens. When the underlying token changes, every component using it updates automatically.

Tailwind v4 makes this model especially powerful because tokens can now live directly in CSS through the @theme system. That means the styling architecture becomes simpler, more centralized, and easier to reason about.

To make the most of this approach, it helps to organize tokens into a clear structure. The most practical system is a four-layer model where each layer has one responsibility and naturally builds on the previous one.

2. The Four-Layer System for Tailwind v4

A token system remains clean only when responsibilities are separated. If raw values, semantic names, global styles, and local overrides are mixed together, confusion returns quickly.

For that reason, Tailwind v4 works best when tokens are organized into four connected layers.

The first layer stores the raw design values such as colors, spacing, and radii. The second layer exposes those values to Tailwind using semantic names. The third layer applies sensible defaults across the application. The fourth layer allows isolated sections to introduce local variations without disturbing the global theme.

Each layer depends on the previous one. Raw values feed semantic names. Semantic names feed global defaults. Global defaults establish consistency, while scoped tokens provide controlled exceptions.

Once this flow is understood, each part of the system becomes easier to maintain. The natural starting point is the foundation itself, the raw values.

3. Layer 1, Raw Values (:root and .dark)

The first layer is where the actual design values live. This includes colors, radii, spacing units, shadows, and any other primitive values that define the visual language of the interface.

These values usually belong in :root for light mode and in .dark for dark mode.

:root {
  --background: #f8f9fa;
  --primary: #0a0a0a;
}

.dark {
  --background: #212529;
  --primary: #0a0a0a;
}

This layer should be the only place where raw color values such as hex or RGB are written directly. If a redesign happens later, this is where the changes belong.

Notice that these variables are still low-level. They define values, but they do not yet express purpose inside the application. To make them useful in components, they need meaningful names that Tailwind understands. That is the role of the second layer.

4. Layer 2, Semantic Registration (@theme)

Once raw values exist, the next step is to map them into semantic tokens. This happens inside the @theme block.

@theme inline {
  --color-background: var(--background);
  --color-primary: var(--primary);
  --radius-md: calc(var(--radius) - 2px);
}

This layer translates primitive values into names with intent. Instead of referencing #f8f9fa, developers use background. Instead of thinking about a specific dark gray, they use primary.

Tailwind reads these variables and automatically generates utility classes such as bg-background, text-primary, and rounded-md.

The inline keyword is especially useful because it preserves CSS variable resolution through the cascade. In practice, this means that when .dark changes a raw variable in Layer 1, the semantic token updates automatically without requiring any component changes.

Now that Tailwind understands the token system, the next logical step is to apply those tokens globally so the application starts from a consistent baseline.

5. Layer 3, Global Defaults (@layer base)

Once semantic tokens are available, they can be applied to the entire application through @layer base.

@layer base {
  body { @apply bg-background text-foreground; }
  * { @apply border-border outline-ring/50; }
  h1, h2, h3 { font-family: var(--font-heading); }
}

This layer removes repetition by defining shared defaults once. The body receives the correct page colors. Borders become consistent across elements. Headings inherit the intended typography system.

As a result, every page begins with a coherent visual foundation before any components are rendered. Developers no longer need to restate common decisions in each file.

However, not every part of a product should always look identical. Marketing sections, product showcases, and promotional blocks often need their own styling identity. That is where the fourth layer becomes useful.

6. Layer 4, Scoped Tokens for Isolated Sections

Some parts of an application need controlled visual independence. Instead of altering the global token system, those sections can define local tokens.

.my-section {
  --pe-bg: #f4f5f7;
  --pe-gold: #b8956a;
}

.dark .my-section {
  --pe-bg: #0f1116;
}

.pe-bg { background-color: var(--pe-bg); }

These variables exist only inside .my-section. They do not affect the rest of the application and do not pollute the global namespace.

This is ideal for product landing pages, temporary campaigns, or branded content areas that need distinct styling while the rest of the interface remains consistent.

With all four layers explained individually, it becomes easier to understand how they connect into one coherent system.

7. How the Four Layers Work Together

The strength of this model is not in any single layer, but in the sequence between them.

Layer 1 -> Raw values live here
Layer 2 -> Tailwind receives semantic names
Layer 3 -> Global defaults apply tokens
Layer 4 -> Local sections create exceptions

If a brand color changes, update Layer 1. If a new utility name is needed, update Layer 2. If headings should use a new font everywhere, update Layer 3. If one campaign page needs a gold accent palette, use Layer 4.

Because every responsibility has a home, styling decisions stay organized instead of becoming scattered.

Now that the conceptual model is clear, it helps to see how Tailwind v4 implements this directly in globals.css.

8. Defining Design Tokens in Tailwind v4

Tailwind v4 simplifies configuration by allowing token definitions directly inside CSS.

@import "tailwindcss";

@theme {
  --color-primary: #3B82F6;
  --color-background: #ffffff;
  --color-foreground: #0a0a0a;
  --color-muted: #6B7280;

  --font-sans: 'Inter', sans-serif;

  --radius-md: 8px;
  --radius-lg: 12px;
}

From these definitions, Tailwind automatically generates utility classes.

<button className="bg-primary text-background rounded-md">
  Submit
</button>

This means developers interact with a stable design vocabulary rather than raw CSS values.

For teams upgrading from older Tailwind versions, the next question is usually how to migrate existing projects.

9. Upgrading Existing Projects to Tailwind v4

Migration from Tailwind v3 to v4 is generally straightforward.

First, update the package:

npm install tailwindcss@latest

Then run the official upgrade tool:

npx @tailwindcss/upgrade

This process typically removes the old configuration structure, moves token definitions into CSS, and replaces earlier directives with:

@import "tailwindcss";

After the migration, review your styles carefully. Even successful upgrades should be tested visually to confirm spacing, colors, and utilities still behave as expected.

Once upgraded, the best way to structure the new project is with a complete token architecture.

10. Complete Example, A Full Token Architecture

@import "tailwindcss";

:root {
  --brand: rgb(37 99 235);
  --brand-fg: rgb(255 255 255);
  --bg: rgb(249 250 251);
  --fg: rgb(17 24 39);
  --surface: rgb(255 255 255);
  --muted: rgb(107 114 128);
  --border: rgb(229 231 235);
}

.dark {
  --brand: rgb(96 165 250);
  --bg: rgb(17 24 39);
  --fg: rgb(249 250 251);
  --surface: rgb(31 41 55);
  --muted: rgb(156 163 175);
  --border: rgb(55 65 81);
}

@theme inline {
  --color-brand: var(--brand);
  --color-brand-foreground: var(--brand-fg);
  --color-background: var(--bg);
  --color-foreground: var(--fg);
  --color-surface: var(--surface);
  --color-muted: var(--muted);
  --color-border: var(--border);

  --radius-card: 10px;
  --radius-button: 6px;
}

@layer base {
  body { @apply bg-background text-foreground; }
  * { @apply border-border box-border; }
}

This example demonstrates how the four layers combine into a maintainable system.

Once the architecture is in place, components become significantly cleaner.

11. How Components Consume Tokens

Components should use token names rather than raw values.

function Button({ children }) {
  return (
    <button className="bg-brand text-brand-foreground rounded-button px-4 py-2">
      {children}
    </button>
  )
}

function Card({ children }) {
  return (
    <div className="bg-surface border border-border rounded-card p-6">
      {children}
    </div>
  )
}

These components describe purpose rather than implementation. The button knows it uses the brand color, but it does not know the exact shade. The card knows it uses the surface token, but it does not care what that surface looks like in light or dark mode.

That separation is what makes redesigns efficient and safe.

As projects grow, this advantage becomes even more valuable.

12. Why This System Scales Over Time

Small projects can tolerate inconsistent styling for a while. Larger products cannot.

As teams grow, multiple developers add features simultaneously. Without a token system, each person introduces slightly different values. Over time, interfaces become visually fragmented.

A layered token architecture prevents that drift. New developers inherit a shared vocabulary. Rebrands happen centrally. Dark mode remains predictable. New sections can evolve independently without damaging the core design language.

Most importantly, the system continues to work as the codebase expands. What begins as a small styling convention becomes long-term operational leverage.

That is why tokens are not merely a design preference. They are an engineering advantage.

13. Conclusion

Design tokens in Tailwind v4 are most effective when treated as a structured system rather than a collection of variables.

By organizing raw values, semantic registration, global defaults, and scoped exceptions into a logical sequence, you create a frontend architecture that is easier to understand, easier to maintain, and easier to scale.

Components stay clean because they express intent. Redesigns become simpler because values are centralized. Dark mode becomes elegant because it relies on inheritance instead of duplication.

The strongest frontend systems are rarely the most complex. They are the ones built on clear rules, applied consistently over time.

Alain Ngongang

Table of Contents