Version history: Tailwind CSS

v1

scan: pass2026-08-11 — Ingested from source

Initial 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>- ```+ ```