{"id":"cd6e0209-12a7-479e-82fc-6a7882b0ed30","shortId":"7mpt5x","kind":"skill","title":"tailwind-css","tagline":"This skill should be used when the user asks to \"style with Tailwind\", \"add Tailwind classes\", \"fix Tailwind styles\", \"use tailwind-variants\", \"add animations with tw-animate-css\", \"configure Tailwind v4\", \"migrate to Tailwind v4\", or mentions Tailwind utilities, CSS classes, res","description":"# Tailwind CSS v4\n\nExpert guidance for Tailwind CSS v4, CSS-first configuration, modern utility patterns, and type-safe component styling with tailwind-variants.\n\n## CSS-First Configuration\n\nTailwind CSS v4 eliminates `tailwind.config.ts` in favor of CSS-only configuration. All configuration lives in CSS files using special directives.\n\n**Core Directives:**\n\n- `@import \"tailwindcss\"` - Entry point that loads Tailwind\n- `@theme { }` - Define or extend design tokens\n- `@theme static { }` - Define tokens that should not generate utilities\n- `@utility` - Create custom utilities\n- `@custom-variant` - Define custom variants\n\n**Minimal Example:**\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 --spacing-edge: 1.5rem;\n}\n```\n\nAll theme tokens defined with `@theme` automatically become available as utility classes. For example, `--color-brand` can be used as `bg-brand`, `text-brand`, `border-brand`, etc.\n\n## ESLint Integration\n\nUse `eslint-plugin-better-tailwindcss` for Tailwind CSS v4 class validation and style enforcement.\n\n**Correctness Rules (errors):**\n\n- `no-conflicting-classes` - Detect classes that override each other\n- `no-unknown-classes` - Flag classes not registered with Tailwind\n\n**Stylistic Rules (warnings):**\n\n- `enforce-canonical-classes` - Use standard v4 class names\n- `enforce-shorthand-classes` - Use abbreviated class versions\n- `no-deprecated-classes` - Remove outdated class names\n- `no-duplicate-classes` - Eliminate redundant declarations\n- `no-unnecessary-whitespace` - Clean up extra spacing\n\n**Examples:**\n\n```typescript\n// ❌ Bad: separate padding\n
\n\n// ✅ Good: shorthand\n
\n```\n\n```typescript\n// ❌ Bad: separate width/height\n
\n\n// ✅ Good: size utility\n
\n```\n\nRun the project's ESLint check after modifying Tailwind classes to validate all changes across the codebase.\n\n## Coding Preferences\n\n### Layout and Spacing\n\n**Use `gap` for flex/grid spacing, not `space-x`/`space-y`:**\n\nThe `gap` utilities handle wrapping correctly, while `space-*` utilities break when flex/grid items wrap to multiple lines.\n\n```typescript\n// ✅ Good: gap handles wrapping\n
\n\n// ❌ Bad: breaks when items wrap\n
\n```\n\n**Prefer `size-*` over separate `w-*`/`h-*` for equal dimensions:**\n\n```typescript\n// ✅ Good: concise\n
\n\n// ❌ Bad: redundant\n
\n```\n\n**Always use `min-h-dvh` instead of `min-h-screen`:**\n\nDynamic viewport height (`dvh`) accounts for mobile browser chrome, while `vh` units ignore it and cause layout issues on mobile Safari.\n\n```typescript\n// ✅ Good: works on mobile Safari\n
\n\n// ❌ Bad: buggy on mobile Safari\n
\n```\n\n**Prefer top/left margins over bottom/right:**\n\nConsistent directionality improves layout predictability.\n\n```typescript\n// ✅ Good: top margin\n
\n\n// ❌ Avoid: bottom margin (unless needed)\n
\n```\n\n**Use padding on parent containers instead of bottom margins on last child:**\n\nPadding provides consistent spacing without needing `:last-child` selectors.\n\n```typescript\n// ✅ Good: padding on parent\n
\n
Item 1
\n
Item 2
\n
Item 3
\n
\n\n// ❌ Avoid: margin on children\n
\n
Item 1
\n
Item 2
\n
Item 3
\n
\n```\n\n**For max-widths, prefer container scale over pixel values:**\n\n```typescript\n// ✅ Good: semantic container size\n
\n\n// ❌ Avoid: arbitrary pixel value\n
\n```\n\n### Typography\n\n**Avoid `leading-*` classes; use line height modifiers:**\n\nTailwind v4 supports inline line height modifiers with the `text-{size}/{leading}` syntax.\n\n```typescript\n// ✅ Good: combined size and line height\n

\n\n// ❌ Bad: separate utilities\n

\n```\n\n**Font Size Reference:**\n\n| Class | Size |\n| ----------- | ---- |\n| `text-xs` | 12px |\n| `text-sm` | 14px |\n| `text-base` | 16px |\n| `text-lg` | 18px |\n| `text-xl` | 20px |\n\n### Colors and Opacity\n\n**Use opacity modifier syntax, not separate opacity utilities:**\n\nAll `*-opacity-*` utilities were removed in Tailwind v4. Use the modifier syntax instead.\n\n```typescript\n// ✅ Good: opacity modifier\n

\n\n// ❌ Bad: removed in v4\n
\n```\n\n**Prefer design tokens over arbitrary hex values:**\n\nCheck the project's `@theme` configuration before using arbitrary color values.\n\n```typescript\n// ✅ Good: theme token\n
\n\n// ❌ Avoid: arbitrary hex (check theme first)\n
\n```\n\n### Border Radius\n\nTailwind v4 renamed border radius utilities:\n\n| v3 | v4 (equivalent) | Size |\n| ------------ | --------------- | ---- |\n| `rounded-sm` | `rounded-xs` | 2px |\n| `rounded` | `rounded-sm` | 4px |\n| `rounded-md` | `rounded` | 6px |\n| `rounded-lg` | `rounded-md` | 8px |\n\nUse the v4 names when writing new code.\n\n### Gradients\n\nTailwind v4 renamed gradient utilities and added new gradient types.\n\n**Use `bg-linear-*`, not `bg-gradient-*`:**\n\n```typescript\n// ✅ Good: v4 syntax\n
\n\n// ❌ Bad: removed in v4\n
\n```\n\n**New gradient types:**\n\n- `bg-radial` - Radial gradients\n- `bg-conic` - Conic gradients\n\n**Example:**\n\n```typescript\n
\n
\n```\n\n### Arbitrary Values\n\n**Always prefer Tailwind's predefined scale:**\n\nCheck the project's `@theme` configuration for available tokens before using arbitrary values.\n\n```typescript\n// ✅ Good: predefined scale\n
\n\n// ❌ Avoid: arbitrary pixel value\n
\n```\n\n**General rule:** Prefer sizing scale over pixel values. Three similar lines of code is better than a premature abstraction.\n\n### Class Merging\n\nThe common pattern is a `cn` utility combining `clsx` + `tailwind-merge`.\n\n**Use `cn` for:**\n\n- Static constants: `const CARD_BASE = cn(\"fixed classes\")`\n- Conditional classes: `cn(\"base\", condition && \"conditional\")`\n- Dynamic merging: `cn(baseClasses, className)`\n- Conflict resolution: `cn(\"p-4\", \"p-6\")` → `\"p-6\"`\n\n**Do NOT use `cn` for:**\n\n- Static strings in `className` attributes: `className=\"fixed classes\"`\n\n**Examples:**\n\n```typescript\n// ✅ Good: static string in className\n