tailwind

name	tailwind
description	Patterns and conventions for all Tailwind styling. Use this skill whenever writing Tailwind class names, combining conditional classes, building component variants, or choosing between twJoin and twMerge. Also trigger when the user asks about custom values, defining @theme tokens or CSS variables, naming color/spacing tokens, rem vs px, responsive breakpoints, or avoiding template literal class strings.
model	haiku

Tailwind

units

Always use Tailwind units first. For custom values, always use 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" />;

tailwind-merge

Use tailwind-merge to concatenate class names in React components instead of template literals or array joins.

• twJoin: for conditional class combinations (no override needed)
• twMerge: allow class override (merges conflicting utilities; perfect for setting default and optional classes)

Examples

import {twMerge, twJoin} from 'tailwind-merge';

// BAD, template literals with potential conflicts
return <span className={`bg-gray-500 ${isBlue ? 'bg-blue-500' : ''}`} />;

// GOOD - twJoin for conditional classes, but no override needed
return <span className={twJoin('bg-gray-800', isBlue && 'text-blue-500')} />;

// GOOD, twMerge for override, twJoin for conditional classes
return <span className={twMerge('text-white', isBlue && 'text-blue-500')} />;

The key distinction: use twMerge when a component accepts a className prop that should be able to override defaults, twJoin would leave both conflicting classes on the element, but twMerge resolves the conflict:

// twMerge enables callers to override component defaults
function Button({className}: {className?: string}) {
  return (
    <button
      className={twMerge('bg-blue-500 px-4 py-2 text-white', className)}
    />
  );
}

// bg-red-500 wins, twMerge removes the conflicting bg-blue-500
<Button className="bg-red-500" />;

Conditional classes

Pass falsy values directly to twJoin / twMerge, they're skipped.

// correct
twJoin('base', isActive && 'bg-blue-500', error && 'border-red-500');

// ternaries that produce two positive values are fine
twJoin('base', condition ? 'a' : 'b');

Don't wrap class lists in template literals to concatenate, pass each class as a separate argument. Template literals inside twJoin / twMerge are acceptable only when interpolating a pre-built string from a lookup table (e.g., ICON_POSITION[iconPosition] from a Record<string, string>).

Variant / size lookup tables

Extract multi-class variant strings into Record constants at the top of the file, then reference them positionally, not via interpolation.

const VARIANTS: Record<Variant, string> = {
  primary: 'border border-blue-400 bg-blue-500 text-white ...',
  secondary: '...',
};

// usage
twJoin('rounded-sm px-3 py-2', VARIANTS[variant]);

Custom Values

When Tailwind's built-in scale doesn't have an exact value, use an arbitrary value with rem, never px:

// BAD, px unit
<p className="text-[9px]" />

// GOOD, rem unit
<p className="text-[0.5625rem]" />

Use arbitrary values sparingly. If the same custom value appears more than once, add it to the tailwind.css @theme instead.

Custom Theme Tokens

When adding @theme tokens to app/styles/tailwind.css, name them by role, not by the utility they'll be used with. The CSS variable suffix becomes the suffix on every generated utility (bg-, text-, border-, ring-, fill-, stroke-, from-, to-, etc.), so a token containing a utility prefix produces stuttering class names.

Lint check before naming: mentally expand bg-{name}, text-{name}, border-{name}. If any reads as a stutter or nonsense, rename.

/* BAD, produces bg-bg, text-bg, border-bg-tint, text-text-muted */
--color-bg: #141413;
--color-bg-tint: #181c1e;
--color-text: #e0e0e0;
--color-text-muted: #999;

/* GOOD, produces bg-canvas, bg-surface, text-ink, text-muted */
--color-canvas: #141413;
--color-surface: #181c1e;
--color-ink: #e0e0e0;
--color-muted: #999;

Role vocabulary that survives the lint check: canvas, surface, surface-raised, ink, muted, subtle, primary, brand-*, success, warning, danger, palette-style names like claude-500. Avoid token names starting with bg-, text-, border-, ring-, fill-, stroke-, from-, to-, outline-, shadow-.

For paired light/dark colors, prefer defining an @utility (like the existing bg-body, text-body) over a single @theme token, @utility binds two palette values together; a @theme token exposes one hex on every utility prefix.