1# tailwind-design-system — detailed patterns and worked examples
2 
3## Patterns
4 
5### Pattern 1: CVA (Class Variance Authority) Components
6 
7```typescript
8// components/ui/button.tsx
9import { Slot } from '@radix-ui/react-slot'
10import { cva, type VariantProps } from 'class-variance-authority'
11import { cn } from '@/lib/utils'
12 
13const buttonVariants = cva(
14  // Base styles - v4 uses native CSS variables
15  'inline-flex items-center justify-center whitespace-nowrap rounded-md text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50',
16  {
17    variants: {
18      variant: {
19        default: 'bg-primary text-primary-foreground hover:bg-primary/90',
20        destructive: 'bg-destructive text-destructive-foreground hover:bg-destructive/90',
21        outline: 'border border-border bg-background hover:bg-accent hover:text-accent-foreground',
22        secondary: 'bg-secondary text-secondary-foreground hover:bg-secondary/80',
23        ghost: 'hover:bg-accent hover:text-accent-foreground',
24        link: 'text-primary underline-offset-4 hover:underline',
25      },
26      size: {
27        default: 'h-10 px-4 py-2',
28        sm: 'h-9 rounded-md px-3',
29        lg: 'h-11 rounded-md px-8',
30        icon: 'size-10',
31      },
32    },
33    defaultVariants: {
34      variant: 'default',
35      size: 'default',
36    },
37  }
38)
39 
40export interface ButtonProps
41  extends React.ButtonHTMLAttributes<HTMLButtonElement>,
42    VariantProps<typeof buttonVariants> {
43  asChild?: boolean
44}
45 
46// React 19: No forwardRef needed
47export function Button({
48  className,
49  variant,
50  size,
51  asChild = false,
52  ref,
53  ...props
54}: ButtonProps & { ref?: React.Ref<HTMLButtonElement> }) {
55  const Comp = asChild ? Slot : 'button'
56  return (
57    <Comp
58      className={cn(buttonVariants({ variant, size, className }))}
59      ref={ref}
60      {...props}
61    />
62  )
63}
64 
65// Usage
66<Button variant="destructive" size="lg">Delete</Button>
67<Button variant="outline">Cancel</Button>
68<Button asChild><Link href="/home">Home</Link></Button>
69```
70 
71### Pattern 2: Compound Components (React 19)
72 
73```typescript
74// components/ui/card.tsx
75import { cn } from '@/lib/utils'
76 
77// React 19: ref is a regular prop, no forwardRef
78export function Card({
79  className,
80  ref,
81  ...props
82}: React.HTMLAttributes<HTMLDivElement> & { ref?: React.Ref<HTMLDivElement> }) {
83  return (
84    <div
85      ref={ref}
86      className={cn(
87        'rounded-lg border border-border bg-card text-card-foreground shadow-sm',
88        className
89      )}
90      {...props}
91    />
92  )
93}
94 
95export function CardHeader({
96  className,
97  ref,
98  ...props
99}: React.HTMLAttributes<HTMLDivElement> & { ref?: React.Ref<HTMLDivElement> }) {
100  return (
101    <div
102      ref={ref}
103      className={cn('flex flex-col space-y-1.5 p-6', className)}
104      {...props}
105    />
106  )
107}
108 
109export function CardTitle({
110  className,
111  ref,
112  ...props
113}: React.HTMLAttributes<HTMLHeadingElement> & { ref?: React.Ref<HTMLHeadingElement> }) {
114  return (
115    <h3
116      ref={ref}
117      className={cn('text-2xl font-semibold leading-none tracking-tight', className)}
118      {...props}
119    />
120  )
121}
122 
123export function CardDescription({
124  className,
125  ref,
126  ...props
127}: React.HTMLAttributes<HTMLParagraphElement> & { ref?: React.Ref<HTMLParagraphElement> }) {
128  return (
129    <p
130      ref={ref}
131      className={cn('text-sm text-muted-foreground', className)}
132      {...props}
133    />
134  )
135}
136 
137export function CardContent({
138  className,
139  ref,
140  ...props
141}: React.HTMLAttributes<HTMLDivElement> & { ref?: React.Ref<HTMLDivElement> }) {
142  return (
143    <div ref={ref} className={cn('p-6 pt-0', className)} {...props} />
144  )
145}
146 
147export function CardFooter({
148  className,
149  ref,
150  ...props
151}: React.HTMLAttributes<HTMLDivElement> & { ref?: React.Ref<HTMLDivElement> }) {
152  return (
153    <div
154      ref={ref}
155      className={cn('flex items-center p-6 pt-0', className)}
156      {...props}
157    />
158  )
159}
160 
161// Usage
162<Card>
163  <CardHeader>
164    <CardTitle>Account</CardTitle>
165    <CardDescription>Manage your account settings</CardDescription>
166  </CardHeader>
167  <CardContent>
168    <form>...</form>
169  </CardContent>
170  <CardFooter>
171    <Button>Save</Button>
172  </CardFooter>
173</Card>
174```
175 
176### Pattern 3: Form Components
177 
178```typescript
179// components/ui/input.tsx
180import { cn } from '@/lib/utils'
181 
182export interface InputProps extends React.InputHTMLAttributes<HTMLInputElement> {
183  error?: string
184  ref?: React.Ref<HTMLInputElement>
185}
186 
187export function Input({ className, type, error, ref, ...props }: InputProps) {
188  return (
189    <div className="relative">
190      <input
191        type={type}
192        className={cn(
193          'flex h-10 w-full rounded-md border border-border bg-background px-3 py-2 text-sm ring-offset-background file:border-0 file:bg-transparent file:text-sm file:font-medium placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50',
194          error && 'border-destructive focus-visible:ring-destructive',
195          className
196        )}
197        ref={ref}
198        aria-invalid={!!error}
199        aria-describedby={error ? `${props.id}-error` : undefined}
200        {...props}
201      />
202      {error && (
203        <p
204          id={`${props.id}-error`}
205          className="mt-1 text-sm text-destructive"
206          role="alert"
207        >
208          {error}
209        </p>
210      )}
211    </div>
212  )
213}
214 
215// components/ui/label.tsx
216import { cva, type VariantProps } from 'class-variance-authority'
217 
218const labelVariants = cva(
219  'text-sm font-medium leading-none peer-disabled:cursor-not-allowed peer-disabled:opacity-70'
220)
221 
222export function Label({
223  className,
224  ref,
225  ...props
226}: React.LabelHTMLAttributes<HTMLLabelElement> & { ref?: React.Ref<HTMLLabelElement> }) {
227  return (
228    <label ref={ref} className={cn(labelVariants(), className)} {...props} />
229  )
230}
231 
232// Usage with React Hook Form + Zod
233import { useForm } from 'react-hook-form'
234import { zodResolver } from '@hookform/resolvers/zod'
235import { z } from 'zod'
236 
237const schema = z.object({
238  email: z.string().email('Invalid email address'),
239  password: z.string().min(8, 'Password must be at least 8 characters'),
240})
241 
242function LoginForm() {
243  const { register, handleSubmit, formState: { errors } } = useForm({
244    resolver: zodResolver(schema),
245  })
246 
247  return (
248    <form onSubmit={handleSubmit(onSubmit)} className="space-y-4">
249      <div className="space-y-2">
250        <Label htmlFor="email">Email</Label>
251        <Input
252          id="email"
253          type="email"
254          {...register('email')}
255          error={errors.email?.message}
256        />
257      </div>
258      <div className="space-y-2">
259        <Label htmlFor="password">Password</Label>
260        <Input
261          id="password"
262          type="password"
263          {...register('password')}
264          error={errors.password?.message}
265        />
266      </div>
267      <Button type="submit" className="w-full">Sign In</Button>
268    </form>
269  )
270}
271```
272 
273### Pattern 4: Responsive Grid System
274 
275```typescript
276// components/ui/grid.tsx
277import { cn } from '@/lib/utils'
278import { cva, type VariantProps } from 'class-variance-authority'
279 
280const gridVariants = cva('grid', {
281  variants: {
282    cols: {
283      1: 'grid-cols-1',
284      2: 'grid-cols-1 sm:grid-cols-2',
285      3: 'grid-cols-1 sm:grid-cols-2 lg:grid-cols-3',
286      4: 'grid-cols-1 sm:grid-cols-2 lg:grid-cols-4',
287      5: 'grid-cols-2 sm:grid-cols-3 lg:grid-cols-5',
288      6: 'grid-cols-2 sm:grid-cols-3 lg:grid-cols-6',
289    },
290    gap: {
291      none: 'gap-0',
292      sm: 'gap-2',
293      md: 'gap-4',
294      lg: 'gap-6',
295      xl: 'gap-8',
296    },
297  },
298  defaultVariants: {
299    cols: 3,
300    gap: 'md',
301  },
302})
303 
304interface GridProps
305  extends React.HTMLAttributes<HTMLDivElement>,
306    VariantProps<typeof gridVariants> {}
307 
308export function Grid({ className, cols, gap, ...props }: GridProps) {
309  return (
310    <div className={cn(gridVariants({ cols, gap, className }))} {...props} />
311  )
312}
313 
314// Container component
315const containerVariants = cva('mx-auto w-full px-4 sm:px-6 lg:px-8', {
316  variants: {
317    size: {
318      sm: 'max-w-screen-sm',
319      md: 'max-w-screen-md',
320      lg: 'max-w-screen-lg',
321      xl: 'max-w-screen-xl',
322      '2xl': 'max-w-screen-2xl',
323      full: 'max-w-full',
324    },
325  },
326  defaultVariants: {
327    size: 'xl',
328  },
329})
330 
331interface ContainerProps
332  extends React.HTMLAttributes<HTMLDivElement>,
333    VariantProps<typeof containerVariants> {}
334 
335export function Container({ className, size, ...props }: ContainerProps) {
336  return (
337    <div className={cn(containerVariants({ size, className }))} {...props} />
338  )
339}
340 
341// Usage
342<Container>
343  <Grid cols={4} gap="lg">
344    {products.map((product) => (
345      <ProductCard key={product.id} product={product} />
346    ))}
347  </Grid>
348</Container>
349```
350 
351For advanced animation and dark mode patterns, see [references/advanced-patterns.md](references/advanced-patterns.md):
352 
353- **Pattern 5: Native CSS Animations** — dialog `@keyframes`, native popover API with `@starting-style`, `allow-discrete` transitions, and a full `DialogContent`/`DialogOverlay` implementation using Radix UI
354- **Pattern 6: Dark Mode** — `ThemeProvider` context with `localStorage` persistence, `prefers-color-scheme` detection, meta `theme-color` update, and a `ThemeToggle` button component
355 
356## Utility Functions
357 
358```typescript
359// lib/utils.ts
360import { type ClassValue, clsx } from "clsx";
361import { twMerge } from "tailwind-merge";
362 
363export function cn(...inputs: ClassValue[]) {
364  return twMerge(clsx(inputs));
365}
366 
367// Focus ring utility
368export const focusRing = cn(
369  "focus-visible:outline-none focus-visible:ring-2",
370  "focus-visible:ring-ring focus-visible:ring-offset-2",
371);
372 
373// Disabled utility
374export const disabled = "disabled:pointer-events-none disabled:opacity-50";
375```
376 
377For advanced v4 CSS patterns, the full v3-to-v4 migration checklist, and complete best practices, see [references/advanced-patterns.md](references/advanced-patterns.md):
378 
379- **Custom `@utility`** — reusable CSS utilities for decorative lines and text gradients
380- **Theme modifiers** — `@theme inline` (reference other CSS vars), `@theme static` (always output), `@import "tailwindcss" theme(static)`
381- **Namespace overrides** — clearing default Tailwind color scales with `--color-*: initial`
382- **Semi-transparent variants** — `color-mix()` for alpha scale generation
383- **Container queries** — `--container-*` token definitions
384- **v3→v4 migration checklist** — 10-item checklist covering config, directives, colors, dark mode, animations, React 19 ref changes
385- **Best practices** — full Do's and Don'ts list
386