git:20260305.a08fbb4 to git:20260313.02a8e7c

+

+ 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.

+ | Topic | Reference | Contents |

+ | ---------------- | ------------------------------------------------------------------- | --------------------------------------------------------------- |

+ | 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) |

+ - 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`

+ - Do not use Sass, Less, or Stylus with Tailwind v4 — Tailwind is the preprocessor (handles `@import`, nesting,

+ variables, vendor prefixes)

+ - `@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

+ - 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()`

+ | Option | Behavior |

+ | ------------------- | --------------------------------------------- |

+ | `@theme { }` | Default: only emit used vars |

+ | `@theme static { }` | Always emit all vars |

+ Use `@theme inline` when a token references another variable — prevents CSS variable resolution failures in the cascade.

+ | Namespace | Generated utilities |

+ | --------------------------------- | ------------------------------------------------------------------ |

+ | `--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.

+ - Every `--color-*` token generates utilities across `bg-*`, `text-*`, `border-*`, `ring-*`, `fill-*`, `stroke-*`, etc.

+ - **Complete class names only.** Never concatenate or interpolate — `text-red-600` yes, `` `text-${color}-600` `` never.

+ Tailwind scans source files as plain text

+ - **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

+ - **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

+ | Prefix | Min-width | Prefix | Min-width |

+ | ------ | -------------- | ------ | -------------- |

+ | `sm:` | 40rem (640px) | `xl:` | 80rem (1280px) |

+ | `md:` | 48rem (768px) | `2xl:` | 96rem (1536px) |

+ | `lg:` | 64rem (1024px) | | |

+ - **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`

+ - 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 are inserted into the `utilities` layer automatically and support all variants (`hover:`, `focus:`,

+ `lg:`, etc.)

+ - Complex with nesting: `@utility scrollbar-hidden { &::-webkit-scrollbar { display: none; } }`

+ - `--value()` resolution modes: `--value(--ns-*)` (theme key), `--value(integer)` (bare value), `--value([integer])`

+ (arbitrary value), `--value("inherit")` (literal)

+ - Shorthand: `@custom-variant theme-midnight (&:where([data-theme="midnight"] *));`

+ - **`@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

+ - **`@plugin`:** Load JS plugins. CSS-native `@utility`/`@custom-variant` preferred

+ - **`@layer` precedence:** `base` < `components` < `utilities`. Utilities always win

+ - **`@source`:** Register additional scan paths, exclude paths, safelist with `@source inline()` using brace expansion

+ - Auto-scans all project files except `.gitignore`d, `node_modules`, binaries, CSS files, lock files

+ - **Template components over `@apply`.** In React/Vue/Svelte, extract a component. In server templates, extract a

+ partial. `@apply` is the last resort

+ - `@apply` only for single-element patterns — multi-element structures belong in template components

+ - Acceptable `@apply` uses: third-party library overrides, legacy HTML you don't control

+ - `sr-only` for visually hidden, screen-reader accessible; `not-sr-only` to reverse. `hidden` removes from flow;

+ `invisible` keeps space

+ - `flex-1` (grow/shrink, ignore initial), `flex-auto` (respect initial), `flex-none` (fixed size)

+ See `${CLAUDE_SKILL_DIR}/references/layout.md` for full display, position, flexbox, grid, alignment, order, and

+ visibility utility catalogs.

+ `--spacing` drives all spacing utilities. 1 unit = 0.25rem (4px). Customize: `@theme { --spacing: 4px; }`.

+ - Width/height: `w-<n>`, `h-<n>` (spacing scale), `w-<fraction>` (percentage), `w-full`, `w-screen`, `w-dvw`, `h-dvh`.

+ `size-<n>` sets both

+ - Margin: same prefixes plus `auto` and negatives (`-mt-4`). `mx-auto` centers block elements

+ **v4 scale shift:** `rounded` without suffix maps to `xs` size (was `md` in v3). Per-side, per-corner, and logical

+ variants (`rounded-s-*`, `rounded-ss-*`) available. See `${CLAUDE_SKILL_DIR}/references/sizing-and-spacing.md` for the

+ full scale table.

+ See `${CLAUDE_SKILL_DIR}/references/sizing-and-spacing.md` for the full spacing scale, width/height keywords, container

+ scale, viewport units, and box model details.

+ - Family: `font-sans`, `font-serif`, `font-mono`. Custom via `--font-*` in `@theme`

+ - Size: `text-xs` through `text-9xl` — each sets both `font-size` and default `line-height`. Override inline:

+ `text-sm/6`, `text-lg/loose`

+ See `${CLAUDE_SKILL_DIR}/references/typography.md` for full font properties, text spacing, styling, decoration, and text

+ layout utility catalogs.

+ - **Gradient syntax:** `bg-linear-to-r` (not `bg-gradient-to-r`), `bg-radial`, `bg-conic`. Default interpolation is

+ **oklab**

+ - **Shadow scale shifted by one step from v3.** `shadow-sm` in v3 = `shadow-xs` in v4

+ - **Ring default:** 1px currentColor (v3 was 3px blue) — use `ring-3` for thick rings

+ See `${CLAUDE_SKILL_DIR}/references/backgrounds-and-effects.md` for full gradient, shadow, ring, filter, backdrop, and

+ mask utility catalogs.

+ - Use specific transitions: `transition-colors`, `transition-transform`, `transition-opacity` — **never**

+ `transition-all`

+ See `${CLAUDE_SKILL_DIR}/references/transforms-and-animations.md` for full transition, animation, 2D/3D transform,

+ filter, and mask utility catalogs.

+ - **Respect reduced motion.** Gate animations with `motion-safe:` or disable with `motion-reduce:transition-none`

+ - `forced-color-adjust-none` only for elements where forced colors destroys essential visual information — always

+ include `sr-only` text label

+ - Add `role="list"` on unstyled lists — VoiceOver doesn't announce `list-style: none` elements as lists

+ - Extends reset: headings unstyled, lists have no bullets, images are `display: block`

+ - **v4 changes:** buttons default `cursor: default`, placeholder is text color at 50% opacity

+ - Disable by importing `tailwindcss/theme.css` and `tailwindcss/utilities.css` individually

+ Each module is processed separately — causes slower builds and missing `@theme` context. Use `@reference "../app.css"`

+ in `<style>` blocks, or prefer CSS variables directly: `background-color: var(--color-blue-500)`.

+ - **React:** `clsx` for conditional composition, `cva` for variant APIs, `cn` = `twMerge(clsx(...))` for className

+ overrides

+

+ - Use utilities directly in markup. Reach for custom CSS only when utilities are insufficient.

+ - If an existing codebase contradicts a convention, follow the codebase and flag the divergence once.

+

+ The CSS skill is a prerequisite — it provides specificity, box model, and layout knowledge that Tailwind abstracts but

+ does not replace. Framework skills handle class binding in each framework.

+ **Utility classes are the default. When in doubt, keep configuration in `@theme` and styling in markup.**