Tailwind CSS v4 Best Practices

Documentation snapshot: Tailwind CSS v4.3.3, verified against the npm latest tag and official documentation on 2026-08-29. Recheck https://tailwindcss.com/docs and the npm tag when the user asks for the latest version.

Tailwind v4 is CSS-first: @theme defines design tokens, @utility registers utilities, and @custom-variant registers variants. Legacy JavaScript configuration is still available through @config, but it is not detected automatically and some v3 options are unsupported.

Working Method

1. Inspect the project before editing. Identify the installed tailwindcss version, package manager, build integration, main CSS entry point, legacy config or plugins, source roots, and existing design tokens/components. Do not upgrade a project merely because this skill documents a newer version.
2. Choose the integration that matches the stack. Prefer the framework's official guide when one exists. Use @tailwindcss/vite for Vite-based stacks, @tailwindcss/postcss for PostCSS-based stacks such as Next.js, @tailwindcss/webpack as a webpack loader, or @tailwindcss/cli for a standalone build. Read installation before changing build configuration.
3. Use the smallest styling mechanism that fits. Prefer an existing utility or component; use an arbitrary value for a true one-off; add an @theme token when a design value is reused; add @utility only for a reusable CSS capability; use custom CSS for third-party overrides or rules that are clearer as CSS.
4. Keep candidates statically detectable. Map props and states to complete class strings. Do not construct fragments such as `bg-${color}-500`. Read source detection for monorepos, external packages, exclusions, and safelists.
5. Preserve the existing design system. Reuse its spacing, color, typography, radius, component, and class-merging conventions. Avoid introducing arbitrary values when a matching token already exists.
6. Verify the observable result. Run the relevant build/type/lint/tests, confirm expected utilities appear in compiled CSS when detection is in question, and inspect responsive, state, dark-mode, focus, and reduced-motion behavior in the rendered UI when applicable.

v4.3 Additions