tailwindcss

# Tailwind CSS v4 **Utility classes are the default. Custom CSS is the escape hatch.** <prerequisite> **Tailwind builds on CSS fundamentals.** Before writing or reviewing Tailwind code, invoke the `css` skill to load specificity, box model, and layout knowledge. ``` Skill(frontend:css) ``` Skip only for trivial class additions where no CSS reasoning is needed. </prerequisite> Tailwind CSS uses CSS-first configuration: design tokens live in `@theme`, custom utilities use `@utility`, and there is no JavaScript configuration file. Constrain yourself to the design system; break out only with intention. ## References - **Theme** — [`${CLAUDE_SKILL_DIR}/references/theme-configuration.md`]: Theme tokens, `@theme` options, namespace mapping, color system - **Class authoring** — [`${CLAUDE_SKILL_DIR}/references/class-authoring.md`]: Class composition, variants, dark mode, breakpoints - **Custom utilities** — [`${CLAUDE_SKILL_DIR}/references/custom-utilities-and-variants.md`]: `@utility`, `@custom-variant`, directives, `@source` - **Layout** — [`${CLAUDE_SKILL_DIR}/references/layout.md`]: Display, position, flexbox, grid, alignment, order utilities - **Sizing** — [`${CLAUDE_SKILL_DIR}/references/sizing-and-spacing.md`]: Spacing scale, width/height, padding/margin, borders, box model - **Typography** — [`${CLAUDE_SKILL_DIR}/references/typography.md`]: Font properties, text spacing, styling, decoration, layout - **Backgrounds** — [`${CLAUDE_SKILL_DIR}/references/backgrounds-and-effects.md`]: Gradients, shadows, rings, opacity, SVG, filters - **Transforms** — [`${CLAUDE_SKILL_DIR}/references/transforms-and-animations.md`]: Transitions, animations, 2D/3D transforms, masks - **Framework** — [`${CLAUDE_SKILL_DIR}/references/framework-integration.md`]: Preflight, CSS Modules, class binding (React, Vue, Svelte) ## Entry Point and Installation - Single import: `@import "tailwindcss";` — provides preflight reset, theme variables, and all utilities. No `@tailwind base/components/utilities` (v3 syntax) - Vite: install `@tailwindcss/vite` plugin. PostCSS: install `@tailwindcss/postcss`. CLI: `npx @tailwindcss/cli -i input.css -o output.css` - No `tailwind.config.js` in v4 — all configuration lives in CSS via `@theme` - Remove `postcss-import` and `autoprefixer` — v4 handles both internally - Do not use Sass, Less, or Stylus with Tailwind v4 — Tailwind is the preprocessor (handles `@import`, nesting, variables, vendor prefixes) ## Theme Configuration (`@theme`) ### Core Rules - `@theme` defines design tokens that generate utility classes — not equivalent to `:root`. Use `@theme` for values needing utilities; use `:root` for CSS variables that only need `var()` access - `@theme` must be top-level (not nested under selectors or media queries) - All `@theme` values compile to `:root { }` CSS vars in output - Only used CSS vars are emitted by default - Semantic token names: `--color-primary`, `--color-surface` — not `--color-blue-500` or `--color-gray-100` - OKLCH for custom colors: `oklch(0.72 0.11 178)` — perceptually uniform, works with CSS `color-mix()` ### `@theme` Options - **`@theme { }`** — Default: only emit used vars - **`@theme static { }`** — Always emit all vars - **`@theme inline { }`** — Inline `var()` references into utility output Use `@theme inline` when a token references another variable — prevents CSS variable resolution failures in the cascade. ### Namespace → Utility Mapping - **`--color-*`** → `bg-*`, `text-*`, `border-*`, `ring-*`, `fill-*`, `stroke-*`, etc. - **`--font-*`** → `font-*` (family) - **`--text-*`** → `text-*` (size) - **`--font-weight-*`** → `font-*` (weight) - **`--tracking-*`** → `tracking-*` - **`--leading-*`** → `leading-*` - **`--breakpoint-*`** → Responsive variants: `sm:*`, `md:*` - **`--container-*`** → Container query variants: `@sm:*`, and `max-w-*` - **`--spacing-*` or `--spacing`** → `px-*`, `py-*`, `m-*`, `w-*`, `h-*`, etc. - **`--radius-*`** → `rounded-*` - **`--shadow-*` / `--inset-shadow-*`** → `shadow-*` / `inset-shadow-*` - **`--blur-*`** → `blur-*` - **`--ease-*`** → `ease-*` - **`--animate-*`** → `animate-*` Breakpoints generate variants, not utilities. Colors generate multiple utility families from a single namespace. ### Extending, Replacing, Resetting - **Extend:** Add new tokens alongside defaults — just declare new vars in `@theme` - **Override:** Redeclare a default var to change its value - **Reset namespace:** `--color-*: initial` removes all defaults in that namespace - **Reset everything:** `--*: initial` for fully custom theme - **Disable specific colors:** `--color-lime-*: initial` ### Colors - 22 color families x 11 steps (50-950) plus `black` and `white` - Every `--color-*` token generates utilities across `bg-*`, `text-*`, `border-*`, `ring-*`, `fill-*`, `stroke-*`, etc. - Opacity modifier: `bg-sky-500/50` — per-property, not whole-element - `--alpha()` for CSS opacity: compiles to `color-mix(in oklab, ...)` - Never use `bg-opacity-*` (removed in v4) — always `bg-color/opacity` ### Sharing Themes Put `@theme` in a standalone CSS file and `@import` it after `@import "tailwindcss"`. ## Class Authoring ### Fundamental Rules - **Complete class names only.** Never concatenate or interpolate — `text-red-600` yes, `` `text-${color}-600` `` never. Tailwind scans source files as plain text - Map dynamic values to static class string lookups - **Prettier plugin for ordering.** Install `prettier-plugin-tailwindcss` — do not manually sort classes - **CSS variable shorthand:** `bg-(--brand-color)` — parenthesis syntax auto-wraps in `var()`. Do not use `bg-[var(--brand)]` (v3 verbose form) - **Modifiers stack left-to-right** (v4): `dark:lg:hover:bg-indigo-600`. v3 was right-to-left — reverse stacking order when migrating - **Arbitrary values for one-offs only.** Repeated values belong in `@theme` - **Important suffix:** `bg-red-500!` — the `!` goes at end, after all modifiers - **Conflict resolution:** Last class in the generated stylesheet wins, not last in the HTML attribute. Don't rely on attribute order — use conditional rendering - **Underscores = spaces** in arbitrary values: `grid-cols-[1fr_500px_2fr]`. Escape for literal underscore: `content-['hello\_world']` - **Type hints** for ambiguous CSS vars: `text-(length:--my-var)` for font-size, `text-(color:--my-var)` for text color ### Responsive Breakpoints (Mobile-First) Unprefixed = all sizes. Prefix = that breakpoint **and up**. - **`sm:`** — 40rem (640px) - **`md:`** — 48rem (768px) - **`lg:`** — 64rem (1024px) - **`xl:`** — 80rem (1280px) - **`2xl:`** — 96rem (1536px) - Don't use `sm:` to mean "mobile only" — it means 640px and up - Unprefixed for mobile base, override at breakpoints - Range targeting: `md:max-xl:flex` (only between md and xl) - Arbitrary breakpoints: `min-[900px]:grid-cols-3` - Custom breakpoints: define in `@theme { --breakpoint-xs: 30rem; }` ### Container Queries - `@container` on parent, `@md:flex-row` on children - Named containers: `@container/main` + `@sm/main:flex-col` - Sizes range `@3xs` (16rem) through `@7xl` (80rem) - Arbitrary: `@min-[475px]:flex-row` - Customize via `--container-*` in `@theme` ### State Variants - **Pseudo-classes:** `hover:`, `focus:`, `active:`, `visited:`, `focus-visible:`, `focus-within:`, `disabled:`, `required:`, `invalid:`, `checked:`, `read-only:`, `indeterminate:`, `first:`, `last:`, `odd:`, `even:`, `empty:` - **Conditional:** `has-checked:` (element has checked descendant), `not-focus:` (element is NOT focused) - **Group** (style children based on parent): `group` on parent, `group-hover:text-white` on child. Named groups: `group/item` + `group-hover/item:visible` for nested disambiguation - **In-\*:** Like group but without marking the parent: `in-focus:opacity-100` - **Peer** (style based on preceding sibling): `peer` on sibling, `peer-invalid:visible` on target. Named peers for disambiguation - **has-\* variant:** `has-checked:bg-indigo-50`, `group-has-[a]:block`, `peer-has-checked:ring-2` ### Dark Mode - Default is `prefers-color-scheme` media query — `dark:` works without config - Manual toggle via `@custom-variant dark (&:where(.dark, .dark *));` - Data attribute: `@custom-variant dark (&:where([data-theme=dark], [data-theme=dark] *));` - **Prevent FOUC:** Theme-detection script must be inline in `<head>`, never in a deferred bundle - `color-scheme` for native UI: `scheme-light dark:scheme-dark` on `<html>` matches scrollbars and form controls to active theme ## Custom Utilities and Variants ### `@utility` - Custom utilities are inserted into the `utilities` layer automatically and support all variants (`hover:`, `focus:`, `lg:`, etc.) - Simple: `@utility content-auto { content-visibility: auto; }` - Complex with nesting: `@utility scrollbar-hidden { &::-webkit-scrollbar { display: none; } }` - Functional (accepts argument): use wildcard `@utility tab-*` with `--value()` - `--value()` resolution modes: `--value(--ns-*)` (theme key), `--value(integer)` (bare value), `--value([integer])` (arbitrary value), `--value("inherit")` (literal) - Multiple modes: `--value(--tab-size-*, integer, [integer])` - `--modifier()` reads the modifier portion (`text-lg/tight`) - Negative values: register separate `-utility-*` form - Prefer `@utility` and `@custom-variant` over JS plugins for new code ### `@custom-variant` - Shorthand: `@custom-variant theme-midnight (&:where([data-theme="midnight"] *));` - Block form with `@slot` for multiple rules or media queries - Override built-in `dark` variant for class-based toggling ### Other Directives - **`@variant`:** Apply variants in custom CSS: `@variant dark { background: black; }` - **`@apply`:** Compose utilities into custom CSS — last resort only. Place in `@layer components`. Single-element patterns only - **`@reference`:** Import theme context in Vue/Svelte `<style>` blocks or CSS Modules without duplicating output CSS