Theme System Cheatsheet

One-page reference for developers and AI agents - copy-paste ready

Theme System Cheatsheet

Use this file when building UI components. All variables work in light and dark mode.

🎨 Core Variables (Copy-Paste)

// Backgrounds
background: var(--ux-background);           // Page background
background: var(--ux-surface);              // Cards, panels, elevated surfaces
background: var(--ux-surface-variant);      // Alternate surface (inputs, subtle areas)
background: var(--ux-card-bg);              // Card-specific (theme-aware)

// Text - ALWAYS use semantic variables
color: var(--ux-text-primary);              // Main content (highest contrast)
color: var(--ux-text-secondary);            // Supporting text
color: var(--ux-text-muted);                // Less important
color: var(--ux-on-surface);                // Text ON surface/background
color: var(--ux-on-primary);                // Text ON primary colored background

// Borders
border: 1px solid var(--ux-border);
border-color: var(--ux-outline);

// Brand colors
background: var(--ux-primary);
color: var(--ux-on-primary);                // REQUIRED on primary background

⚠️ Background → Text Mapping (CRITICAL)

Background Variable Text Variable (REQUIRED)
--ux-primary --ux-on-primary
--ux-secondary --ux-on-secondary
--ux-surface --ux-on-surface
--ux-background --ux-on-background
--ux-error --ux-on-error
--ux-success --ux-on-success
--ux-warning --ux-on-warning
--ux-info --ux-on-info

Rule: Never use --ux-text-primary on colored backgrounds. Use --ux-on-{color}.

📦 Legacy Aliases (Backward Compatible)

Use these if migrating from older components:

Legacy Prefer Notes
--surface-ground --ux-background Page background
--surface-card --ux-surface Cards, panels
--surface-border --ux-border Borders
--text-color --ux-text-primary Main text
--text-color-secondary --ux-text-secondary Secondary text
--surface-100 --ux-surface-variant Subtle surfaces
--surface-200 --ux-surface-variant Hover states

🌟 Glass & Effects

// Glass panel (theme-aware)
background: var(--ux-glass-bg);
backdrop-filter: var(--ux-glass-blur);
border: var(--ux-glass-border);
box-shadow: var(--ux-glass-shadow);

// Or use utility class
.ux-glass-panel { ... }

// Alpha operations (for custom glass)
background: rgba(var(--ux-surface-rgb), 0.9);
background: rgba(var(--ux-primary-rgb), 0.1);  // 10% primary tint

🎯 Lively Cards & Chips (Dark Mode Contrast)

Primary-tinted surfaces for dashboards — less gray, more contrast in dark mode. Use these for cards, tab bars, and chips.

// Lively glass cards (primary gradient overlay in dark mode)
background: var(--ux-glass-card-bg);
background: var(--ux-glass-card-bg-hover);   // hover state
border: var(--ux-glass-card-border);
border: var(--ux-glass-card-border-hover);    // hover state
box-shadow: var(--ux-glass-card-shadow);
box-shadow: var(--ux-glass-card-shadow-hover);

// Or use utility class
.ux-glass-card-lively { ... }

// Chips / tabs (clear inactive vs active contrast)
background: var(--ux-chip-bg);                // inactive
background: var(--ux-chip-bg-hover);         // hover
background: var(--ux-chip-bg-active);        // active tab
border: var(--ux-chip-border);
border: var(--ux-chip-border-active);
color: var(--ux-chip-color);
color: var(--ux-chip-color-active);

// Or use utility classes
.ux-chip-bar { ... }   // tab bar container
.ux-chip-tab { ... }   // tab button (.active for selected)

📏 Spacing & Layout

padding: var(--ux-spacing-md);
gap: var(--ux-spacing-sm);
margin: var(--ux-spacing-lg);
// Scale: 3xs, 2xs, xs, sm, md, lg, xl, 2xl, 3xl

🔘 Radius & Shadows

border-radius: var(--ux-radius-md);
border-radius: var(--ux-radius-lg);
border-radius: var(--ux-radius-full);       // Pills, circles
box-shadow: var(--ux-shadow-md);
box-shadow: var(--ux-shadow-lg);

🎯 Common Patterns

Card (theme-aware)

.card {
  background: var(--ux-surface);
  border: 1px solid var(--ux-border);
  border-radius: var(--ux-radius-lg);
  color: var(--ux-on-surface);
  box-shadow: var(--ux-shadow-sm);
}

Button Primary

.btn-primary {
  background: var(--ux-primary);
  color: var(--ux-on-primary);
  border: none;
  border-radius: var(--ux-radius-md);
  padding: var(--ux-spacing-sm) var(--ux-spacing-lg);
}

Light Tinted Card (5–15% opacity)

.card-tinted {
  background: linear-gradient(135deg, 
    rgba(var(--ux-primary-rgb), 0.05) 0%, 
    rgba(var(--ux-primary-rgb), 0.08) 100%);
  border: 1px solid var(--ux-primary);
  // Text stays dark - background is light
  .title { color: var(--ux-text-primary); }
  .desc { color: var(--ux-text-secondary); }
}

Input / Form Control

.input {
  background: var(--ux-surface);
  border: 1px solid var(--ux-border);
  color: var(--ux-on-surface);
  &::placeholder {
    color: var(--ux-text-muted);
  }
}

🛠️ Utility Classes (HTML)

<div class="ux-bg-adaptive surface">...</div>
<span class="ux-text-adaptive">...</span>
<button class="ux-btn-smart primary">Action</button>
<div class="ux-glass-panel">...</div>
<div class="ux-badge-smart success">Status</div>

📁 Key Files

Need File
Full variable list css-variables.md
AI design rules ai-design-guidelines.md
Design tokens (TS) libs/theme-system/theme-runtime/src/lib/models/ai-design-tokens.const.ts
Variant mixins libs/theme-system/theme-styles/src/lib/styles/mixins/ux-variants.scss
Smart utilities libs/theme-system/theme-styles/src/lib/styles/utilities/ux-smart-theme-utilities.scss

❌ Anti-Patterns