Tailwind CSS

Foundationv4.x

Utility-first CSS framework — build designs directly in your markup with CSS variables and modern features.

Read this to understand how Catalyst handles styling.
Useful when customizing the design system or adding new styles.

Why Tailwind CSS

Tailwind lets you build fast without leaving your HTML. Instead of writing CSS files, you apply utility classes directly to elements. This keeps styles colocated with components and makes it easy for AI agents to understand and modify designs.

Catalyst uses Tailwind v4, which introduces native CSS variables, better performance, and a simplified configuration. The design system is built on CSS custom properties, making theming straightforward.

Key Concepts

The Tailwind features Catalyst relies on:

CSS Variables

Design tokens as variables. Colors, spacing, and typography defined in CSS, used everywhere.

Dark Mode

Built-in dark mode. Toggle themes with the dark: variant and CSS variables.

Utility-First

Compose styles inline. No context switching between HTML and CSS files.

Catalyst Patterns

How Catalyst organizes styles:

CSS Variables (Critical)

Always use the --color- prefix for design tokens

/* Correct */
background: var(--color-background);
color: var(--color-primary);

/* Incorrect - won't work */
background: var(--background);

Transparency with OKLCH

Use oklch() for transparent colors

/* Correct - uses oklch for transparency */
background: oklch(from var(--color-primary) l c h / 0.1);

/* Incorrect - hsl/rgb don't work with CSS variables */
background: hsl(var(--primary) / 0.1);

The cn() Utility

Merge Tailwind classes without conflicts

import { cn } from "@/lib/utils"

// Merges classes and handles conflicts
<div className={cn(
  "p-4 bg-muted",
  isActive && "bg-primary text-primary-foreground",
  className
)} />

Key Files

app/globals.css

Root styles — imports design system, defines CSS variables

design/shared.css

Design tokens — colors, typography, shadows

design/animate.css

Animation utilities and keyframes

design/helpers.css

Utility classes for common patterns

tailwind.config.ts

Tailwind configuration (minimal in v4)

Color System

Catalyst uses semantic color tokens that adapt to light/dark mode:

--color-background

Page background

--color-foreground

Primary text

--color-primary

Brand/accent color

--color-primary-foreground

Text on primary

--color-muted

Subtle backgrounds

--color-muted-foreground

Secondary text

--color-border

Borders and dividers

--color-destructive

Error/danger states

See /docs/design/colors for the full color reference.

Tips

No spacing/radius variables. Use direct values like p-4, rounded-lg — Tailwind handles the rest.

Use bg-muted for subtle backgrounds. It adapts to light/dark mode automatically.

Prefer Tailwind over custom CSS. Only write custom CSS for complex animations or truly unique patterns.

Dark mode uses the .dark class. The next-themes package handles the toggle.

Learn More

Tailwind DocumentationColor CustomizationDark Mode Guide

For AI Agents

Key rules:

  • Always use --color- prefix for CSS variables
  • Use oklch(from var(--color-*) l c h / opacity) for transparency
  • Use cn() utility from @/lib/utils to merge classes
  • No spacing/radius CSS variables — use Tailwind classes directly
  • Read design/DESIGN.md for full conventions

Next Steps

Related foundation packages:

shadcn/ui

UI components styled with Tailwind.

Utility Packages

CVA, clsx, and tailwind-merge utilities.