Tailwind v4 Style

Conventions for Tailwind CSS v4. Configuration is CSS-first via @theme, design tokens are native CSS variables, and the JavaScript config file is gone.

Tailwind v4 is a ground-up rewrite: full builds run ~3.5-5x faster and incremental rebuilds with no new CSS complete in microseconds. The developer-facing changes are large enough to be a style break from v3. Source: Tailwind, https://tailwindcss.com/blog/tailwindcss-v4, 2026-05-31

Install with one line

Import the framework in your single global stylesheet, not via @tailwind base/components/utilities:

@import "tailwindcss";

Use the first-party Vite plugin (@tailwindcss/vite) where possible. Content paths are detected automatically, do not hand-maintain a content array. Source: Tailwind v4 release, 2026-05-31

Configure in CSS, not JS

There is no tailwind.config.js by default. Define tokens in @theme inside globals.css, which is exactly the file CSS UI Enforcement says owns global concerns:

@theme {
  --color-brand: oklch(0.62 0.19 256);
  --font-display: "Inter", sans-serif;
  --spacing: 0.25rem;
}

Every theme variable is emitted as a real CSS custom property, so tokens are reachable as var(--color-brand) anywhere, including inline SVG and third-party components. Derive utilities from tokens; do not duplicate hex values in markup. Source: Tailwind v4 release, 2026-05-31

Use the modern-web features

• P3 / oklch palette - the default palette is wider-gamut; author custom colors in oklch() to match (see Frontend and Design Skills).
• Container queries are first-class - use @container and @sm:/@md: variants instead of plugins.
• Dynamic utility values - arbitrary spacing and grid values work without extending config.
• Custom utilities - register with @utility, not @layer utilities plus a plugin; add variants with @variant.
• New not-* variant, @starting-style for JS-free enter/exit transitions, and 3D transform utilities are available, prefer them over hand-rolled CSS.

Source: Tailwind v4 release, 2026-05-31

Hold the line on the house rules

v4 does not change Kevin's CSS policy: style with className={cn(...)}, keep raw CSS in globals.css only, and never mix style={{}} with Tailwind on one node (see CSS UI Enforcement). v4 actually strengthens this, because @theme, @utility, and keyframes all live in that one global file.

Project Contract

Proof

After Tailwind config changes, render at least one component consuming the new token or utility. A token that exists only in CSS but no component uses is a style-system TODO, not a finished rule.

Style Rule Contract

This page follows Style Rule Contract: name the default pattern, banned pattern, reason, exception, proof, and codification path clearly enough that the next agent can apply the rule without asking Kevin again. If a local repo has a stricter rule, follow the local rule and update the wiki when the decision becomes durable.

---

Timeline

• 2026-07-01 | Aligned this page with Style Rule Contract so style guidance names default behavior, banned patterns, exceptions, proof, and codification expectations. Source: User request, 2026-07-01
• 2026-07-01 | Added project-contract and proof sections for Tailwind v4 install, token, utility, container-query, color, and rendered-usage rules. Source: User request, 2026-07-01
• 2026-05-31 | Page created from the Tailwind CSS v4.0 release notes. Captured the single-line @import, CSS-first @theme configuration, tokens-as-CSS-variables, automatic content detection, container queries, oklch palette, and @utility, aligned with CSS UI Enforcement globals ownership. Source: https://tailwindcss.com/blog/tailwindcss-v4, 2026-05-31