Multi Namespace Token Strategy

The Problem

A website starts small — a blog with article pages. The design team creates tokens under a single namespace:

@theme {
  /* myweb- namespace: article-focused design */
  --spacing-myweb-hsp-sm: 20px;
  --spacing-myweb-hsp-md: 40px;
  --spacing-myweb-vsp-sm: 24px;
  --spacing-myweb-vsp-md: 48px;

  --font-size-myweb-body: 1.125rem;
  --font-size-myweb-h1: 2.5rem;
  --font-size-myweb-h2: 1.75rem;
  --font-size-myweb-caption: 0.875rem;
}

This works. Spacing is generous for readability. Font sizes are optimized for long-form content. Every component shares the same design language.

Then the site grows. A login page arrives. Then a user settings panel. Then an admin dashboard with data tables, dense toolbars, and compact navigation. The admin UI needs tighter spacing, smaller font sizes, and a denser layout — the opposite of what the article tokens provide.

The instinct is to add more tokens to the same namespace:

@theme {
  /* Original article tokens */
  --spacing-myweb-hsp-sm: 20px;
  --spacing-myweb-hsp-md: 40px;
  --spacing-myweb-vsp-sm: 24px;
  --spacing-myweb-vsp-md: 48px;

  /* ...now add admin-density tokens into the same namespace */
  --spacing-myweb-hsp-dense-sm: 8px;
  --spacing-myweb-hsp-dense-md: 16px;
  --spacing-myweb-vsp-dense-sm: 6px;
  --spacing-myweb-vsp-dense-md: 12px;

  --font-size-myweb-body: 1.125rem;
  --font-size-myweb-body-dense: 0.8125rem;
  --font-size-myweb-h1: 2.5rem;
  --font-size-myweb-h1-dense: 1.25rem;
  --font-size-myweb-h2: 1.75rem;
  --font-size-myweb-h2-dense: 1rem;
  --font-size-myweb-caption: 0.875rem;
  --font-size-myweb-caption-dense: 0.75rem;
}

The token set doubles in size. Every axis now has both “article” and “dense” variants. Developers must choose between hsp-sm and hsp-dense-sm for every spacing decision. The tight token strategy — designed to constrain choices — now offers twice as many options as before.

As the site adds more contexts (marketing landing pages, email templates, embedded widgets), the problem compounds. A single namespace tries to serve every design context, and the token set becomes a bloated list of variations.

The Solution

Split tokens into separate namespaces, one per design context. Each namespace contains a focused, minimal token set that serves exactly one type of UI.

/* ── Article/content context ── */
@theme {
  --spacing-myweb-hsp-sm: 20px;
  --spacing-myweb-hsp-md: 40px;
  --spacing-myweb-vsp-sm: 24px;
  --spacing-myweb-vsp-md: 48px;

  --font-size-myweb-body: 1.125rem;
  --font-size-myweb-h1: 2.5rem;
  --font-size-myweb-h2: 1.75rem;
  --font-size-myweb-caption: 0.875rem;
}

/* ── Admin/dashboard context ── */
@theme {
  --spacing-myadmin-hsp-sm: 8px;
  --spacing-myadmin-hsp-md: 16px;
  --spacing-myadmin-vsp-sm: 6px;
  --spacing-myadmin-vsp-md: 12px;

  --font-size-myadmin-body: 0.8125rem;
  --font-size-myadmin-h1: 1.25rem;
  --font-size-myadmin-h2: 1rem;
  --font-size-myadmin-caption: 0.75rem;
}

The total token count is the same, but the structure is different:

• Each namespace has exactly 4 spacing + 4 font-size tokens — the same tight constraint as a single-context project
• Developers working on article pages only interact with myweb- tokens
• Developers working on the admin dashboard only interact with myadmin- tokens
• There is no ambiguity about which token to use — the namespace tells you the context

File Organization

Separate namespaces work best when each lives in its own CSS file:

styles/
├── tokens-myweb.css      /* Article/content tokens */
├── tokens-myadmin.css    /* Admin/dashboard tokens */
├── tokens-shared.css     /* Color, font-family, breakpoints — shared */
└── app.css               /* Imports all token files */

Shared tokens (colors, font families, breakpoints) that apply across all contexts stay in a shared file. Only context-specific tokens (spacing, font sizes) are split into namespaces.

/* app.css */
@import "tailwindcss/preflight";
@import "tailwindcss/utilities";
@import "./tokens-shared.css";
@import "./tokens-myweb.css";
@import "./tokens-myadmin.css";

Demos

Visual Contrast: Article vs Admin UI

The same page framework rendered with two different token namespaces. Article tokens produce generous, readable spacing. Admin tokens produce a dense, efficient layout.

When to Split: Decision Boundary

Not every page variation needs its own namespace. The split makes sense when design rules — spacing rhythm, font size scale, density — are fundamentally different between contexts.

Namespace Usage in Components

Each namespace produces its own set of Tailwind utility classes. Developers working in a specific context use only that context’s namespace prefix.

Shared vs Context-Specific Tokens

Not all token categories need namespace separation. The rule: split tokens that define density and scale (spacing, font sizes). Keep tokens that define identity (colors, font families, border radii) shared.

/* tokens-shared.css — applies everywhere */
@theme {
  --color-brand: oklch(55.5% 0.163 48.998);
  --color-surface: hsl(0 0% 100%);
  --color-text: hsl(222 47% 11%);
  --color-muted: hsl(215 16% 47%);
  --color-border: hsl(214 32% 91%);

  --font-sans: system-ui, sans-serif;
  --font-mono: ui-monospace, monospace;

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

Quick Reference

Common AI Mistakes

• Mixing tokens from different namespaces in one component — if a component uses px-myweb-hsp-sm for horizontal padding and text-myadmin-body for font size, it is pulling from two design contexts; each component should use tokens from exactly one namespace
• Creating a namespace for every page — namespaces represent design contexts (content vs admin), not individual pages; a blog post and an about page share the same design context
• Splitting colors into namespaces — colors define brand identity and should remain shared; only density-related tokens (spacing, font sizes) need namespace separation
• Using generic token names without a namespace prefix — in a multi-namespace project, hsp-sm is ambiguous; always use the full prefix (myweb-hsp-sm or myadmin-hsp-sm)
• Creating namespaces preemptively — start with one namespace; split only when a genuinely different design context arrives with different density requirements

When to Use

Good fit

• Sites with distinct UI contexts — a content-heavy site that adds an admin dashboard, or a marketing site that adds an application UI
• Large teams with separate ownership — when the article team and the admin team work independently, separate namespaces prevent cross-contamination of design decisions
• Projects using the tight token strategy — namespace separation is a natural extension when the single namespace accumulates too many variants

Not needed

• Single-context websites — a blog, a documentation site, or a portfolio does not need multiple namespaces
• Small projects — if the token set is small and manageable, the complexity of multiple namespaces adds overhead without benefit
• Projects early in development — start with one namespace and split later when a second design context actually arrives

Contrast with Other Token Strategies

This strategy builds on top of the tight token strategy. It does not replace it — it extends it for multi-context projects.

References

• Tailwind CSS v4 Theme Configuration
• Tailwind CSS v4 @theme Directive