Design Tokens vs Atomic CSS: A Failed Integration and the Path to Harmony

A personal developer's attempt to map design tokens to UnoCSS failed the same day. But it resulted in a set of pragmatic boundaries.

This article covers: quantified comparison between design tokens and atomic CSS, the real configuration of the failed UnoCSS mapping, pragmatic boundaries between CSS variables and atomic tools, and when to abandon atomic CSS.

I. Starting Point: I Have a Complete Design Token System

My personal project moongate-vue started with just three CSS files:

• colors.css : Light/dark dual theme, 40+ semantic color variables (--ui-primary, --ui-bg-muted...)
• layout.css : Layout tokens for spacing, radius, shadow, animation, typography, breakpoints
• main.css : Global component styles

This token system doesn't depend on any framework. Any component can access design constraints through var(--ui-spacing-md), var(--ui-primary). It's stable, intuitive, and maintainable — the foundation of my entire component library.

II. The Temptation: UnoCSS Lightweight and Atomic

I had heard about Tailwind's "heaviness", but UnoCSS promised on-demand generation, zero runtime, ultra-lightweight. As a solo developer, I longed for the "no need to write CSS class names" experience — just stack flex p-4 text-center directly in templates, no file switching, no naming headaches.

So one night I decided: map the design tokens to UnoCSS, preserving the design system while enjoying atomic writing.

III. The Collision: One Night of Struggle (With Real Config)

I wrote uno.config.ts, trying to map each --ui-* variable to an atomic class. Here's the failing configuration:

// uno.config.ts (failed version)
import { defineConfig } from 'unocss'

export default defineConfig({
  theme: {
    colors: {
      primary: 'var(--ui-primary)',
      success: 'var(--ui-success)',
      warning: 'var(--ui-warning)',
      error: 'var(--ui-error)',
      'bg-muted': 'var(--ui-bg-muted)',
      'border-subtle': 'var(--ui-border-subtle)',
      // 40+ variables need mapping...
    },
    spacing: {
      sm: 'var(--ui-spacing-sm)',
      md: 'var(--ui-spacing-md)',
      lg: 'var(--ui-spacing-lg)',
      xl: 'var(--ui-spacing-xl)',
    },
    borderRadius: {
      none: 'var(--ui-radius-none)',
      sm: 'var(--ui-radius-sm)',
      md: 'var(--ui-radius-md)',
      lg: 'var(--ui-radius-lg)',
    }
  },
  shortcuts: {
    'btn': 'px-4 py-2 rounded',
    'btn-primary': 'btn bg-primary text-white'
  }
})

Then in Button.vue, I replaced all scoped styles with atomic classes:

<!-- Button.vue after refactor (failed attempt) -->
<button :class="cn('bg-primary text-white', 'bg-bg-muted', 'border-border-subtle')">

Problems quickly emerged:

• Redundant and non-semantic class names : bg-bg-muted, border-border-subtle — reads like stuttering
• High mapping maintenance cost : Change a CSS variable in one place, update the UnoCSS config in another — single source of truth becomes two
• Conditional logic explosion : Handling neutral color required color === 'neutral' ? 'text-dim' : 'text-'+color
• Difficult debugging : Seeing bg-bg-muted in the browser means reverse-looking up which CSS variable it corresponds to
• No IDE autocomplete : UnoCSS's type generation can't automatically cover my custom variable names

I deleted all mapping code that night and returned to the original solution.

IV. Epiphany: Design Tokens Are the Lightest Atomic Framework

Looking at bg-bg-muted, I suddenly asked myself: Why not just write background-color: var(--ui-bg-muted) directly?

My design token system already provides all the design constraints. The only value UnoCSS adds is "fast writing" — syntactic sugar.

Deeper still: mapping --ui-primary to bg-primary is essentially "wrapping CSS with CSS". UnoCSS generates .bg-primary { background-color: var(--ui-primary); } at compile time. If that's the final CSS, isn't writing it directly in scoped styles more straightforward?

V. Quantified Comparison: Pure Design Tokens vs UnoCSS Mapping

To objectively judge how "not worth it" it really is, I compiled this table (based on my project measurements):

Metric	Pure Design Tokens (final)	UnoCSS Mapping (abandoned)
Number of CSS variables	40+	40+ (unchanged)
Extra config file lines	0	~150 lines (uno.config.ts)
Class name length in templates	Short (mg-button)	Long (bg-primary text-white rounded)
Places to change one color	1 place (CSS variable definition)	2 places (CSS variable + UnoCSS mapping)
TypeScript support	None for CSS variables	Via type generation, requires extra config
Initial CSS size (gzipped)	~4 KB	~2 KB (smaller, on-demand)
Debugging experience	See background: var(--ui-primary) directly	Need to look up what bg-primary maps to
Learning curve (newcomers)	Low (just understand CSS variables)	Medium (need to understand mapping + UnoCSS rules)

Conclusion : Sacrifice ~2 KB in size for a massive reduction in maintenance cost. For a personal project, maintainability, semantic clarity, and debugging experience are more important than extreme size optimization.

VI. The Path to Harmony: Pragmatic Boundaries

My experience doesn't prove atomic CSS is bad — it proves that when your project already has a mature design token system, forcibly mapping tokens to atomic classes is redundant.

But that doesn't mean abandoning atomic tools entirely. I later found a reasonable division of labor, the key being distinguishing between "classes unrelated to values" and "classes related to values" :

Style Type	Recommended Solution	Reason
Layout (flex, grid, position)	UnoCSS atomic classes (flex, grid, items-center, justify-between, relative)	No values involved, no tokens needed, works out of the box
Spacing (padding, margin, gap)	Prefer scoped styles + var(--ui-spacing-*)	Maintains theme consistency. If atomic classes must be used, modify UnoCSS config to map values to your tokens
Colors, border-radius, shadow, animation	Always scoped styles + CSS variables	Strong semantics, no mapping cost, intuitive debugging
Responsive variants	Can use UnoCSS md: prefix, but only for layout/spacing classes, never for colors	Clean and doesn't pollute design tokens

Special Note on Spacing

UnoCSS's default p-4 equals 1rem, while your design token might have --ui-spacing-md: 0.75rem. Using p-4 directly bypasses the design system. If you really want to use atomic spacing classes, you must modify the config:

// uno.config.ts (only if you want atomic spacing)
theme: {
  spacing: {
    sm: 'var(--ui-spacing-sm)',
    md: 'var(--ui-spacing-md)',
    lg: 'var(--ui-spacing-lg)',
  }
}

Then you can write p-sm, m-md. But note: this returns to the mapping maintenance problem — every time you change a token value, you must sync the UnoCSS config. I ultimately chose to completely avoid atomic spacing classes, using only valueless layout classes.

VII. When to Use Atomic CSS (If You Don't Have Design Tokens)

I'm not an opponent of atomic CSS. I would not hesitate to choose UnoCSS/Tailwind if:

• ✅ New project, rapid prototyping
• ✅ Design system not yet mature, still iterating quickly
• ✅ Entire team familiar with atomic syntax
• ✅ No need to reuse styles across frameworks

Scenarios to avoid :

• ❌ Existing mature design tokens requiring long-term maintenance
• ❌ Need to reuse style files across Vue/React/Svelte
• ❌ CSS size is not the primary concern (modern atomic frameworks are actually quite small)

VIII. Advice for Developers in the Same Situation

If you're like me — already have a complete design token system (CSS variables, Design Tokens) but want to try atomic CSS — my advice:

1. Don't map core tokens like colors, theme spacing, border-radius. Use them directly via var(--ui-*) in scoped styles.
2. Only use the generic layout classes provided by atomic tools (flex, grid, items-center, relative...). These have nothing to do with your design system and require no mapping.
3. Beware of "magic numbers" : Avoid hardcoded values like p-3.5 or gap-11 in templates — they break the design token contract.
4. For responsive layouts , continue using atomic tools' responsive variants (md:flex), but try to use them only for layout, never for colors/spacing.
5. If atomic tools feel like "using for the sake of using", you can completely abandon them. Native CSS + design tokens is already clear and maintainable enough.

IX. Looking Ahead: DTCG and the Future

The W3C Design Tokens Community Group (DTCG) released its first stable specification at the end of 2025, advancing design tokens as a cross-platform common language. This means the token-centric architecture is becoming industry consensus.

Atomic tools can consume design tokens, but shouldn't hijack them. Hardcoding tokens into tool-specific atomic classes locks your design system into that tool's syntax. Using CSS variables directly, on the other hand, is framework-agnostic and future-oriented.

In the future, when DTCG tooling matures, it may automatically generate atomic classes from design tokens. At that point I'll reevaluate UnoCSS. But for now (2026), manual mapping is still a maintenance burden.

X. Conclusion: Design Tokens First, Atomic Optional

In the end, my Button.vue went back to its original form:

<style scoped>
.mg-button {
  background-color: var(--ui-primary);
  color: white;
  padding: var(--ui-spacing-md) var(--ui-spacing-lg);
}
</style>

Simple, direct, semantic. That's how design tokens should be used.

UnoCSS and Tailwind are good tools, but they're not substitutes for a design system. Design tokens are the foundation; atomic is just a layer of paint on top. When you already have a solid foundation, whether to apply that layer of paint depends on whether you're willing to accept the maintenance cost for some syntactic sugar.

For me, at least, it's not worth it.

---

This article is part of the **Vue 3 Component Library Development Guide* series.*

The original Chinese version is available on my blog: moongate.top.

Try the component library on npm: moongate-vue

© 2026 yuelinghuashu. This work is licensed under CC BY-NC 4.0.