Version history: Tailwind CSS
v1
scan: pass2026-08-11 — Ingested from sourceInitial version.
v2
currentscan: pass2026-11-02 — Currency pass 2026-11-01: rewritten for Tailwind CSS v4. Replaced tailwind.config.js, content arrays and PurgeCSS guidance with @import "tailwindcss", @theme tokens, automatic content detection, @source, and @tailwindcss/vite or @tailwindcss/postcss; dark mode via @custom-variant; @config kept only as a legacy bridge; focus-visible rings. Frontmatter globs made valid YAML.---- description: Provides definitive best practices for using Tailwind CSS, focusing on maintainability, performance, and scalability in modern web development. - globs: **/*.{css,html,jsx,tsx,vue}+ description: "Tailwind CSS v4 best practices: CSS-first theme tokens, component abstraction, class ordering, mobile-first layout, accessibility, and dark mode." + globs: "**/*.{html,js,jsx,ts,tsx,vue,svelte,css}" + alwaysApply: false --- # tailwind Best Practices - Tailwind CSS is a powerful utility-first framework. These rules ensure our projects leverage Tailwind effectively, promoting consistency, performance, and maintainability across the team.+ Tailwind CSS is a powerful utility-first framework. These rules target Tailwind CSS v4 and ensure our projects leverage Tailwind effectively, promoting consistency, performance, and maintainability across the team. - ## 1. Design System Configuration+ ## 1. Design System Configuration (CSS-first) - **Always define your design system in `tailwind.config.js`.** Avoid arbitrary values in markup unless absolutely necessary for unique, non-reusable styles. This ensures UI consistency and enables efficient PurgeCSS tree-shaking.+ **Define your design system as theme tokens in your main CSS file with `@theme`.** Tailwind v4 is configured in CSS: one `@import "tailwindcss";` replaces the old `@tailwind base/components/utilities` directives, and `@theme` variables generate both utilities and CSS custom properties. There is no `tailwind.config.js` by default. Avoid arbitrary values in markup unless absolutely necessary for unique, non-reusable styles. ❌ BAD: Arbitrary values in markup ```html <div class="bg-[#1a2b3c] text-[15px] p-[1.25rem] rounded-[8px]">...</div> ``` - ✅ GOOD: Configured design tokens - ```js - // tailwind.config.js - module.exports = { - theme: { - extend: { - colors: { - brand: { 500: '#1a2b3c' }, - }, - fontSize: { - 'body-md': '15px', - }, - spacing: { - 'layout-sm': '1.25rem', - }, - borderRadius: { - 'card': '8px', - }, - }, - }, - };+ ✅ GOOD: Theme tokens defined once in CSS + ```css + /* src/app.css */ + @import "tailwindcss"; + + @theme { + --color-brand-500: #1a2b3c; + --text-body-md: 15px; + --spacing-layout-sm: 1.25rem; + --radius-card: 8px; + } ``` ```html <div class="bg-brand-500 text-body-md p-layout-sm rounded-card">...</div> ``` + Tokens are also available as plain CSS variables (`var(--color-brand-500)`) for the rare custom CSS you still write. Only reach for a JavaScript config when migrating a legacy v3 project; load it with `@config "./tailwind.config.js";` in your CSS and move its `theme.extend` values into `@theme` over time. + ## 2. Component Abstraction **Extract reusable UI patterns into framework-specific components.** This keeps your markup clean, promotes reusability, and centralizes complex styling logic. Use libraries like `clsx` or `cva` for dynamic class composition. - **Avoid `@apply` for general component styling.** It creates custom CSS that hides Tailwind's utility-first nature, making refactoring harder and reducing clarity. Reserve `@apply` for very specific, non-reusable base styles (e.g., resetting browser defaults) or legacy migrations.+ **Avoid `@apply` for general component styling.** It creates custom CSS that hides Tailwind's utility-first nature, making refactoring harder and reducing clarity. Reserve `@apply` for very specific, non-reusable base styles (e.g., resetting browser defaults) or legacy migrations. In v4, `@apply` inside a separately imported CSS file needs `@reference "./app.css";` to see your theme. ❌ BAD: Duplicated utility soup in every instance ```html <button class="bg-blue-500 hover:bg-blue-700 text-white font-bold py-2 px-4 rounded focus:outline-hidden focus:ring-2 focus:ring-blue-500/50"> Submit </button> <!-- ... many more buttons with the exact same classes ... --> ``` ✅ GOOD: Reusable component (React example)- ```jsx - // components/Button.jsx+ ```tsx + // components/Button.tsx import clsx from 'clsx'; export function Button({ variant = 'primary', size = 'md', className, ...props }) { const baseStyles = 'font-bold py-2 px-4 rounded focus:outline-hidden focus:ring-2'; const variantStyles = { primary: 'bg-blue-500 hover:bg-blue-700 text-white focus:ring-blue-500/50', secondary: 'bg-gray-200 hover:bg-gray-300 text-gray-800 focus:ring-gray-300/50', }; const sizeStyles = { sm: 'text-sm', md: 'text-base', }; return ( <button className={clsx(baseStyles, variantStyles[variant], sizeStyles[size], className)} {...props} /> ); } ```- ```jsx+ ```tsx // Usage <Button>Submit</Button> <Button variant="secondary">Cancel</Button> ``` ## 3. Class Ordering & Readability - **Group utility classes logically for improved readability.** While Tailwind doesn't enforce an order, a consistent pattern makes scanning classes easier and reduces cognitive load. We recommend:+ **Group utility classes logically for improved readability.** While Tailwind doesn't enforce an order, a consistent pattern makes scanning classes easier and reduces cognitive load. Install `prettier-plugin-tailwindcss` so the order is applied automatically on save; it sorts in the same order Tailwind emits the CSS: `Layout` > `Flexbox` > `Grid` > `Box Model (p, m, w, h)` > `Typography` > `Backgrounds` > `Borders` > `Effects` > `Interactivity` > `States (hover, focus, active, responsive)` ❌ BAD: Random order ```html <div class="text-lg flex shadow-md p-4 items-center bg-white rounded-lg">...</div> ``` ✅ GOOD: Consistent order ```html <div class="flex items-center p-4 bg-white rounded-lg shadow-md text-lg">...</div> ``` ## 4. Mobile-First & Responsive Design - **Adopt a mobile-first approach.** Design for the smallest screen first, then use responsive prefixes (`sm:`, `md:`, `lg:`, `xl:`, `2xl:`) to adapt styles for larger viewports. This is the default and most efficient way to build responsive UIs with Tailwind.+ **Adopt a mobile-first approach.** Design for the smallest screen first, then use responsive prefixes (`sm:`, `md:`, `lg:`, `xl:`, `2xl:`) to adapt styles for larger viewports. This is the default and most efficient way to build responsive UIs with Tailwind. Use container queries (`@container` on the parent, `@md:` variants on children) when a component should respond to its container rather than the viewport. ```html <!-- Default (mobile) is stacked, medium screens and up are side-by-side --> <div class="flex flex-col md:flex-row items-center md:items-start gap-4"> <img class="w-24 h-24 rounded-full md:w-32 md:h-32" src="..." alt="Profile"> <div class="text-center md:text-left"> <h2 class="text-xl md:text-2xl font-bold">John Doe</h2> <p class="text-gray-600 md:text-lg">Software Engineer</p> </div> </div> ``` - ## 5. Performance Optimization+ ## 5. Build Setup & Performance - **Configure `content` for PurgeCSS and leverage JIT.** Ensure your `tailwind.config.js` accurately lists *all* files containing Tailwind classes. This is critical for PurgeCSS to tree-shake unused CSS, keeping your bundle size minimal. Tailwind v4 uses the Just-In-Time (JIT) engine by default, providing fast compilation.+ **Use the first-party build integration and let Tailwind find your classes.** Tailwind v4 scans your project automatically (respecting `.gitignore` and skipping binaries), so there is no `content` array to maintain and no separate purge step; only the classes you actually use are generated. - ```js - // tailwind.config.js - module.exports = { - content: [ - './src/**/*.{js,jsx,ts,tsx,vue,html}', // Your source files - './public/index.html', // Any raw HTML files - ], - theme: { extend: {} }, - plugins: [], - };+ * **Vite**: add `@tailwindcss/vite` to `plugins` in `vite.config.ts`. + * **Everything else**: add `@tailwindcss/postcss` to your PostCSS config (no `autoprefixer` or `postcss-import` needed; v4 handles both). + * **Classes in unusual places** (a package in `node_modules`, generated files): register them explicitly with `@source "../node_modules/my-ui-lib";` in your CSS instead of relying on detection. + * **Do not build class names dynamically** (`` `bg-${color}-500` ``): the scanner only finds complete strings in source. Map values to full class names instead. + + ```css + /* src/app.css */ + @import "tailwindcss"; + @source "../node_modules/@acme/ui"; ``` - **Keep Tailwind updated.** Use `npx @tailwindcss/upgrade` to migrate from v3 to v4, benefiting from performance improvements and modern CSS features. Be aware of v4's modern browser requirements (Safari 16.4+, Chrome 111+, Firefox 128+).+ **Keep Tailwind updated.** Use `npx @tailwindcss/upgrade` to migrate from v3 to v4; it rewrites the config, directives, and renamed utilities (e.g., `shadow-sm` → `shadow-xs`, `outline-none` → `outline-hidden`). Be aware of v4's modern browser requirements (Safari 16.4+, Chrome 111+, Firefox 128+). ## 6. Accessibility **Prioritize semantic HTML.** Tailwind styles should enhance, not replace, proper HTML structure. Ensure all interactive elements have clear, visible focus states. **`outline-hidden` vs `outline-none` (Tailwind v4):** * **`outline-hidden`**: Sets an invisible outline that *still shows in forced colors mode* for accessibility. **Prefer this for interactive elements** when you want to hide the default browser outline but ensure accessibility. * **`outline-none`**: Sets `outline-style: none`, completely removing the outline. **Avoid this for interactive elements** unless you provide a custom, accessible focus indicator (e.g., `focus:ring-2`). + Prefer `focus-visible:` over `focus:` for ring styles so mouse users do not see keyboard focus rings. + ❌ BAD: Removing focus entirely ```html <button class="focus:outline-none">Click me</button> ``` ✅ GOOD: Accessible focus state ```html- <button class="focus:outline-hidden focus:ring-2 focus:ring-blue-500/50">Click me</button>+ <button class="focus:outline-hidden focus-visible:ring-2 focus-visible:ring-blue-500/50">Click me</button> ``` ## 7. Theming & Dark Mode - **Extend your `tailwind.config.js` for custom themes.** Define custom colors, fonts, spacing, and other design tokens to match your brand. Leverage the `dark:` variant for built-in dark mode support.+ **Extend your theme in CSS.** Define custom colors, fonts, spacing, and other design tokens in `@theme` to match your brand. The `dark:` variant uses `prefers-color-scheme` by default; switch it to a class or data attribute with `@custom-variant` when users can toggle the theme manually. - ```js - // tailwind.config.js - module.exports = { - darkMode: 'class', // or 'media' - theme: { - extend: { - colors: { - 'primary-light': '#f0f9ff', - 'primary-dark': '#0c4a6e', - }, - }, - }, - };+ ```css + /* src/app.css */ + @import "tailwindcss"; + + /* Class-based dark mode instead of the default media query */ + @custom-variant dark (&:where(.dark, .dark *)); + + @theme { + --color-primary-light: #f0f9ff; + --color-primary-dark: #0c4a6e; + --font-sans: "Inter", ui-sans-serif, system-ui, sans-serif; + } ``` ```html <div class="bg-primary-light dark:bg-primary-dark text-gray-900 dark:text-gray-100"> Hello, world! </div>- ```+ ```