Tailwind v4 Theme Configuration

Instructions for declaring design tokens in Tailwind v4's root stylesheet and using them in components.
Published: 7/20/2026

Tailwind CSS v4 introduces theme configuration directly in CSS using the @theme directive, bypassing the legacy tailwind.config.js configuration.

Ensure all semantic colors and sizing values from the design system are mapped in this block, avoiding inline arbitrary values (e.g. bg-[#1a1a1a]).

warning
STRICT PROHIBITION: Do not use inline arbitrary color syntaxes like bg-[#3a3a3a] unless the token is missing. If a token does not exist, add it to index.css first.
index.css (css)
@import "tailwindcss";

@theme {
  --color-brand-accent: #0066cc;
  --color-brand-hover: #0052a3;
  --color-surface-base: #ffffff;
  --color-surface-muted: #f5f5f7;
  
  --spacing-xs: 0.25rem;
  --spacing-sm: 0.5rem;
  --spacing-md: 1rem;
  
  --radius-sm: 4px;
  --radius-md: 8px;
}
Tailwind CSS v4 theme variables declaration
SEO Title: Tailwind v4 Theme Configuration
SEO Description: Map semantic design tokens directly to Tailwind v4 CSS theme variables in your main styles file.
Index Alternates:tailwind v4css theme variablescss configuration