JosiahSiegel/tailwindcss-advanced-design-systems

Tailwind CSS Advanced Design Systems

Building Design Tokens with @theme

Complete Design Token System

@import "tailwindcss";

@theme {
  /* ===== COLOR SYSTEM ===== */

  /* Disable all defaults for full control */
  --color-*: initial;

  /* Semantic color tokens */
  --color-surface-primary: oklch(1 0 0);
  --color-surface-secondary: oklch(0.98 0.002 250);
  --color-surface-tertiary: oklch(0.95 0.004 250);
  --color-surface-inverse: oklch(0.15 0.02 250);

  --color-text-primary: oklch(0.15 0.02 250);
  --color-text-secondary: oklch(0.4 0.02 250);
  --color-text-tertiary: oklch(0.55 0.015 250);
  --color-text-inverse: oklch(0.98 0 0);
  --color-text-disabled: oklch(0.7 0.01 250);

  --color-border-default: oklch(0.85 0.01 250);
  --color-border-subtle: oklch(0.92 0.005 250);
  --color-border-strong: oklch(0.7 0.02 250);

  /* Brand colors with full scale */
  --color-brand-50: oklch(0.97 0.02 250);
  --color-brand-100: oklch(0.93 0.04 250);
  --color-brand-200: oklch(0.87 0.08 250);
  --color-brand-300: oklch(0.78 0.12 250);
  --color-brand-400: oklch(0.68 0.16 250);
  --color-brand-500: oklch(0.58 0.2 250);
  --color-brand-600: oklch(0.5 0.2 250);
  --color-brand-700: oklch(0.42 0.18 250);
  --color-brand-800: oklch(0.35 0.15 250);
  --color-brand-900: oklch(0.28 0.12 250);
  --color-brand-950: oklch(0.2 0.08 250);

  /* Status colors */
  --color-success: oklch(0.6 0.18 145);
  --color-success-subtle: oklch(0.95 0.04 145);
  --color-warning: oklch(0.75 0.18 85);
  --color-warning-subtle: oklch(0.95 0.06 85);
  --color-error: oklch(0.55 0.22 25);
  --color-error-subtle: oklch(0.95 0.04 25);
  --color-info: oklch(0.6 0.18 250);
  --color-info-subtle: oklch(0.95 0.04 250);

  /* ===== TYPOGRAPHY SYSTEM ===== */

  --font-*: initial;

  --font-display: "Cal Sans", "Inter", system-ui, sans-serif;
  --font-body: "Inter", system-ui, sans-serif;
  --font-mono: "JetBrains Mono", "Fira Code", monospace;

  /* Type scale (Major Third - 1.25) */
  --text-xs: 0.64rem;
  --text-sm: 0.8rem;
  --text-base: 1rem;
  --text-lg: 1.25rem;
  --text-xl: 1.563rem;
  --text-2xl: 1.953rem;
  --text-3xl: 2.441rem;
  --text-4xl: 3.052rem;
  --text-5xl: 3.815rem;

  /* Line heights */
  --leading-none: 1;
  --leading-tight: 1.15;
  --leading-snug: 1.3;
  --leading-normal: 1.5;
  --leading-relaxed: 1.625;
  --leading-loose: 2;

  /* Letter spacing */
  --tracking-tighter: -0.05em;
  --tracking-tight: -0.025em;
  --tracking-normal: 0;
  --tracking-wide: 0.025em;
  --tracking-wider: 0.05em;
  --tracking-widest: 0.1em;

  /* ===== SPACING SYSTEM ===== */

  --spacing-*: initial;

  /* 4px base unit */
  --spacing-0: 0;
  --spacing-px: 1px;
  --spacing-0_5: 0.125rem;
  --spacing-1: 0.25rem;
  --spacing-1_5: 0.375rem;
  --spacing-2: 0.5rem;
  --spacing-2_5: 0.625rem;
  --spacing-3: 0.75rem;
  --spacing-3_5: 0.875rem;
  --spacing-4: 1rem;
  --spacing-5: 1.25rem;
  --spacing-6: 1.5rem;
  --spacing-7: 1.75rem;
  --spacing-8: 2rem;
  --spacing-9: 2.25rem;
  --spacing-10: 2.5rem;
  --spacing-11: 2.75rem;
  --spacing-12: 3rem;
  --spacing-14: 3.5rem;
  --spacing-16: 4rem;
  --spacing-20: 5rem;
  --spacing-24: 6rem;
  --spacing-28: 7rem;
  --spacing-32: 8rem;
  --spacing-36: 9rem;
  --spacing-40: 10rem;
  --spacing-44: 11rem;
  --spacing-48: 12rem;
  --spacing-52: 13rem;
  --spacing-56: 14rem;
  --spacing-60: 15rem;
  --spacing-64: 16rem;
  --spacing-72: 18rem;
  --spacing-80: 20rem;
  --spacing-96: 24rem;

  /* ===== EFFECTS ===== */

  --shadow-*: initial;

  --shadow-xs: 0 1px 2px 0 oklch(0 0 0 / 0.05);
  --shadow-sm: 0 1px 3px 0 oklch(0 0 0 / 0.1), 0 1px 2px -1px oklch(0 0 0 / 0.1);
  --shadow-md: 0 4px 6px -1px oklch(0 0 0 / 0.1), 0 2px 4px -2px oklch(0 0 0 / 0.1);
  --shadow-lg: 0 10px 15px -3px oklch(0 0 0 / 0.1), 0 4px 6px -4px oklch(0 0 0 / 0.1);
  --shadow-xl: 0 20px 25px -5px oklch(0 0 0 / 0.1), 0 8px 10px -6px oklch(0 0 0 / 0.1);
  --shadow-2xl: 0 25px 50px -12px oklch(0 0 0 / 0.25);
  --shadow-inner: inset 0 2px 4px 0 oklch(0 0 0 / 0.05);

  /* Colored shadows */
  --shadow-brand: 0 4px 14px 0 oklch(0.58 0.2 250 / 0.3);
  --shadow-success: 0 4px 14px 0 oklch(0.6 0.18 145 / 0.3);
  --shadow-error: 0 4px 14px 0 oklch(0.55 0.22 25 / 0.3);

  --radius-*: initial;

  --radius-none: 0;
  --radius-sm: 0.125rem;
  --radius-default: 0.25rem;
  --radius-md: 0.375rem;
  --radius-lg: 0.5rem;
  --radius-xl: 0.75rem;
  --radius-2xl: 1rem;
  --radius-3xl: 1.5rem;
  --radius-full: 9999px;

  /* ===== MOTION ===== */

  --ease-*: initial;
  --animate-*: initial;

  --ease-linear: linear;
  --ease-in: cubic-bezier(0.4, 0, 1, 1);
  --ease-out: cubic-bezier(0, 0, 0.2, 1);
  --ease-in-out: cubic-bezier(0.4, 0, 0.2, 1);
  --ease-bounce: cubic-bezier(0.68, -0.55, 0.265, 1.55);
  --ease-spring: cubic-bezier(0.175, 0.885, 0.32, 1.275);

  --duration-75: 75ms;
  --duration-100: 100ms;
  --duration-150: 150ms;
  --duration-200: 200ms;
  --duration-300: 300ms;
  --duration-500: 500ms;
  --duration-700: 700ms;
  --duration-1000: 1000ms;

  /* ===== BREAKPOINTS ===== */

  --breakpoint-*: initial;

  --breakpoint-xs: 475px;
  --breakpoint-sm: 640px;
  --breakpoint-md: 768px;
  --breakpoint-lg: 1024px;
  --breakpoint-xl: 1280px;
  --breakpoint-2xl: 1536px;
  --breakpoint-3xl: 1920px;

  /* ===== Z-INDEX ===== */

  --z-auto: auto;
  --z-0: 0;
  --z-10: 10;
  --z-20: 20;
  --z-30: 30;
  --z-40: 40;
  --z-50: 50;
  --z-dropdown: 100;
  --z-sticky: 200;
  --z-fixed: 300;
  --z-modal-backdrop: 400;
  --z-modal: 500;
  --z-popover: 600;
  --z-tooltip: 700;
  --z-toast: 800;
}

Dark Mode Design Tokens

Automatic Dark Mode with CSS Variables

@import "tailwindcss";

@theme {
  /* Light mode tokens (default) */
  --color-surface: oklch(1 0 0);
  --color-surface-raised: oklch(0.98 0 0);
  --color-text: oklch(0.15 0 0);
  --color-text-muted: oklch(0.45 0 0);
  --color-border: oklch(0.9 0 0);
}

/* Dark mode overrides using native CSS */
@media (prefers-color-scheme: dark) {
  :root {
    --color-surface: oklch(0.12 0.02 260);
    --color-surface-raised: oklch(0.18 0.02 260);
    --color-text: oklch(0.95 0 0);
    --color-text-muted: oklch(0.65 0 0);
    --color-border: oklch(0.28 0.02 260);
  }
}

/* Selector-based dark mode */
@custom-variant dark (&:where(.dark, .dark *));

.dark {
  --color-surface: oklch(0.12 0.02 260);
  --color-surface-raised: oklch(0.18 0.02 260);
  --color-text: oklch(0.95 0 0);
  --color-text-muted: oklch(0.65 0 0);
  --color-border: oklch(0.28 0.02 260);
}

Usage

<!-- These classes work in both light and dark automatically -->
<div class="bg-[var(--color-surface)] text-[var(--color-text)]">
  <p class="text-[var(--color-text-muted)]">Muted text</p>
  <div class="border border-[var(--color-border)]">Bordered</div>
</div>

<!-- Or create semantic utility classes -->

@utility bg-surface {
  background-color: var(--color-surface);
}

@utility bg-surface-raised {
  background-color: var(--color-surface-raised);
}

@utility text-default {
  color: var(--color-text);
}

@utility text-muted {
  color: var(--color-text-muted);
}

@utility border-default {
  border-color: var(--color-border);
}

Multi-Theme Systems

Theme Switching with Data Attributes

@import "tailwindcss";

@custom-variant theme-ocean (&:where([data-theme="ocean"], [data-theme="ocean"] *));
@custom-variant theme-forest (&:where([data-theme="forest"], [data-theme="forest"] *));
@custom-variant theme-sunset (&:where([data-theme="sunset"], [data-theme="sunset"] *));

@theme {
  /* Default theme */
  --color-primary: oklch(0.6 0.2 250);
  --color-secondary: oklch(0.7 0.15 200);
  --color-accent: oklch(0.75 0.18 30);
}

[data-theme="ocean"] {
  --color-primary: oklch(0.55 0.2 220);
  --color-secondary: oklch(0.65 0.15 200);
  --color-accent: oklch(0.7 0.18 180);
}

[data-theme="forest"] {
  --color-primary: oklch(0.5 0.18 145);
  --color-secondary: oklch(0.6 0.12 120);
  --color-accent: oklch(0.75 0.15 85);
}

[data-theme="sunset"] {
  --color-primary: oklch(0.6 0.22 25);
  --color-secondary: oklch(0.7 0.2 45);
  --color-accent: oklch(0.8 0.18 65);
}

<html data-theme="ocean">
  <body>
    <button class="bg-primary theme-forest:bg-primary">
      Uses ocean primary, unless explicitly overridden
    </button>
  </body>
</html>

JavaScript Theme Switcher

const themes = ['default', 'ocean', 'forest', 'sunset'];

function setTheme(theme) {
  if (theme === 'default') {
    document.documentElement.removeAttribute('data-theme');
  } else {
    document.documentElement.setAttribute('data-theme', theme);
  }
  localStorage.setItem('theme', theme);
}

function initTheme() {
  const saved = localStorage.getItem('theme') || 'default';
  setTheme(saved);
}

// Theme picker component
function ThemePicker() {
  return `
    <select onchange="setTheme(this.value)">
      ${themes.map(t => `<option value="${t}">${t}</option>`).join('')}
    </select>
  `;
}

initTheme();

Component Token System

Design Tokens for Components

@theme {
  /* Button tokens */
  --button-padding-x: var(--spacing-4);
  --button-padding-y: var(--spacing-2);
  --button-radius: var(--radius-lg);
  --button-font-weight: 500;
  --button-transition: all 150ms ease;

  /* Input tokens */
  --input-padding-x: var(--spacing-3);
  --input-padding-y: var(--spacing-2);
  --input-radius: var(--radius-md);
  --input-border-width: 1px;
  --input-focus-ring-width: 2px;
  --input-focus-ring-offset: 2px;

  /* Card tokens */
  --card-padding: var(--spacing-6);
  --card-radius: var(--radius-xl);
  --card-shadow: var(--shadow-md);
  --card-border-width: 1px;

  /* Modal tokens */
  --modal-padding: var(--spacing-6);
  --modal-radius: var(--radius-2xl);
  --modal-max-width: 32rem;
  --modal-backdrop-opacity: 0.5;
}

@layer components {
  .btn {
    padding: var(--button-padding-y) var(--button-padding-x);
    border-radius: var(--button-radius);
    font-weight: var(--button-font-weight);
    transition: var(--button-transition);
  }

  .input {
    padding: var(--input-padding-y) var(--input-padding-x);
    border-radius: var(--input-radius);
    border-width: var(--input-border-width);
  }

  .input:focus {
    outline: none;
    ring-width: var(--input-focus-ring-width);
    ring-offset: var(--input-focus-ring-offset);
  }

  .card {
    padding: var(--card-padding);
    border-radius: var(--card-radius);
    box-shadow: var(--card-shadow);
    border-width: var(--card-border-width);
  }
}

Responsive Design Tokens

Fluid Typography

@theme {
  /* Fluid type scale using clamp() */
  --text-fluid-xs: clamp(0.64rem, 0.5rem + 0.5vw, 0.75rem);
  --text-fluid-sm: clamp(0.8rem, 0.7rem + 0.5vw, 0.875rem);
  --text-fluid-base: clamp(1rem, 0.9rem + 0.5vw, 1.125rem);
  --text-fluid-lg: clamp(1.25rem, 1rem + 1vw, 1.5rem);
  --text-fluid-xl: clamp(1.5rem, 1.2rem + 1.5vw, 2rem);
  --text-fluid-2xl: clamp(2rem, 1.5rem + 2vw, 3rem);
  --text-fluid-3xl: clamp(2.5rem, 1.8rem + 3vw, 4rem);
  --text-fluid-4xl: clamp(3rem, 2rem + 4vw, 5rem);
}

@utility text-fluid-xs { font-size: var(--text-fluid-xs); }
@utility text-fluid-sm { font-size: var(--text-fluid-sm); }
@utility text-fluid-base { font-size: var(--text-fluid-base); }
@utility text-fluid-lg { font-size: var(--text-fluid-lg); }
@utility text-fluid-xl { font-size: var(--text-fluid-xl); }
@utility text-fluid-2xl { font-size: var(--text-fluid-2xl); }
@utility text-fluid-3xl { font-size: var(--text-fluid-3xl); }
@utility text-fluid-4xl { font-size: var(--text-fluid-4xl); }

Fluid Spacing

@theme {
  /* Fluid spacing using clamp() */
  --space-fluid-xs: clamp(0.25rem, 0.2rem + 0.25vw, 0.5rem);
  --space-fluid-sm: clamp(0.5rem, 0.4rem + 0.5vw, 1rem);
  --space-fluid-md: clamp(1rem, 0.8rem + 1vw, 2rem);
  --space-fluid-lg: clamp(2rem, 1.5rem + 2vw, 4rem);
  --space-fluid-xl: clamp(4rem, 3rem + 4vw, 8rem);
  --space-fluid-2xl: clamp(6rem, 4rem + 6vw, 12rem);
}

@utility p-fluid-xs { padding: var(--space-fluid-xs); }
@utility p-fluid-sm { padding: var(--space-fluid-sm); }
@utility p-fluid-md { padding: var(--space-fluid-md); }
@utility p-fluid-lg { padding: var(--space-fluid-lg); }
@utility p-fluid-xl { padding: var(--space-fluid-xl); }

@utility gap-fluid-xs { gap: var(--space-fluid-xs); }
@utility gap-fluid-sm { gap: var(--space-fluid-sm); }
@utility gap-fluid-md { gap: var(--space-fluid-md); }
@utility gap-fluid-lg { gap: var(--space-fluid-lg); }

Brand Color Generation

Generating Color Scales from Brand Color

@theme {
  /* Start with your brand color */
  --brand-hue: 250;
  --brand-chroma: 0.2;

  /* Generate full scale */
  --color-brand-50: oklch(0.97 calc(var(--brand-chroma) * 0.1) var(--brand-hue));
  --color-brand-100: oklch(0.93 calc(var(--brand-chroma) * 0.2) var(--brand-hue));
  --color-brand-200: oklch(0.87 calc(var(--brand-chroma) * 0.4) var(--brand-hue));
  --color-brand-300: oklch(0.78 calc(var(--brand-chroma) * 0.6) var(--brand-hue));
  --color-brand-400: oklch(0.68 calc(var(--brand-chroma) * 0.8) var(--brand-hue));
  --color-brand-500: oklch(0.58 var(--brand-chroma) var(--brand-hue));
  --color-brand-600: oklch(0.5 var(--brand-chroma) var(--brand-hue));
  --color-brand-700: oklch(0.42 calc(var(--brand-chroma) * 0.9) var(--brand-hue));
  --color-brand-800: oklch(0.35 calc(var(--brand-chroma) * 0.75) var(--brand-hue));
  --color-brand-900: oklch(0.28 calc(var(--brand-chroma) * 0.6) var(--brand-hue));
  --color-brand-950: oklch(0.2 calc(var(--brand-chroma) * 0.4) var(--brand-hue));
}

Monorepo Design System

Shared Design Tokens Package

packages/
  design-tokens/
    tokens.css
    package.json
  ui-components/
    src/
    package.json
apps/
  web/
  mobile/

packages/design-tokens/tokens.css:

/* Exportable design tokens */
@theme {
  /* All your design tokens here */
  --color-brand-500: oklch(0.58 0.2 250);
  /* ... */
}

packages/design-tokens/package.json:

{
  "name": "@mycompany/design-tokens",
  "version": "1.0.0",
  "exports": {
    ".": "./tokens.css"
  }
}

apps/web/app.css:

@import "tailwindcss";
@import "@mycompany/design-tokens";

Best Practices

1. Use Semantic Naming

/* Good - Semantic names */
--color-text-primary
--color-surface-elevated
--color-action-primary

/* Avoid - Raw values */
--color-gray-900
--color-white
--color-blue-500

2. Document Token Purpose

@theme {
  /*
   * Surface colors for backgrounds
   * primary: Main page background
   * raised: Cards and elevated elements
   * sunken: Inset areas like inputs
   */
  --color-surface-primary: oklch(1 0 0);
  --color-surface-raised: oklch(0.98 0 0);
  --color-surface-sunken: oklch(0.96 0 0);
}

3. Create Token Aliases

@theme {
  /* Base tokens */
  --color-blue-500: oklch(0.58 0.2 250);

  /* Semantic aliases */
  --color-primary: var(--color-blue-500);
  --color-link: var(--color-blue-500);
  --color-focus-ring: var(--color-blue-500);
}

4. Version Your Design System

Keep design tokens in version control and document changes:

/*
 * Design System v2.0.0
 * Breaking changes:
 * - Renamed --color-gray-* to --color-neutral-*
 * - Updated primary color to new brand guidelines
 */