XenT uses a design token system based on 16 primitive values to generate complete themes. The architecture follows a three-tier hierarchy that separates concerns between primitive tokens, semantic meanings, and component-specific applications.

Design Token Architecture

The system uses a three-tier hierarchy:

Related Approaches

The design token pattern is used by several major design systems:

shadcn/ui

Uses 16 primitive tokens with background/foreground pairs:

--background, --foreground
--card, --card-foreground
--primary, --primary-foreground
--secondary, --secondary-foreground
--muted, --muted-foreground
--accent, --accent-foreground
--destructive, --border, --input, --ring

Chakra UI

Uses a three-tier hierarchy: Primitive → Semantic → Component tokens with automatic derivation.

Material UI

Uses minimal semantic colors with CSS functions generating variants automatically.

Ant Design

Uses a Seed Token → Map Token → Alias Token architecture with algorithmic color generation.

XenT’s Implementation

The system combines elements from these approaches:

Tier 1: Primitive Tokens (16 Core Values)

:root {
  /* Surface Primitives - Background/Foreground Pairs */
  --primitive-canvas: #ffffff; /* Main page background */
  --primitive-canvas-text: #171717; /* Main text */
  --primitive-surface: #fafafa; /* Card/elevated backgrounds */
  --primitive-surface-text: #262626; /* Surface text */
  --primitive-muted: #f5f5f5; /* Subdued backgrounds */
  --primitive-muted-text: #737373; /* Muted text */

  /* Brand Primitives */
  --primitive-brand: #0078d4; /* Primary brand */
  --primitive-accent: #00d4aa; /* Secondary accent */

  /* Semantic State Primitives */
  --primitive-danger: #dc3545;
  --primitive-warning: #ffc107;
  --primitive-success: #28a745;
  --primitive-info: #17a2b8;

  /* Utility Primitives */
  --primitive-border: #e5e5e5;
  --primitive-overlay: rgba(0, 0, 0, 0.5);
  --primitive-focus: #0078d4;
  --primitive-shadow: rgba(0, 0, 0, 0.1);
}

Tier 2: Semantic Tokens (Auto-Derived)

:root {
  /* Surface System */
  --surface-page: var(--primitive-canvas);
  --surface-page-text: var(--primitive-canvas-text);
  --surface-card: var(--primitive-surface);
  --surface-card-text: var(--primitive-surface-text);

  /* Interactive System */
  --interactive-primary: var(--primitive-brand);
  --interactive-primary-text: var(--primitive-canvas);

  /* Auto-generated Hover/Active States using CSS functions */
  --interactive-primary-hover: color-mix(in srgb, var(--primitive-brand) 85%, black);
  --interactive-primary-active: color-mix(in srgb, var(--primitive-brand) 75%, black);

  /* Border System */
  --border-default: var(--primitive-border);
  --border-muted: color-mix(in srgb, var(--primitive-border) 50%, transparent);
  --border-emphasis: color-mix(in srgb, var(--primitive-border) 150%, black);
}

Tier 3: Component Tokens (Minimal)

:root {
  /* Only define what can't be computed */
  --button-radius: 6px;
  --input-radius: 4px;
  --card-radius: 8px;

  /* Special cases */
  --navbar-bg: color-mix(in srgb, var(--surface-page) 95%, transparent);
  --code-bg: var(--surface-overlay);
  --selection-bg: color-mix(in srgb, var(--primitive-brand) 20%, transparent);
}

Theme Switching Made Simple

Dark Theme: Override Only What Changes

[data-theme='dark'] {
  --primitive-canvas: #0a0a0a;
  --primitive-canvas-text: #fafafa;
  --primitive-surface: #171717;
  --primitive-surface-text: #e5e5e5;
  --primitive-muted: #262626;
  --primitive-muted-text: #a3a3a3;

  --primitive-brand: #3b82f6; /* Brighter for dark mode */
  --primitive-accent: #10b981;

  --primitive-border: #404040;
  /* Everything else auto-computes! */
}

Instead of redefining 225+ variables, dark theme only needs to override 10 values. All hover states, borders, and component variations are computed automatically.

The Magic: CSS Functions

Modern CSS functions eliminate the need for manual color variants:

/* Old way: Manual definition */
--color-brand-primary: #0078d4;
--color-brand-hover: #106ebe;
--color-brand-active: #005a9e;
--color-brand-light: #e1f5fe;

/* New way: Computed automatically */
--interactive-primary: var(--primitive-brand);
--interactive-primary-hover: color-mix(in srgb, var(--primitive-brand) 85%, black);
--interactive-primary-active: color-mix(in srgb, var(--primitive-brand) 75%, black);
--interactive-primary-subtle: color-mix(in srgb, var(--primitive-brand) 10%, transparent);

Benefits of the New System

1. 90% Reduction: From 225+ variables to 16 primitives
2. Systematic Relationships: Hover/active states computed automatically
3. Consistent Naming: Clear primitive → semantic → component hierarchy
4. Minimal Theme Files: Only override what actually changes
5. Future-Proof: Easy to add new colors or components
6. Modern CSS: Uses color-mix(), light-dark() for computed variants

Implementation Strategy

Phase 1: Foundation Setup

• Create new token files: primitives.css, semantics.css, components.css
• Establish naming conventions
• Set up the three-tier hierarchy

Phase 2: Gradual Migration

• Create mapping from old → new tokens
• Incremental component migration with fallbacks
• Use CSS :where() for temporary dual-support
• Automated find/replace tooling

Phase 3: Theme Simplification

• Consolidate theme files to primitive overrides only
• Remove redundant aliases and component variables
• Add new themes with minimal effort

Looking Forward

This new system positions XenT’s theming architecture alongside the best design systems in 2024. By reducing complexity while increasing capability, we’re creating a foundation that will scale beautifully as the project grows.

The transition from 225 variables to 16 primitives isn’t just about reduction—it’s about creating a system that makes sense, scales efficiently, and embraces the latest CSS capabilities.

Implementation of this new theme system is planned for the next major release. Stay tuned for technical deep-dives on each phase of the migration.