1# Tailwind Design System: Advanced Patterns
2 
3Advanced Tailwind CSS v4 patterns including animations, dark mode theming, custom utilities, theme modifiers, namespace overrides, and the v3-to-v4 migration checklist.
4 
5## Pattern 5: Native CSS Animations (v4)
6 
7```css
8/* In your CSS file - native @starting-style for entry animations */
9@theme {
10  --animate-dialog-in: dialog-fade-in 0.2s ease-out;
11  --animate-dialog-out: dialog-fade-out 0.15s ease-in;
12}
13 
14@keyframes dialog-fade-in {
15  from {
16    opacity: 0;
17    transform: scale(0.95) translateY(-0.5rem);
18  }
19  to {
20    opacity: 1;
21    transform: scale(1) translateY(0);
22  }
23}
24 
25@keyframes dialog-fade-out {
26  from {
27    opacity: 1;
28    transform: scale(1) translateY(0);
29  }
30  to {
31    opacity: 0;
32    transform: scale(0.95) translateY(-0.5rem);
33  }
34}
35 
36/* Native popover animations using @starting-style */
37[popover] {
38  transition:
39    opacity 0.2s,
40    transform 0.2s,
41    display 0.2s allow-discrete;
42  opacity: 0;
43  transform: scale(0.95);
44}
45 
46[popover]:popover-open {
47  opacity: 1;
48  transform: scale(1);
49}
50 
51@starting-style {
52  [popover]:popover-open {
53    opacity: 0;
54    transform: scale(0.95);
55  }
56}
57```
58 
59```typescript
60// components/ui/dialog.tsx - Using native popover API
61import * as DialogPrimitive from '@radix-ui/react-dialog'
62import { cn } from '@/lib/utils'
63 
64const DialogPortal = DialogPrimitive.Portal
65 
66export function DialogOverlay({
67  className,
68  ref,
69  ...props
70}: React.ComponentPropsWithoutRef<typeof DialogPrimitive.Overlay> & {
71  ref?: React.Ref<HTMLDivElement>
72}) {
73  return (
74    <DialogPrimitive.Overlay
75      ref={ref}
76      className={cn(
77        'fixed inset-0 z-50 bg-black/80',
78        'data-[state=open]:animate-fade-in data-[state=closed]:animate-fade-out',
79        className
80      )}
81      {...props}
82    />
83  )
84}
85 
86export function DialogContent({
87  className,
88  children,
89  ref,
90  ...props
91}: React.ComponentPropsWithoutRef<typeof DialogPrimitive.Content> & {
92  ref?: React.Ref<HTMLDivElement>
93}) {
94  return (
95    <DialogPortal>
96      <DialogOverlay />
97      <DialogPrimitive.Content
98        ref={ref}
99        className={cn(
100          'fixed left-1/2 top-1/2 z-50 grid w-full max-w-lg -translate-x-1/2 -translate-y-1/2 gap-4 border border-border bg-background p-6 shadow-lg sm:rounded-lg',
101          'data-[state=open]:animate-dialog-in data-[state=closed]:animate-dialog-out',
102          className
103        )}
104        {...props}
105      >
106        {children}
107      </DialogPrimitive.Content>
108    </DialogPortal>
109  )
110}
111```
112 
113## Pattern 6: Dark Mode with CSS (v4)
114 
115```typescript
116// providers/ThemeProvider.tsx - Simplified for v4
117'use client'
118 
119import { createContext, useContext, useEffect, useState } from 'react'
120 
121type Theme = 'dark' | 'light' | 'system'
122 
123interface ThemeContextType {
124  theme: Theme
125  setTheme: (theme: Theme) => void
126  resolvedTheme: 'dark' | 'light'
127}
128 
129const ThemeContext = createContext<ThemeContextType | undefined>(undefined)
130 
131export function ThemeProvider({
132  children,
133  defaultTheme = 'system',
134  storageKey = 'theme',
135}: {
136  children: React.ReactNode
137  defaultTheme?: Theme
138  storageKey?: string
139}) {
140  const [theme, setTheme] = useState<Theme>(defaultTheme)
141  const [resolvedTheme, setResolvedTheme] = useState<'dark' | 'light'>('light')
142 
143  useEffect(() => {
144    const stored = localStorage.getItem(storageKey) as Theme | null
145    if (stored) setTheme(stored)
146  }, [storageKey])
147 
148  useEffect(() => {
149    const root = document.documentElement
150    root.classList.remove('light', 'dark')
151 
152    const resolved = theme === 'system'
153      ? (window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light')
154      : theme
155 
156    root.classList.add(resolved)
157    setResolvedTheme(resolved)
158 
159    // Update meta theme-color for mobile browsers
160    const metaThemeColor = document.querySelector('meta[name="theme-color"]')
161    if (metaThemeColor) {
162      metaThemeColor.setAttribute('content', resolved === 'dark' ? '#09090b' : '#ffffff')
163    }
164  }, [theme])
165 
166  return (
167    <ThemeContext.Provider value={{
168      theme,
169      setTheme: (newTheme) => {
170        localStorage.setItem(storageKey, newTheme)
171        setTheme(newTheme)
172      },
173      resolvedTheme,
174    }}>
175      {children}
176    </ThemeContext.Provider>
177  )
178}
179 
180export const useTheme = () => {
181  const context = useContext(ThemeContext)
182  if (!context) throw new Error('useTheme must be used within ThemeProvider')
183  return context
184}
185 
186// components/ThemeToggle.tsx
187import { Moon, Sun } from 'lucide-react'
188import { useTheme } from '@/providers/ThemeProvider'
189 
190export function ThemeToggle() {
191  const { resolvedTheme, setTheme } = useTheme()
192 
193  return (
194    <Button
195      variant="ghost"
196      size="icon"
197      onClick={() => setTheme(resolvedTheme === 'dark' ? 'light' : 'dark')}
198    >
199      <Sun className="size-5 rotate-0 scale-100 transition-all dark:-rotate-90 dark:scale-0" />
200      <Moon className="absolute size-5 rotate-90 scale-0 transition-all dark:rotate-0 dark:scale-100" />
201      <span className="sr-only">Toggle theme</span>
202    </Button>
203  )
204}
205```
206 
207## Advanced v4 Patterns
208 
209### Custom Utilities with `@utility`
210 
211Define reusable custom utilities:
212 
213```css
214/* Custom utility for decorative lines */
215@utility line-t {
216  @apply relative before:absolute before:top-0 before:-left-[100vw] before:h-px before:w-[200vw] before:bg-gray-950/5 dark:before:bg-white/10;
217}
218 
219/* Custom utility for text gradients */
220@utility text-gradient {
221  @apply bg-gradient-to-r from-primary to-accent bg-clip-text text-transparent;
222}
223```
224 
225### Theme Modifiers
226 
227```css
228/* Use @theme inline when referencing other CSS variables */
229@theme inline {
230  --font-sans: var(--font-inter), system-ui;
231}
232 
233/* Use @theme static to always generate CSS variables (even when unused) */
234@theme static {
235  --color-brand: oklch(65% 0.15 240);
236}
237 
238/* Import with theme options */
239@import "tailwindcss" theme(static);
240```
241 
242### Namespace Overrides
243 
244```css
245@theme {
246  /* Clear all default colors and define your own */
247  --color-*: initial;
248  --color-white: #fff;
249  --color-black: #000;
250  --color-primary: oklch(45% 0.2 260);
251  --color-secondary: oklch(65% 0.15 200);
252 
253  /* Clear ALL defaults for a minimal setup */
254  /* --*: initial; */
255}
256```
257 
258### Semi-transparent Color Variants
259 
260```css
261@theme {
262  /* Use color-mix() for alpha variants */
263  --color-primary-50: color-mix(in oklab, var(--color-primary) 5%, transparent);
264  --color-primary-100: color-mix(
265    in oklab,
266    var(--color-primary) 10%,
267    transparent
268  );
269  --color-primary-200: color-mix(
270    in oklab,
271    var(--color-primary) 20%,
272    transparent
273  );
274}
275```
276 
277### Container Queries
278 
279```css
280@theme {
281  --container-xs: 20rem;
282  --container-sm: 24rem;
283  --container-md: 28rem;
284  --container-lg: 32rem;
285}
286```
287 
288## v3 to v4 Migration Checklist
289 
290- [ ] Replace `tailwind.config.ts` with CSS `@theme` block
291- [ ] Change `@tailwind base/components/utilities` to `@import "tailwindcss"`
292- [ ] Move color definitions to `@theme { --color-*: value }`
293- [ ] Replace `darkMode: "class"` with `@custom-variant dark`
294- [ ] Move `@keyframes` inside `@theme` blocks (ensures keyframes output with theme)
295- [ ] Replace `require("tailwindcss-animate")` with native CSS animations
296- [ ] Update `h-10 w-10` to `size-10` (new utility)
297- [ ] Remove `forwardRef` (React 19 passes ref as prop)
298- [ ] Consider OKLCH colors for better color perception
299- [ ] Replace custom plugins with `@utility` directives
300 
301## Best Practices
302 
303### Do's
304 
305- **Use `@theme` blocks** - CSS-first configuration is v4's core pattern
306- **Use OKLCH colors** - Better perceptual uniformity than HSL
307- **Compose with CVA** - Type-safe variants
308- **Use semantic tokens** - `bg-primary` not `bg-blue-500`
309- **Use `size-*`** - New shorthand for `w-* h-*`
310- **Add accessibility** - ARIA attributes, focus states
311 
312### Don'ts
313 
314- **Don't use `tailwind.config.ts`** - Use CSS `@theme` instead
315- **Don't use `@tailwind` directives** - Use `@import "tailwindcss"`
316- **Don't use `forwardRef`** - React 19 passes ref as prop
317- **Don't use arbitrary values** - Extend `@theme` instead
318- **Don't hardcode colors** - Use semantic tokens
319- **Don't forget dark mode** - Test both themes
320