Design Tokens

When to Use

• "What color should I use?" → Look up semantic color tokens
• "How much padding?" → Check spacing scale
• "What font size for this?" → Reference typography tokens
• "What's the right corner radius?" → Use radius tokens
• "Does this meet dark mode?" → Review dark mode overrides
• "How do I add interactivity?" → Use shadows + transitions + hover states
• Brand consistency check → Ensure all components use tokens, not magic numbers
• Onboarding designers → Show Figma/design mapping to code tokens

Token Categories

Colors

Complete color reference with:

• Semantic names: --color-primary, --color-success, --color-text, --color-surface
• HSL values for each token
• Light and dark mode variants
• Visual swatches (usage in browser)
• Accessibility notes (contrast ratios)

Typography

Typography scale:

• Font sizes: --font-size-xs, --font-size-sm, --font-size-base, --font-size-md, --font-size-lg, --font-size-xl, --font-size-2xl, --font-size-3xl, --font-size-4xl
• Font weights: --font-weight-normal, --font-weight-medium, --font-weight-semibold, --font-weight-bold
• Line heights: --line-height-tight, --line-height-snug, --line-height-normal, --line-height-relaxed, --line-height-loose
• Letter spacing: --tracking-tight, --tracking-normal, --tracking-wide

Spacing

Spacing scale:

• Consistent scale: xs (0.25rem), sm (0.5rem), md (1rem), lg (1.5rem), xl (2rem), 2xl (3rem), 3xl (4rem), 4xl (6rem), 5xl (8rem)
• Used in padding, margins, gaps
• Always prefer token values over hardcoded pixels

Radii

Border radius scale:

• --radius-sm (0.25rem), --radius-md (0.375rem), --radius-lg (0.5rem), --radius-xl (0.75rem), --radius-2xl (1rem), --radius-full (9999px)
• Use rounded-sm, rounded-md, rounded-lg, rounded-xl, rounded-2xl, rounded-full (all mapped in tailwind.config.js)

CSS Variables in tokens/

Location: src/styles/tokens/ (split by category)

All token files are imported via src/styles/tokens/index.css:

/* src/styles/tokens/colors.css */
:root {
  /* Colors - Light mode */
  --color-primary: hsl(119 43% 52%);
  --color-success: hsl(119 43% 45%);
  --color-warning: hsl(45 93% 56%);
  --color-error: hsl(0 84% 60%);
  --color-text: hsl(210 12% 18%);
  --color-text-muted: hsl(210 10% 52%);
  --color-surface: hsl(210 20% 100%);
  --color-border: hsl(210 16% 90%);

  /* Spacing */
  --spacing-sm: 0.5rem;
  --spacing-md: 1rem;
  --spacing-lg: 1.5rem;

  /* Typography */
  --font-sans: system-ui, "Segoe UI", sans-serif;
  --font-size-base: 1rem;
  --font-size-md: 1.125rem;

  /* Radii */
  --radius-sm: 0.25rem;
  --radius-md: 0.375rem;
  --radius-lg: 0.5rem;
  --radius-full: 9999px;
}

/* src/styles/tokens/themes.css */
.dark {
  --color-text: hsl(210 20% 96%);
  --color-surface: hsl(210 15% 12%);
  --color-border: hsl(210 10% 32%);
}

Using Tokens in Components

❌ DON'T: Use Hardcoded Sizes or Magic Numbers

// Hardcoded sizes – hard to maintain and breaks design consistency
<button className="bg-green-500 text-white px-4 py-2 text-sm rounded-lg">
  Click me
</button>

// Magic colors – inconsistent across dark mode
<div style={{ color: '#333333', backgroundColor: '#f0f0f0', padding: '12px' }}>
  Content
</div>

✅ DO: Use Tailwind Extended Config Class Names

All tokens are mapped in tailwind.config.js. Use the named Tailwind utilities — not CSS variable access syntax.

// Colors, spacing, typography, and radius via Tailwind extended config
<button className="bg-primary-500 text-white px-md py-sm text-sm rounded-lg font-semibold">
  Click me
</button>

// Complete semantic styling
<div className="bg-surface p-md rounded-lg border border-base">
  <h3 className="text-lg font-semibold mb-md">
    Heading
  </h3>
  <p className="text-sm text-secondary leading-normal">
    Body text with proper typography tokens.
  </p>
</div>

Token → Tailwind class quick reference (from tailwind.config.js):

* text-base sets both color: var(--color-text) and font-size: var(--font-size-base). Use text-(--color-text) when you only want the color with a different size.

✅ DO: Use CSS Variables Only for Unmapped Tokens

Some tokens have no Tailwind class mapping (hover/active states, foreground pairs, surface-hover). Use CSS var syntax only for these:

// Unmapped tokens — CSS var syntax is correct here
<button
  className="bg-primary-500 hover:bg-(--color-primary-hover) active:bg-(--color-primary-active)"
>
  Click me
</button>

// Inline styles: use CSS vars when Tailwind utilities aren't applicable
<div
  style={{
    borderColor: "var(--color-border)",   // prefer border-base in className
    backgroundColor: "var(--color-surface-hover)",  // no Tailwind mapping
  }}
>
  Content
</div>

Unmapped tokens (CSS var syntax required):

• --color-primary / --color-primary-hover / --color-primary-active / --color-primary-foreground
• --color-secondary / --color-secondary-hover / --color-secondary-foreground
• --color-surface-hover

✅ DO: Use Tokens in CVA (Class Variance Authority)

// Use Tailwind extended class names from tailwind.config.js, not CSS var syntax
import { cva } from "class-variance-authority";

export const buttonVariants = cva(
  [
    "inline-flex items-center justify-center",
    "font-semibold",
    "rounded-lg",
    "transition-all duration-200",
  ].join(" "),
  {
    variants: {
      variant: {
        primary:
          // bg-primary-500 is the Tailwind mapped ramp class; hover uses unmapped token
          "bg-primary-500 text-white hover:bg-(--color-primary-hover)",
        outline: "border border-base text-(--color-text) hover:bg-muted",
      },
      size: {
        sm: "px-sm py-xs text-sm",
        md: "px-md py-sm text-base",
        lg: "px-lg py-md text-md",
      },
    },
  },
);

Prefer Tailwind utilities (Method 1) for consistency.

Dark Mode Strategy

Dark mode is controlled by Tailwind's darkMode: 'class' strategy. Add or remove the .dark class on <html> to switch themes. The color overrides live in src/styles/tokens/themes.css.

// Toggle dark mode
document.documentElement.classList.toggle("dark");

// Restore persisted preference on load
if (localStorage.getItem("theme") === "dark") {
  document.documentElement.classList.add("dark");
}

This gives users explicit control independent of their OS preference.

Testing in browser DevTools:

1. DevTools → Console: document.documentElement.classList.add('dark')
2. Toggle between light and dark
3. Observe color changes without page reload

Dark mode implementation guide

Tailwind Integration

The tailwind.config.js extends Tailwind's theme to map all design tokens to named utility classes. Always prefer these class names over CSS variable access syntax.

// tailwind.config.js (simplified)
export default {
  theme: {
    extend: {
      backgroundColor: { base: "var(--color-bg)", surface: "var(--color-surface)", muted: "var(--color-muted-bg)" },
      textColor:       { base: "var(--color-text)", secondary: "var(--color-text-secondary)", muted: "var(--color-text-muted)", light: "var(--color-text-light)" },
      borderColor:     { base: "var(--color-border)", muted: "var(--color-border-muted)" },
      colors:          { success: "var(--color-success)", error: "var(--color-error)", warning: "var(--color-warning)", info: "var(--color-info)" },
      spacing:         { xs: "var(--spacing-xs)", sm: "var(--spacing-sm)", md: "var(--spacing-md)", lg: "var(--spacing-lg)", ... },
      borderRadius:    { sm: "var(--radius-sm)", md: "var(--radius-md)", lg: "var(--radius-lg)", ... },
      fontSize:        { xs: "var(--font-size-xs)", sm: "var(--font-size-sm)", base: "var(--font-size-base)", lg: "var(--font-size-lg)", ... },
      fontWeight:      { normal: "var(--font-weight-normal)", semibold: "var(--font-weight-semibold)", bold: "var(--font-weight-bold)" },
    },
  },
};

See Tailwind Integration Reference for the complete class mapping table.

Micro-Interactions: Standardized Active Scale

All interactive components use a consistent active:scale-[0.98] pattern for button press feedback. This simulates tactile interaction feedback and aligns with modern app standards (Material Design, Figma, Slack).

Standard Pattern (Buttons, Inputs, Dialogs):

className="
  shadow-sm hover:shadow-md active:shadow-lg
  transition-all duration-200 ease-out
  active:scale-[0.98]
  focus-visible:ring-2 focus-visible:ring-(--color-primary)
"

Why 0.98? — Subtle (noticeable but natural), matches Google Material Design and modern UX best practices. Tested extensively across device types for universal perceived smoothness.

See: Micro-Interactions Reference for complete pattern, rationale, component mapping, and testing guide.

References

• Color Tokens — All colors with swatches
• Spacing Scale — All spacing values
• Typography — Font sizes and weights
• Dark Mode Guide — How system dark mode works
• Tailwind + Tokens — Using tokens in utilities
• Accessibility Notes — Color contrast, semantics
• Micro-Interactions — Active state scale, transitions, and best practices

Procedure: Add a New Token

1. Identify the token: semantic name (e.g., --color-info)
2. Set light mode value in :root { }
3. Set dark mode override in @media (prefers-color-scheme: dark) { }
4. Document in reference with use case and swatches
5. Update Tailwind config if Tailwind-exposed
6. Test in both light and dark modes

Example:

/* In tokens.css */
:root {
  --color-info: hsl(200 100% 54%);
}

@media (prefers-color-scheme: dark) {
  :root {
    --color-info: hsl(200 100% 60%);
  }
}

/* In Tailwind config */