RuleScan: pass
Tailwind CSS
Tailwind CSS v4 rule: CSS-first @theme tokens over arbitrary values, clsx/cva component abstraction, prettier class ordering, mobile-first and container queries, accessible focus styles, and dark mode via @custom-variant.
Add a trust badge to your README
[](https://waxmark.app/items/tailwind-2/scan)
---
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 target Tailwind CSS v4 and ensure our projects leverage Tailwind effectively, promoting consistency, performance, and maintainability across the team.
## 1. Design System Configuration (CSS-first)
**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: 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. 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)
```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}
/>
);
}
```
```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. 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. 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. Build Setup & Performance
**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.
* **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; 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-visible:ring-2 focus-visible:ring-blue-500/50">Click me</button>
```
## 7. Theming & Dark Mode
**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.
```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>
```