// Child — respond to container, not viewport
function ProductCard() {
return (
Title
$29.99
);
}
```
## Critical Gotchas
| # | Gotcha | What to do |
|---|--------|------------|
| 1 | `tailwindcss-animate` doesn't work in v4 | Use `tw-animate-css` instead — import in CSS: `@import "tw-animate-css"` |
| 2 | OKLCH, not HSL | shadcn 2.3.0+ uses OKLCH color space. Use `oklch()` not `hsl()` |
| 3 | Container parent needs measurable width | Flex columns with no explicit width break container queries |
| 4 | `@md:` ≠ `md:` | `@md:` = container query, `md:` = viewport media query. Don't mix |
| 5 | shadcn components.json needs `"rsc": true` | Required for Server Component projects |
| 6 | Static shadcn components are server-safe | Interactive ones (Dialog, Dropdown) include 'use client' already — no need to wrap |
| 7 | Tailwind v4 is incompatible with Sass/Less | CSS-first @theme directive: Sass can't parse it. Use plain CSS |
| 8 | No `forwardRef` in components | v4 uses `React.ComponentProps` + `data-slot` attributes |
| 9 | Default style deprecated | New projects use `"style": "new-york"` exclusively |
| 10 | Toast deprecated | Use `sonner` instead |
## Design Token Hierarchy
```
Brand tokens (--brand-blue-500) → Semantic tokens (--color-primary) → Component tokens (--button-bg)
```
Use semantic tokens in your CSS. AI agents (Claude Code, Cursor) parse CSS variables more reliably than JS config files.
```css
@theme {
/* Brand tokens */
--color-brand-blue: oklch(0.55 0.22 250);
--color-brand-green: oklch(0.63 0.18 170);
/* Semantic tokens (map brand values) */
--color-primary: var(--color-brand-blue);
--color-success: var(--color-brand-green);
}
```
## RSC Optimization
- **Server components** for all static Tailwind-styled UI (no `'use client'`)
- **Client islands** only where state/events exist
- **Variant computation** server-side with class composition, not runtime
```tsx
// ✅ Server Component — styling is just inert strings
function ProductCard({ title, price }: { title: string; price: number }) {
const sizeClass = price > 100 ? 'text-xl' : 'text-base';
return (
{title}
);
}
```
## Reference Documents
- `references/research-2026-07-02.md` — Full research context with source URLs, MCP server evaluation table, and all 10 AI agent gotchas in one place.
## MCP Servers for Tailwind (recommended)
Install these in your Hermes/Claude config:
```json
{
"mcpServers": {
"tailwindcss-docs-mcp": {
"command": "npx",
"args": ["-y", "tailwindcss-docs-mcp"]
},
"designmcp-server": {
"command": "npx",
"args": ["-y", "@cdej-lgtm/designmcp-server"]
}
}
}
```
- `tailwindcss-docs-mcp`: Local semantic search over Tailwind docs (v3 + v4)
- `designmcp-server`: shadcn/ui theming with OKLCH color science===ME:tailwind-v4-shadcn-setup