Core concepts

Token categories

Every design system needs tokens in these categories (example prefixes shown):

• Color — --color- (semantic tokens like --color-surface, --color-accent)
• Spacing — --space- (--space-sm, --space-md)
• Radii — --radius- (--radius-card, --radius-pill)
• Shadow — --shadow- (--shadow-subtle, --shadow-elevated)
• Typography — --font-, type scale --text- (use clamp() for fluid scales)
• Motion — --duration-, --ease-
• Z-index — --z-
• Blur — --blur-
• Mask / Clip / Text-Shadow — --mask-, --text-shadow- (v4.1 adds utilities; expose tokens when you need consistent styles)

Concentric radii rule

Nested surfaces must preserve concentric radii: outer radius ≈ (inner radius + padding). When designing card systems, document the math and provide helper tokens so authors keep consistent results.

OKLCH color authoring

Author custom colors in OKLCH for perceptual uniformity. Provide HSL/hex fallbacks for legacy browsers only when necessary.

Example:

--color-accent: oklch(0.65 0.25 29);
--color-accent-hover: oklch(0.58 0.25 29);
--color-accent-subtle: oklch(0.65 0.15 29 / 0.12);

Workflow

1. Define the complete @theme block

Use @theme at top-level CSS to declare every token that should produce utility classes. Tailwind uses the @theme block to both expose CSS variables and generate class names (see docs).

Example @theme (semantic tokens):

@theme {
  /* Colors */
  --color-surface: oklch(0.985 0.005 260);
  --color-accent: oklch(0.65 0.25 29);
  --color-text-primary: oklch(0.13 0.01 260);

  /* Spacing */
  --space-xs: 0.25rem;
  --space-sm: 0.5rem;
  --space-md: 1rem;

  /* Radii */
  --radius-card: 1rem;
  --radius-sm: 0.375rem;

  /* Shadows */
  --shadow-subtle: 0 1px 2px oklch(0 0 0 / 0.04);
  --shadow-elevated: 0 4px 12px oklch(0 0 0 / 0.08), 0 1px 3px oklch(0 0 0 / 0.04);

  /* Type scale */
  --text-base: clamp(0.9rem, 0.85rem + 0.3vw, 1rem);
  --text-lg: clamp(1.05rem, 0.95rem + 0.5vw, 1.25rem);

  /* Motion */
  --duration-fast: 120ms;
  --ease-out-expo: cubic-bezier(0.16, 1, 0.3, 1);
}

Notes:

• The @theme directive must be top-level (not nested) — Tailwind uses it to generate utilities.
• Prefer semantic token names (--color-surface) rather than direct role names (--color-gray-500).

2. Add dark mode tokens

Override semantic tokens in prefers-color-scheme or per-theme classes. Keep token names the same — only values change.

@media (prefers-color-scheme: dark) {
  :root {
    --color-surface: oklch(0.14 0.005 260);
    --color-text-primary: oklch(0.93 0.005 260);
  }
}

3. Use tokens as Tailwind utilities in components

Tailwind generates utility classes from your @theme tokens (e.g., bg-surface, text-accent, px-space-md). Use these classes instead of raw values.

<div class="bg-surface rounded-card p-space-md shadow-elevated">
  <h2 class="font-display text-text-primary text-2xl">Heading</h2>
  <p class="mt-space-sm text-text-secondary text-base">Body text</p>
</div>

4. Component-level token usage

Keep component classes token-based so swapping theme values updates components automatically.

<button class="bg-accent text-surface rounded-sm px-space-md py-space-sm text-sm transition duration-fast hover:bg-accent-hover">CTA</button>

Additional tactics (new signals)

Mapping new utilities (Tailwind v4.1)

Tailwind v4.1 added utilities such as text-shadow-*, mask-*, colored drop-shadow, pointer targeting (pointer-*, any-pointer-*), and items-baseline-last (see the v4.1 blog). If your design system needs consistent text-shadow or mask behavior, expose tokens and map them to generated utilities:

• Add --text-shadow-subtle and --text-shadow-elevated in @theme, then use text-shadow-subtle as a class (Tailwind will generate text-shadow-subtle if the token exists).
• For masks, create --mask-hero-gradient and use mask-hero-gradient classes.

This keeps shadow and mask usage consistent across components and allows Tailwind to produce ergonomic classes.

Reference: Tailwind CSS v4.1 blog (text-shadow, mask, variants).

Using Tailwind Plus vanilla-JS Elements (new)

Tailwind Plus UI blocks now ship with a small library of framework-agnostic custom elements (@tailwindplus/elements) so interactive patterns (dialogs, dropdowns, command palettes) work out-of-the-box with just a script tag. To integrate:

1. Include the Elements script in your page (CDN or package):

<script src="https://cdn.jsdelivr.net/npm/@tailwindplus/elements@1" type="module"></script>

2. Use the custom element with your token-based classes. The custom element emits data attributes/classes you can style with your tokens.

Example dropdown:

<el-dropdown class="relative inline-block text-left">  
  <button class="inline-flex w-full justify-center gap-x-1.5 rounded-md bg-surface px-3 py-2 text-sm font-semibold text-text-primary shadow-subtle ring-1 ring-border">Options</button>
  <el-menu anchor="bottom end" popover class="w-56 origin-top-right rounded-md bg-surface shadow-elevated ring-1 ring-black/5">
    <div class="py-1">
      <a class="block px-4 py-2 text-sm text-text-secondary">Account settings</a>
    </div>
  </el-menu>
</el-dropdown>

Why this matters:

• Custom elements remove framework lock-in and let token-driven classes style interactive UIs consistently.
• Prefer token classes (bg-surface, text-text-primary, shadow-elevated) inside element markup so themes and per-site overrides carry through.

Reference: Tailwind Plus vanilla-JS support blog (Elements library).

Examples

Card with concentric radii

<div class="rounded-card bg-surface-elevated p-space-md shadow-elevated">
  <img class="rounded-sm w-full aspect-video object-cover" src="/hero.jpg" alt="" />
  <div class="mt-space-sm">
    <h3 class="font-sans text-lg font-semibold text-text-primary">Card title</h3>
    <p class="mt-space-xs text-sm text-text-secondary">Card description</p>
  </div>
</div>

Metric display with tabular-nums

<div class="font-mono tabular-nums text-4xl text-accent">$12,450.00</div>

Decision tree

• Starting a new project? → Define full @theme block first, before components
• Existing project with arbitrary values? → Audit, create token map, migrate incrementally (use the upgrade tool for v3→v4)
• Need dark mode? → Override semantic tokens in prefers-color-scheme: dark or per-theme class
• Need brand theming? → Use CSS custom property overrides per theme class
• Need fluid type? → Use clamp() in type-scale tokens
• Need interactive UI blocks and prefer no framework? → Consider Tailwind Plus Elements and style them using token-based classes

Edge cases and gotchas (updated)

1. Tailwind v4 only — @theme and generated utilities are v4 features. If you must remain on v3, use theme.extend in tailwind.config.js instead and plan an upgrade.
2. Browser and platform support — Tailwind v4’s engine expects modern browser features; v4 officially targets Safari 16.4+, Chrome 111+, Firefox 128+. The upgrade guide documents tradeoffs for older-browser support.
3. Upgrade tool requirements — the official v4 upgrade tool (npx @tailwindcss/upgrade) requires Node.js 20+. Run it in a feature branch and review changes.
4. OKLCH and fallbacks — OKLCH is broadly supported in modern browsers; keep HSL/hex fallback layers only where you need to support legacy clients.
5. Token proliferation — don’t create tokens for one-off values. Tokens are for repeated design decisions.
6. Design Tokens spec is evolving — the Design Tokens Community Group has been publishing a file-format and resolver proposals (preview drafts 2025–2026). Track the spec for interoperability ideas (modern color spaces, token resolvers, groups/aliases). Don’t assume any breaking standardization until the spec reaches stable recommendation status; design your internal token export/import to be adaptable.
7. Concentric radii math — when nesting rounded elements, calculate inner radius = outer radius − padding and provide helper tokens where needed.
8. Dark mode flash — when using prefers-color-scheme, the initial paint may flash; consider a small inline script to set theme class before first paint.

Evaluation criteria

• All colors, spacing, radii, shadows, and type sizes use tokens from @theme
• Color palette is limited and semantic; use OKLCH authoring
• Concentric radii preserved on nested surfaces
• Type scale uses clamp() for fluid sizing
• Dark mode tokens are semantic overrides, not separate color names
• tabular-nums used for metrics and numeric displays
• No raw hex values or arbitrary Tailwind classes in design-critical positions
• Shadow and mask tokens map to layered, reusable utilities (use v4.1 utilities where appropriate)

Research-backed changes (sources)

• Tailwind v4.0: reimagined CSS-first configuration, @theme, modern-engine, and migration guide — Tailwind blog/docs (v4 release and upgrade guide). (https://tailwindcss.com/blog/tailwindcss-v4, https://tailwindcss.com/docs/upgrade-guide)
• Tailwind v4.1: text-shadow utilities, mask utilities, colored drop-shadow, pointer/any-pointer utilities — map tokens to these new utilities when you need consistent behavior. (https://tailwindcss.com/blog/tailwindcss-v4-1)
• Tailwind Plus Vanilla JS Elements: @tailwindplus/elements provides framework-agnostic custom elements for interactive blocks — prefer token classes inside these elements to preserve theming. (https://tailwindcss.com/blog/vanilla-js-support-for-tailwind-plus)
• Design Tokens Format (preview draft): file format and resolver proposals are in-flight (Design Tokens Community Group drafts, 2025–2026). Follow the spec for token export/import plans. (https://www.designtokens.org/tr/drafts/format/)

Next edits (this revision)

• Added a new tactic showing how to map v4.1 utilities (text-shadow, masks) to tokens.
• Added concrete guidance for using Tailwind Plus vanilla-JS Elements with token-driven classes.
• Added platform/tooling notes from the v4 upgrade guide (browser targets and Node.js requirement).
• Added a short advisory referencing the Design Tokens spec drafts and how that affects token transport and interoperability.

Practical follow-ups / experiments

• Experiment: Add --text-shadow-* tokens and confirm Tailwind v4.1 generates text-shadow-* utilities; document a migration snippet.
• Experiment: Build a small design-system site using @tailwindplus/elements and ensure tokens style the custom elements correctly across themes.
• Track: Monitor Design Tokens Community Group and Tailwind release notes for any changes to @theme semantics or token resolver recommendations.