tailwind

Tailwind

Contents: units; Colors; cn; Conditional classes; Variants with cva; Custom Values; When to create a role token.

units

Always use Tailwind units first. Custom values are a last resort (see Custom Values) and always rem, never px.

// BAD - tailwind units available but custom rem used
return <div className="p-[1.0625rem]" />;

// GOOD - uses tailwind units
return <div className="p-4.25" />;

Colors

Every color is a theme role token (bg-background, text-foreground, text-muted-foreground, bg-primary, text-primary-foreground, border-input, text-destructive), never a raw palette class or an arbitrary color. The contract and where the token list lives: frontend/.claude/rules/tailwind.md. The light and dark values live in the token, so write one utility, not a dark: pair.

// BAD, raw palette classes and a dark: pair
return <p className="bg-white text-gray-900 dark:bg-gray-900 dark:text-white" />;

// GOOD, role tokens carry both themes
return <p className="bg-background text-foreground" />;

cn

cn is the only class utility. Use it to combine class names in React components instead of template literals or array joins.

import {cn} from 'cn';

cn joins its arguments and merges conflicting utilities, so a component default can be overridden by a caller. Put the caller's className last: the later class wins on conflict.

import {cn} from 'cn';

// BAD, template literals with potential conflicts
return <span className={`bg-muted ${isActive ? 'bg-accent' : ''}`} />;

// GOOD, cn skips falsy values and resolves conflicts
return <span className={cn('text-foreground', isActive && 'bg-accent')} />;

// GOOD, callers can override component defaults
const Badge = ({className}: {className?: string}) => (
  <span className={cn('bg-muted px-4 py-2 text-foreground', className)} />
);

// bg-accent wins, cn removes the conflicting bg-muted
<Badge className="bg-accent" />;

Conditional classes