{"id":"5f03aa31-24b2-4593-9db9-9212bc0cc0e0","shortId":"TjV6YC","kind":"skill","title":"tailwind-css","tagline":">-","description":"# Tailwind CSS v4\n\n**Verify before implementing**: For v4-specific syntax (`@theme`, `@variant`, CSS-first config), search current docs via `search_docs` before writing code. Tailwind v4 changed significantly from v3 and training data may be stale.\n\n## CSS-First Configuration\n\nv4 eliminates `tailwind.config.ts`. All configuration lives in CSS.\n\n| Directive | Purpose |\n|-----------|---------|\n| `@import \"tailwindcss\"` | Entry point (replaces `@tailwind base/components/utilities`) |\n| `@theme { }` | Define/extend design tokens -- auto-generates utility classes |\n| `@theme inline { }` | Map CSS variables to Tailwind utilities without generating new vars |\n| `@theme static { }` | Define tokens that don't generate utilities |\n| `@utility name { }` | Create custom utilities (replaces `@layer components` + `@apply`) |\n| `@custom-variant name (selector)` | Define custom variants |\n\n```css\n@import \"tailwindcss\";\n\n@theme {\n --color-brand: oklch(0.72 0.11 178);\n --font-display: \"Inter\", sans-serif;\n --animate-fade-in: fade-in 0.2s ease-out;\n @keyframes fade-in { from { opacity: 0; } to { opacity: 1; } }\n}\n\n@custom-variant dark (&:where(.dark, .dark *));\n```\n\nTokens defined with `@theme` become utilities automatically: `--color-brand` produces `bg-brand`, `text-brand`, `border-brand`. Define z-index as tokens (`--z-modal: 50`) and reference via `z-(--z-modal)` instead of arbitrary `z-50`.\n\n**CSS Modules**: when using `.module.css` with Tailwind v4, add `@reference \"#tailwind\";` at the top of the module file to enable theme token access inside the module.\n\n**Animations (tw-animate-css)**: use `animate-in`/`animate-out` base classes combined with effect classes (`fade-in`, `slide-in-from-top`). Decimal spacing gotcha: use bracket notation `[0.625rem]` instead of fractional values like `2.5`.\n\n## v3 to v4 Migration\n\nFor projects upgrading from v3 to v4, see [v3-to-v4-migration.md](./references/v3-to-v4-migration.md) for the full breaking-change table and codemod guidance. For greenfield v4 work, current patterns are above.\n\n## Coding Rules\n\n- **`gap` over `space-x`/`space-y`** -- gap handles wrapping; space-* breaks on wrap\n- **`size-*` over `w-* h-*`** -- for equal dimensions\n- **`min-h-dvh` over `min-h-screen`** -- dvh accounts for mobile browser chrome\n- **Opacity modifier** (`bg-black/50`) -- `*-opacity-*` utilities are removed in v4\n- **Design tokens over arbitrary values** -- check `@theme` before using `[#hex]`\n- **Never construct classes dynamically** -- `text-${color}-500` won't be detected; use complete class names\n- **`@utility` over `@apply` with `@layer`** -- `@apply` on `@layer` classes fails in v4\n- **Parent padding over last-child margin** -- use padding on containers instead of bottom margins on the last child\n\n## ESLint Integration\n\nUse `eslint-plugin-better-tailwindcss` for automated class validation:\n- `no-conflicting-classes` -- catches `text-red-500 text-blue-500`\n- `no-unknown-classes` -- flags typos\n- `enforce-canonical-classes` -- normalizes shorthand\n- `no-duplicate-classes` -- removes redundant entries\n- `no-deprecated-classes` -- catches v3 classes removed in v4\n- `useSortedClasses` -- enforces canonical class order; configure `attributes: [\"classList\"]` and `functions: [\"clsx\", \"cva\", \"cn\", \"tv\", \"tw\"]` to cover JSX utility functions\n\n## Class Merging\n\nUse `cn()` combining `clsx` + `tailwind-merge` for conditional/dynamic classes. Use plain strings for static `className` attributes.\n\n```typescript\nimport { type ClassValue, clsx } from \"clsx\";\nimport { twMerge } from \"tailwind-merge\";\nexport function cn(...inputs: ClassValue[]) { return twMerge(clsx(inputs)); }\n```\n\n```typescript\n// Static: plain string\n