Getting Started

Tailwind Classes

Our design tokens are CSS custom properties. Tailwind v4 exposes them as utility classes through the @theme inline directive in each app's globals.css. This page documents the full mapping from token name to utility class.

How it works

Tailwind v4 replaces the old tailwind.config.js approach with a CSS-first configuration. The @theme inline block maps named CSS custom properties to Tailwind color names. Any property you define there becomes a Tailwind utility automatically.

/* globals.css — simplified excerpt */
@import "tailwindcss";

/* Semantic tokens defined in .dark selector */
.dark {
  --background-default: hsl(0deg 0% 7.1%);
  --brand-default: hsl(153.1deg 60.2% 52.7%);
}

/* @theme inline maps CSS vars → Tailwind utilities */
@theme inline {
  --color-background: var(--background-default);
  /* bg-background is now available */

  --color-brand: var(--brand-default);
  /* bg-brand, text-brand, border-brand are all available */
}

Because the mapping is indirect (utility references a CSS var, which references another CSS var), swapping the entire theme at runtime is possible without touching the class names in JSX. The .dark selector changes the underlying values; the utilities stay the same.

Background utilities

Foreground utilities

The text-* utilities also work as bg-* and border-* where the token is mapped. For example, --color-foreground enables text-foreground, bg-foreground, and border-foreground simultaneously.

Border utilities

Brand utilities

Shorthands and aliases

Some utility names are deliberately short for readability in dense component code. These aliases are defined in the @theme inline block alongside the full names.

Opacity support

Because our tokens are exposed through @theme inline as color utilities, they support Tailwind's opacity modifier syntax out of the box. Use the slash notation to apply any opacity to any token-based color.

// Opacity modifier on any token-backed utility
<div className="bg-surface-300/90" />      // 90% opaque surface
<div className="bg-brand/10" />            // subtle brand tint
<div className="border-border/50" />       // half-opacity border
<div className="text-foreground/70" />     // slightly faded text

// Useful for focus rings
className="focus-visible:ring-2 focus-visible:ring-brand/40"

// Useful for overlay backgrounds
className="bg-black/60 backdrop-blur-sm"   // modal backdrop

Adding a new token

To add a new design token and make it available as a Tailwind utility, follow these three steps in apps/[app]/app/globals.css:

/* Step 1: Define the primitive value in :root or .dark */
.dark {
  --my-custom-token: hsl(200deg 80% 50%);
}

/* Step 2: Expose it in the @theme inline block */
@theme inline {
  --color-custom: var(--my-custom-token);
}

/* Step 3: Use it in JSX */
// <div className="bg-custom text-custom border-custom" />

Always define tokens in @repo/ui/theme.css if they should be shared across apps. App-specific overrides go in each app's own globals.css.