Token Architecture

The 3 Layers

nnuikit's component system is built on three layers of CSS custom properties. Each layer has a single responsibility — and together they let you switch themes, enable dark mode, or override one component, all with minimal CSS.

/* All brand shades live here */
--color-brand-25:  #f5f3ff;
--color-brand-100: #ede9fe;
--color-brand-400: #a78bfa;
--color-brand-700: #6d28d9;
--color-brand-800: #5b21b6;
--color-brand-950: #1e0a4a;

/* Roles — point at base palette shades */
--color-surface-brand-primary:    var(--color-brand-800);
--color-surface-brand-secondary:  var(--color-brand-700);
--color-surface-brand-quaternary: var(--color-brand-400);  /* disabled */
--color-surface-brand-l1:         var(--color-brand-25);   /* subtle tint */

/* Component reads these — they point up the chain */
--color-button-brand-default-surface:  var(--color-surface-brand-primary);
--color-button-brand-hover-surface:    var(--color-surface-brand-secondary);
--color-button-brand-disabled-surface: var(--color-surface-brand-quaternary);

Why Not Just Use --color-brand-800 Directly?

If you hardcode var(--color-brand-800) in a component, inverting all shades for dark mode breaks some use cases while fixing others — because different parts of the UI remap in opposite directions.

Button surfaces flip from dark to light. Badge backgrounds flip from light to dark. Disabled states shift toward the middle. There's no single inversion formula — each role has its own mapping. That's exactly what Layer 2 encodes.

Choosing the Right Layer to Override

Without this system: 5 themes × 2 modes × 50 components × ~8 properties = thousands of overrides. With 3 layers: roughly 100 total.

One Change, Everything Updates

Here's what happens when you switch to the violet theme. A single Layer 1 override cascades through all three layers automatically:

/* 1. Layer 1: swap the base palette (12 lines) */
.violet {
  --color-brand-700: var(--color-violet-700);
  --color-brand-800: var(--color-violet-800);
  /* ... all 12 shades remapped */
}

/* 2. Layer 2: auto-updates — no changes needed */
--color-surface-brand-primary: var(--color-brand-800);
/*                              ^ now resolves to violet-800 */

/* 3. Layer 3: auto-updates — no changes needed */
--color-button-brand-default-surface: var(--color-surface-brand-primary);
/*                                     ^ now resolves to violet-800 */

12 lines of CSS. Every component, every state, every mode — updated instantly.

Token Categories

Adding Tokens to Your Project

When you run npx nnuikit init, the base design tokens are written to src/routes/layout.css and imported automatically. Component tokens are added when you run npx nnuikit add <component>.

/* layout.css — after running init and adding button */
@import 'tailwindcss';
/* base tokens are injected directly into layout.css by: npx nnuikit init */
@import '$lib/components/ui/button/tokens.css';           /* button component tokens */

Customizing at the Right Layer

/* Change brand color globally — override Layer 1 */
:root {
  --color-brand-700: #7c3aed;
  --color-brand-800: #6d28d9;
}

/* Enable dark mode — override Layer 2 */
.dark {
  --color-surface-brand-primary:   var(--color-brand-200);
  --color-surface-brand-secondary: var(--color-brand-300);
}

/* Override one component in one section — override Layer 3 */
.marketing-hero {
  --color-button-brand-default-surface: var(--color-surface-brand-tertiary);
}

TL;DR