# Tailwindcss

> Tailwind CSS v4 rules - CSS-first config, utility-first, @theme, variants, dark mode, build with CLI/PostCSS/Vite, components with @apply

- Skill: `14bryanespinoza/tailwindcss` (Agent Skill)
- Install (CLI): `npx skillmds@latest add 14bryanespinoza/tailwindcss`
- Raw SKILL.md: https://api.skillmd.com/api/skills/14bryanespinoza/tailwindcss/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: 14BryanEspinoza (https://skillmd.com/u/14bryanespinoza)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/14bryanespinoza/tailwindcss

---


# Tailwind CSS v4 — Rules and Conventions

---

## 1. Philosophy

1. **CSS-first config** — `@theme` in CSS, no `tailwind.config.js` required.
2. **Utility-first** — Compose designs from utilities. Extract components only when patterns repeat.
3. **Design tokens as CSS vars** — Colors, spacing, fonts, shadows via `@theme` → CSS variables.
4. **No runtime** — All compiled at build. Zero client-side JS.
5. **Modern CSS** — Uses cascade layers, container queries, `:has()`, `color-mix()`.

---

## 2. Minimum Version

| Technology   | Minimum Version |
| ------------ | --------------- |
| Tailwind CSS | 4.0+            |
| Node.js      | 22+             |
| pnpm         | 11+             |

---

## 3. Installation

### Vite (recommended)

```bash
pnpm add -D tailwindcss@4 @tailwindcss/vite
```

```ts
// vite.config.ts
import { defineConfig } from "vite";
import tailwindcss from "@tailwindcss/vite";

export default defineConfig({
  plugins: [tailwindcss()],
});
```

```css
/* styles/main.css */
@import "tailwindcss";

@theme {
  /* Design tokens here */
}
```

### PostCSS (standalone)

```bash
pnpm add -D tailwindcss@4 @tailwindcss/postcss postcss
```

```js
// postcss.config.js
export default {
  plugins: {
    "@tailwindcss/postcss": {},
  },
};
```

### CLI (no build tool)

```bash
pnpm add -D tailwindcss@4
npx tailwindcss -i ./styles/main.css -o ./dist/styles.css --watch
```

---

## 4. @import and Directives

```css
/* styles/main.css */
@import "tailwindcss";

/* Or explicit layers */
@import "tailwindcss/base";
@import "tailwindcss/components";
@import "tailwindcss/utilities";

/* Custom layers */
@layer components {
  .btn {
    @apply px-4 py-2 rounded;
  }
}
```

### Rules

- **Single `@import "tailwindcss"`** — imports all layers
- **`@layer` for custom utilities/components** — respects cascade order
- **No `@tailwind` directives** — v4 uses `@import`

---

## 5. @theme — Design Tokens

```css
@theme {
  /* Colors (generates --color-*) */
  --color-primary: #0066cc;
  --color-primary-50: #e6f0fa;
  --color-primary-100: #cce0f5;
  --color-primary-500: #0066cc;
  --color-primary-900: #003366;

  /* Spacing (generates --spacing-*) */
  --spacing-18: 4.5rem;
  --spacing-88: 22rem;

  /* Fonts (generates --font-*) */
  --font-sans: "Inter", system-ui, sans-serif;
  --font-mono: "JetBrains Mono", monospace;

  /* Border radius (generates --radius-*) */
  --radius-xl: 0.75rem;
  --radius-2xl: 1rem;

  /* Shadows (generates --shadow-*) */
  --shadow-glow: 0 0 20px rgb(0 102 204 / 0.3);

  /* Breakpoints (generates --breakpoint-*) */
  --breakpoint-3xl: 120rem;

  /* Custom tokens */
  --animate-duration-fast: 150ms;
  --animate-duration-normal: 250ms;
}
```

### Generated utilities

| Token prefix     | Utility prefix                     | Example                 |
| ---------------- | ---------------------------------- | ----------------------- |
| `--color-*`      | `bg-`, `text-`, `border-`, `ring-` | `bg-primary-500`        |
| `--spacing-*`    | `p-`, `m-`, `gap-`, `space-`       | `p-18`                  |
| `--font-*`       | `font-`                            | `font-sans`             |
| `--radius-*`     | `rounded-`                         | `rounded-xl`            |
| `--shadow-*`     | `shadow-`                          | `shadow-glow`           |
| `--breakpoint-*` | `sm:`, `md:`, etc.                 | `3xl:flex`              |
| `--animate-*`    | `animate-`                         | `animate-duration-fast` |

### Rules Theme

- **All tokens in `@theme`** — single source of truth
- **Semantic names** — `primary`, `secondary`, not `blue-500`
- **CSS variable fallback** — `var(--color-primary, #0066cc)`

---

## 6. Essential Utilities (Table)

### Layout

| Utility                                     | CSS                               | Responsive |
| ------------------------------------------- | --------------------------------- | ---------- |
| `container`                                 | `max-width: 1280px; margin: auto` | ✓          |
| `flex` / `grid` / `block` / `hidden`        | display                           | ✓          |
| `flex-row` / `flex-col`                     | flex-direction                    | ✓          |
| `items-center` / `justify-center` / `gap-4` | align/justify/gap                 | ✓          |
| `w-full` / `h-screen` / `min-h-0`           | width/height                      | ✓          |

### Spacing

| Pattern                         | Values         |
| ------------------------------- | -------------- |
| `p-{0..4..96}` / `m-{0..4..96}` | padding/margin |
| `px-4` / `py-2` / `pt-8`        | directional    |
| `gap-4` / `space-y-4`           | flex/grid gap  |

### Typography

| Utility                   | Values         |
| ------------------------- | -------------- |
| `text-{xs..9xl}`          | font-size      |
| `font-{thin..extrabold}`  | font-weight    |
| `font-sans` / `font-mono` | font-family    |
| `leading-{tight..loose}`  | line-height    |
| `tracking-{tight..wide}`  | letter-spacing |

### Colors

| Utility              | Token                 |
| -------------------- | --------------------- |
| `bg-primary-500`     | `--color-primary-500` |
| `text-gray-900`      | `--color-gray-900`    |
| `border-primary-200` | `--color-primary-200` |
| `ring-primary-500`   | `--color-primary-500` |

### Borders & Radius

| Utility                                                  | Values |
| -------------------------------------------------------- | ------ |
| `border` / `border-2`                                    | width  |
| `rounded` / `rounded-lg` / `rounded-xl` / `rounded-full` | radius |
| `border-gray-200` / `border-primary-500`                 | color  |

### Shadows

| Utility                              | Token                |
| ------------------------------------ | -------------------- |
| `shadow` / `shadow-lg` / `shadow-xl` | default scale        |
| `shadow-glow`                        | custom from `@theme` |

---

## 7. Responsive Design

### Breakpoints (mobile-first)

```css
@theme {
  --breakpoint-sm: 40rem; /* 640px */
  --breakpoint-md: 48rem; /* 768px */
  --breakpoint-lg: 64rem; /* 1024px */
  --breakpoint-xl: 80rem; /* 1280px */
  --breakpoint-2xl: 96rem; /* 1536px */
}
```

### Usage

```html
<div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
  <div class="p-4 md:p-6 lg:p-8">Content</div>
</div>
```

### Container queries

```html
<div class="@container">
  <div class="@md:grid @md:grid-cols-2">...</div>
</div>
```

---

## 8. Variants (States)

| Variant                     | Trigger         | Example                          |
| --------------------------- | --------------- | -------------------------------- |
| `hover:`                    | Mouse hover     | `hover:bg-primary-600`           |
| `focus:` / `focus-visible:` | Keyboard focus  | `focus:ring-2`                   |
| `active:`                   | Mouse down      | `active:scale-95`                |
| `disabled:`                 | Disabled state  | `disabled:opacity-50`            |
| `group-hover:`              | Parent hover    | `group:hover .child:opacity-100` |
| `peer-checked:`             | Sibling checked | `peer:checked ~ .indicator`      |
| `data-[state=open]:`        | Data attribute  | `data-[state=open]:animate-in`   |
| `dark:`                     | Dark mode       | `dark:bg-gray-900`               |
| `supports-[display:grid]:`  | `@supports`     | `supports-[display:grid]:grid`   |

---

## 9. Dark Mode

### Class strategy (recommended)

```css
@theme {
  --color-bg: #ffffff;
  --color-text: #111827;
}

@media (prefers-color-scheme: dark) {
  :root {
    --color-bg: #111827;
    --color-text: #f9fafb;
  }
}

/* Or explicit class */
.dark {
  --color-bg: #111827;
  --color-text: #f9fafb;
}
```

```html
<html class="dark">
  <!-- Force dark -->
  <div class="bg-white dark:bg-gray-900 text-gray-900 dark:text-gray-100"></div>
</html>
```

### Rules Dark Mode

- **CSS variables in `@theme`** — automatic dark mode via media query
- **`dark:` variant** — for explicit overrides
- **`color-scheme` meta** — `<meta name="color-scheme" content="light dark">`

---

## 10. Arbitrary Values

```html
<!-- Arbitrary spacing -->
<div class="p-[18px] mt-[var(--custom-spacing)]">
  <!-- Arbitrary color -->
  <div class="bg-[#0066cc] text-[#f0f0f0]">
    <!-- Arbitrary grid -->
    <div class="grid-cols-[1fr_300px_auto]">
      <!-- Arbitrary animation -->
      <div class="animate-[spin_1s_linear_infinite]"></div>
    </div>
  </div>
</div>
```

### Rules Arbitrary Value

- **Square brackets** — `[value]` for any valid CSS value
- **CSS variables** — `var(--token)` inside brackets
- **Last resort** — prefer design tokens in `@theme`

---

## 11. @apply / @utility

### @apply (component extraction)

```css
@layer components {
  .btn {
    @apply px-4 py-2 rounded-lg font-medium transition-colors;
  }
  .btn-primary {
    @apply btn bg-primary-500 text-white hover:bg-primary-600;
  }
  .btn-secondary {
    @apply btn bg-gray-200 text-gray-900 hover:bg-gray-300;
  }
}
```

### @utility (custom utilities)

```css
@layer utilities {
  @utility text-balance {
    text-wrap: balance;
  }
  @utility scrollbar-hide {
    -ms-overflow-style: none;
    scrollbar-width: none;
    &::-webkit-scrollbar {
      display: none;
    }
  }
}
```

### Rules Apply Utilities

- **`@apply` in `@layer components`** — for repeated UI patterns
- **`@utility` in `@layer utilities`** — for single-purpose utilities
- **Avoid over-extraction** — utilities are fine for one-offs

---

## 12. Essential Plugins

```bash
pnpm add -D @tailwindcss/forms @tailwindcss/typography @tailwindcss/aspect-ratio
```

```css
/* styles/main.css */
@import "tailwindcss";
@plugin "@tailwindcss/forms";
@plugin "@tailwindcss/typography";
@plugin "@tailwindcss/aspect-ratio";

@theme { ... }
```

| Plugin                      | Purpose                         |
| --------------------------- | ------------------------------- |
| `@tailwindcss/forms`        | Reset + style form inputs       |
| `@tailwindcss/typography`   | `.prose` for rich text          |
| `@tailwindcss/aspect-ratio` | `aspect-video`, `aspect-square` |

---

## 13. Framework Integration

### Vite

```bash
pnpm add -D tailwindcss@4 @tailwindcss/vite
```

```ts
// vite.config.ts
import tailwindcss from "@tailwindcss/vite";
export default defineConfig({ plugins: [tailwindcss()] });
```

### Astro

```bash
pnpm astro add tailwind
# or
pnpm add -D tailwindcss@4 @tailwindcss/vite
```

```ts
// astro.config.mjs
import tailwindcss from "@tailwindcss/vite";
export default defineConfig({
  integrations: [],
  vite: { plugins: [tailwindcss()] },
});
```

> **Vite/Astro details**: see `vite` and `astro` skills.

---

## 14. Class Order (Prettier Plugin)

```bash
pnpm add -D prettier prettier-plugin-tailwindcss
```

```json
// .prettierrc
{
  "plugins": ["prettier-plugin-tailwindcss"],
  "tailwindConfig": "./styles/main.css"
}
```

### Automatic sorting

```html
<!-- Before (unsorted) -->
<div class="text-center p-4 bg-white rounded-lg shadow-lg md:flex">
  <!-- After (sorted by Prettier) -->
  <div class="bg-white p-4 rounded-lg shadow-lg text-center md:flex"></div>
</div>
```

### Order groups

1. Layout (`flex`, `grid`, `container`)
2. Spacing (`p-4`, `m-2`, `gap-4`)
3. Sizing (`w-full`, `h-10`)
4. Typography (`text-center`, `font-bold`)
5. Colors (`bg-white`, `text-gray-900`)
6. Borders (`rounded-lg`, `border`)
7. Effects (`shadow-lg`, `opacity-50`)
8. Transforms (`rotate-45`, `scale-100`)
9. Transitions (`transition`, `duration-200`)
10. Interactivity (`hover:`, `focus:`, `dark:`)

---

## 15. Methodology

Before using ANY Tailwind class/pattern not documented in this skill:

1. **MCP Context7** (priority): `context7_resolve-library-id` + `context7_query-docs` for Tailwind CSS.
2. **Official docs**: tailwindcss.com — verify current utilities + config.
3. **Project config**: `styles/main.css`, `vite.config.ts`, `package.json` — verify against actual setup.
4. **HARD RULE**: If not in this skill AND cannot be verified against 2 authoritative sources → DO NOT USE IT. Document as assumption or risk in report to orchestrator.

---

## 16. Prohibitions

- ❌ Do not use `tailwind.config.js` — v4 uses `@theme` in CSS
- ❌ Do not use `@tailwind base/components/utilities`
  — use `@import "tailwindcss"`
- ❌ Do not extract every pattern with `@apply` — utilities are fine for one-offs
- ❌ Do not use arbitrary values when token exists — use `@theme`
- ❌ Do not disable Prettier plugin — class order matters for diffs
- ❌ Do not use `!important` in utilities — use cascade layers
- ❌ Do not skip `@plugin` for forms/typography — better defaults

---

## 17. References

> **Note:** For CSS conventions, see [CSS](../css/SKILL.md)
> **Note:** For package manager conventions, see [Package Manager](../package-manager/SKILL.md)
> **Note:** For Vite integration, see [Vite](../vite/SKILL.md)
> **Note:** For Astro integration, see [Astro](../astro/SKILL.md)
> **Note:** For performance (Core Web Vitals), see [Performance](../performance/SKILL.md)
> **Note:** For accessibility (WCAG), see [Accessibility](../accessibility/SKILL.md)

---

Last updated: 2026-08