// respects theme + dark mode

// breaks theming - avoid ``` Always pair `bg-*` with the matching `text-*-foreground`. Background utilities omit the `-background` suffix (`bg-muted text-muted-foreground`). ### Never build class names dynamically ```tsx

// scanner can't see it - no CSS emitted const map = { red: "bg-red-500", blue: "bg-blue-500" } as const

// complete literal strings ``` ### `cn()` merge order Defaults first, consumer `className` last, so tailwind-merge's last-wins lets callers override: ```tsx className={cn(buttonVariants({ variant, size }), className)} // correct ``` ### Transition only what changes `transition-all` thrashes layout. Name the properties, and respect reduced motion: ```tsx

``` ## Layout and responsiveness Mobile-first breakpoints; container queries are first-class in v4 (no plugin): ```tsx

// responds to container, not viewport

``` Dark mode: prefer semantic colors (auto-flip) over manual `dark:` overrides. Use `next-themes` for the toggle (`attribute="class"`), and add `suppressHydrationWarning` to `` to avoid a flash. ## Version-specific features ### v4.1 / v4.2 ```tsx

// text shadows (4.1)

// gradient masks (4.1) // (4.1)

// logical block props (4.2)

// new palettes: mauve/olive/mist/taupe (4.2) ``` The positioning utilities `start-*`/`end-*` are **deprecated** in favor of `inset-s-*`/`inset-e-*` (don't confuse with logical padding `ps-*`/`pe-*`, which are fine). ### v4.3 (current) ```tsx

// scrollbar utils

// size container for cqb/cqh units // CSS zoom utilities

                                  // tab-size
```

In CSS you can now stack and group `@variant`: `@variant hover:focus { ... }` and `@variant hover, focus { ... }`, and pass `--default(...)` to `--value(...)`/`--modifier(...)` in custom functional utilities.

### Animations

```css
@import "tw-animate-css";
```

```tsx

```

## OKLCH colors

shadcn/ui colors use `oklch(lightness chroma hue)`: lightness 0-1, chroma 0-0.4 (0 = gray), hue 0-360. OKLCH gives perceptually uniform lightness, so dark-mode variants are easy to derive by adjusting L. Base neutral palettes: Neutral, Zinc, Slate, Stone, Gray.

## Notes

- A first-class `@tailwindcss/webpack` loader exists (added v4.2) for Next.js/webpack/Turbopack projects - relevant if you're not on Vite.
- If you lint CSS with Biome, enable `css.parser.tailwindDirectives` so it understands `@theme`/`@utility`/`@apply` (see [biome.md](biome.md)).

## Troubleshooting

- **Colors not updating:** confirm the variable is in your CSS, `@theme inline` includes the mapping, then clear the build cache.
- **`tailwind.config.js` present:** delete it; run `npx @tailwindcss/upgrade` to migrate to CSS-first.
- **Classes not detected:** check `@source` covers your component paths and that no class name is constructed dynamically.

## Resources

- Docs: https://tailwindcss.com/docs - v4.3 blog: https://tailwindcss.com/blog/tailwindcss-v4-3
- Vite plugin: https://tailwindcss.com/docs/installation/using-vite