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- (Tailwind v4.1 added 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 the Theme Variables 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 (for example bg-mint-500, text-accent, fill-mint-500, or px-space-md depending on namespace). 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 (April 3, 2025) introduced text-shadow-*, mask-*, colored drop-shadow, pointer-* / any-pointer-*, items-baseline-last, and several new variants and DX improvements. Recommended practices:

• Add --text-shadow-subtle and --text-shadow-elevated to @theme, then use the generated text-shadow-subtle classes. Confirm generation in your build (Tailwind generates utilities from tokens present in @theme).
• For masks, add --mask-hero-gradient and map it to mask-hero-gradient classes. Treat masks as presentation tokens and avoid tokenizing single-use masks.
• Use pointer-* utilities to explicitly target touch vs pointer interactions for components where input modality affects layout or hover states.
• Because v4.1 also improves graceful degradation for older browsers, review the "Improved compatibility with older browsers" section in the v4.1 release notes when planning fallbacks.

Reference: Tailwind CSS v4.1 blog (April 3, 2025)

Using Tailwind Plus Elements (vanilla JS)

Tailwind Plus customers can use @tailwindplus/elements — a small collection of headless custom elements that provide accessible interactivity (dropdowns, dialogs, command palettes) without a framework. The library was announced in mid-2025 and is distributed as an ES module; the Tailwind Plus blog contains CDN examples.

Integration notes:

• Style the elements using token-based classes inside the element markup so theme overrides carry through.
• Elements expose data attributes and state classes (e.g., data-open, data-closed) you can style with tokens.
• Because Elements are a paid Tailwind Plus product, treat usage as a product decision — fall back to framework-specific implementations if you don't have Plus.

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 — v4's engine targets modern browsers; v4.1 (April 3, 2025) improves graceful degradation for older browsers. Test key platforms and provide fallbacks for critical visuals (OKLCH fallbacks, mask alternatives).
3. Upgrade tool requirements — use the official upgrade helper and run it in a feature branch; verify Node and environment requirements before executing automated migrations.
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 status — the Design Tokens Community Group published the Format Module as a Final Community Group Report on 28 Oct 2025 (Design Tokens TR 2025.10). The report is considered stable and provides a recommended file format and resolver patterns for exchanging tokens. Design your exports to map to the spec's structures (groups, aliases, references) and support resolver semantics.
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, text-shadow, and mask tokens map to layered, reusable utilities (use v4.1 utilities where appropriate)

Research-backed changes (sources)

• Tailwind v4.0 & upgrade guide: reimagined CSS-first configuration, @theme, modern engine, and migration guide — Tailwind blog/docs (v4 release and upgrade guide).
• Tailwind v4.1 (April 3, 2025): text-shadow utilities, mask utilities, colored drop-shadow, pointer/any-pointer utilities, and improved compatibility notes. (Tailwind v4.1 blog)
• Tailwind Plus Elements (mid-2025): @tailwindplus/elements provides framework-agnostic custom elements for interactive blocks — style them using token classes.
• Design Tokens Format Module (Final Community Group Report — 28 Oct 2025): stable file format and resolver guidance for token transport and interoperability (Design Tokens TR 2025.10).

Next edits (this revision)

• Clarified v4.1 feature set with release date (April 3, 2025) and added mapping guidance for text-shadow, mask, pointer-*, and colored drop-shadow.
• Documented Tailwind Plus Elements (@tailwindplus/elements) with integration notes and CDN usage as announced in 2025.
• Updated Design Tokens guidance to reference the Design Tokens TR 2025.10 Final Community Group Report (28 Oct 2025) and recommended exporting to the spec's structures.
• Preserved the Node.js 20+ recommendation for upgrade tooling; advise verifying environment requirements before running automated migrations.

Practical follow-ups / experiments

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