Tailwind CSS Development Patterns
Expert guide for building modern, responsive user interfaces with Tailwind CSS utility-first framework. Covers v4.1+ features including CSS-first configuration, custom utilities, and enhanced developer experience.
Overview
Provides actionable patterns for responsive, accessible UIs with Tailwind CSS v4.1+. Covers utility composition, dark mode, component patterns, and performance optimization.
When to Use
- Styling React/Vue/Svelte components
- Building responsive layouts and grids
- Implementing design systems
- Adding dark mode support
- Optimizing CSS workflow
Quick Reference
Responsive Breakpoints
| Prefix |
Min Width |
Description |
sm: |
640px |
Small screens |
md: |
768px |
Tablets |
lg: |
1024px |
Desktops |
xl: |
1280px |
Large screens |
2xl: |
1536px |
Extra large |
Common Patterns
<!-- Center content -->
<div class="flex min-h-screen items-center justify-center">Content</div>
<!-- Responsive grid -->
<div class="grid grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-4">
<!-- Items -->
</div>
<!-- Card component -->
<div class="rounded-lg bg-white p-6 shadow-lg">
<h3 class="text-xl font-bold">Title</h3>
<p class="text-gray-600">Description</p>
</div>
Instructions
- Start Mobile-First: Write base styles for mobile, add responsive prefixes (
sm:, md:, lg:) for larger screens
- Use Design Tokens: Leverage Tailwind's spacing, color, and typography scales
- Compose Utilities: Combine multiple utilities for complex styles
- Extract Components: Create reusable component classes for repeated patterns
- Configure Theme: Customize design tokens in
tailwind.config.js or using @theme
- Verify Changes: Test at each breakpoint using DevTools responsive mode. Check for visual regressions and accessibility issues before committing.
Examples
Responsive Card Component
function ProductCard({ product }: { product: Product }) {
return (
<div className="overflow-hidden rounded-lg bg-white shadow-lg sm:flex">
<img className="h-48 w-full object-cover sm:h-auto sm:w-48" src={product.image} />
<div className="p-6">
<h3 className="text-lg font-semibold">{product.name}</h3>
<button className="mt-4 rounded-lg bg-indigo-600 px-4 py-2 text-white hover:bg-indigo-700">Add to Cart</button>
</div>
</div>
);
}
Dark Mode Toggle
<div class="bg-white text-gray-900 dark:bg-gray-900 dark:text-white">
<h1 class="dark:text-white">Title</h1>
</div>
Form Input
<input
class="w-full rounded-lg border border-gray-300 px-4 py-2 focus:border-transparent focus:ring-2 focus:ring-blue-500"
placeholder="you@example.com"
/>
Best Practices
- Consistent Spacing: Use Tailwind's spacing scale (4, 8, 12, 16, etc.)
- Color Palette: Stick to Tailwind's color system for consistency
- Component Extraction: Extract repeated patterns into reusable components
- Utility Composition: Prefer utility classes over
@apply for maintainability
- Semantic HTML: Use proper HTML elements with Tailwind classes
- Performance: Ensure content paths include all template files for optimal purging
- Accessibility: Include focus styles, ARIA labels, and respect user preferences (reduced-motion)
Troubleshooting
Classes Not Applying
- Check content paths: Ensure all template files are included in
content: [] in config
- Verify build: Run
npm run build to regenerate purged CSS
- Dev mode: Use
npx tailwindcss -o with --watch flag for live updates
Responsive Styles Not Working
- Order matters: Responsive prefixes must come before non-responsive (e.g.,
md:flex not flex md:flex)
- Check breakpoint values: Verify breakpoints match your design requirements
- DevTools: Use browser DevTools responsive mode to test at each breakpoint
Dark Mode Issues
- Verify config: Ensure
darkMode: 'class' or 'media' is set correctly
- Toggle implementation: Use
document.documentElement.classList.toggle('dark') for class strategy
- Initial flash: Add
dark class to <html> before body renders
Constraints and Warnings
- Class Proliferation: Long class strings reduce readability; extract into components
- Content Paths: Misconfigured paths cause classes to be purged in production
- Arbitrary Values: Use sparingly; prefer design tokens for consistency
- Specificity Issues: Avoid
@apply with complex selectors
- Dark Mode: Requires correct configuration (
class or media strategy)
- Browser Support: Check Tailwind docs for compatibility notes
References
- references/layout-patterns.md — Flexbox, grid, spacing, typography, colors
- references/component-patterns.md — Cards, navigation, forms, modals, React patterns
- references/responsive-design.md — Responsive patterns, dark mode, container queries
- references/animations.md — Transitions, transforms, built-in animations, motion preferences
- references/performance.md — Bundle optimization, CSS optimization, production builds
- references/accessibility.md — Focus management, screen readers, color contrast, ARIA
- references/configuration.md — CSS-first config, JavaScript config, plugins, presets
- references/reference.md — Additional reference materials
External Resources
1---2name: tailwind-css-patterns3description: Provides comprehensive Tailwind CSS utility-first styling patterns including responsive design, layout utilities, flexbox, grid, spacing, typography, colors, and modern CSS best practices. Use when styling React/Vue/Svelte components, building responsive layouts, implementing design systems, or optimizing CSS workflow.4---56# Tailwind CSS Development Patterns78Expert guide for building modern, responsive user interfaces with Tailwind CSS utility-first framework. Covers v4.1+ features including CSS-first configuration, custom utilities, and enhanced developer experience.910## Overview1112Provides actionable patterns for responsive, accessible UIs with Tailwind CSS v4.1+. Covers utility composition, dark mode, component patterns, and performance optimization.1314## When to Use1516- Styling React/Vue/Svelte components17- Building responsive layouts and grids18- Implementing design systems19- Adding dark mode support20- Optimizing CSS workflow2122## Quick Reference2324### Responsive Breakpoints2526| Prefix | Min Width | Description |27| ------ | --------- | ------------- |28| `sm:` | 640px | Small screens |29| `md:` | 768px | Tablets |30| `lg:` | 1024px | Desktops |31| `xl:` | 1280px | Large screens |32| `2xl:` | 1536px | Extra large |3334### Common Patterns3536```html37<!-- Center content -->38<div class="flex min-h-screen items-center justify-center">Content</div>3940<!-- Responsive grid -->41<div class="grid grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-4">42 <!-- Items -->43</div>4445<!-- Card component -->46<div class="rounded-lg bg-white p-6 shadow-lg">47 <h3 class="text-xl font-bold">Title</h3>48 <p class="text-gray-600">Description</p>49</div>50```5152## Instructions53541. **Start Mobile-First**: Write base styles for mobile, add responsive prefixes (`sm:`, `md:`, `lg:`) for larger screens552. **Use Design Tokens**: Leverage Tailwind's spacing, color, and typography scales563. **Compose Utilities**: Combine multiple utilities for complex styles574. **Extract Components**: Create reusable component classes for repeated patterns585. **Configure Theme**: Customize design tokens in `tailwind.config.js` or using `@theme`596. **Verify Changes**: Test at each breakpoint using DevTools responsive mode. Check for visual regressions and accessibility issues before committing.6061## Examples6263### Responsive Card Component6465```tsx66function ProductCard({ product }: { product: Product }) {67 return (68 <div className="overflow-hidden rounded-lg bg-white shadow-lg sm:flex">69 <img className="h-48 w-full object-cover sm:h-auto sm:w-48" src={product.image} />70 <div className="p-6">71 <h3 className="text-lg font-semibold">{product.name}</h3>72 <button className="mt-4 rounded-lg bg-indigo-600 px-4 py-2 text-white hover:bg-indigo-700">Add to Cart</button>73 </div>74 </div>75 );76}77```7879### Dark Mode Toggle8081```html82<div class="bg-white text-gray-900 dark:bg-gray-900 dark:text-white">83 <h1 class="dark:text-white">Title</h1>84</div>85```8687### Form Input8889```html90<input91 class="w-full rounded-lg border border-gray-300 px-4 py-2 focus:border-transparent focus:ring-2 focus:ring-blue-500"92 placeholder="you@example.com"93/>94```9596## Best Practices97981. **Consistent Spacing**: Use Tailwind's spacing scale (4, 8, 12, 16, etc.)992. **Color Palette**: Stick to Tailwind's color system for consistency1003. **Component Extraction**: Extract repeated patterns into reusable components1014. **Utility Composition**: Prefer utility classes over `@apply` for maintainability1025. **Semantic HTML**: Use proper HTML elements with Tailwind classes1036. **Performance**: Ensure content paths include all template files for optimal purging1047. **Accessibility**: Include focus styles, ARIA labels, and respect user preferences (reduced-motion)105106## Troubleshooting107108### Classes Not Applying109110- **Check content paths**: Ensure all template files are included in `content: []` in config111- **Verify build**: Run `npm run build` to regenerate purged CSS112- **Dev mode**: Use `npx tailwindcss -o` with `--watch` flag for live updates113114### Responsive Styles Not Working115116- **Order matters**: Responsive prefixes must come before non-responsive (e.g., `md:flex` not `flex md:flex`)117- **Check breakpoint values**: Verify breakpoints match your design requirements118- **DevTools**: Use browser DevTools responsive mode to test at each breakpoint119120### Dark Mode Issues121122- **Verify config**: Ensure `darkMode: 'class'` or `'media'` is set correctly123- **Toggle implementation**: Use `document.documentElement.classList.toggle('dark')` for class strategy124- **Initial flash**: Add `dark` class to `<html>` before body renders125126## Constraints and Warnings127128- **Class Proliferation**: Long class strings reduce readability; extract into components129- **Content Paths**: Misconfigured paths cause classes to be purged in production130- **Arbitrary Values**: Use sparingly; prefer design tokens for consistency131- **Specificity Issues**: Avoid `@apply` with complex selectors132- **Dark Mode**: Requires correct configuration (`class` or `media` strategy)133- **Browser Support**: Check Tailwind docs for compatibility notes134135## References136137- **[references/layout-patterns.md](references/layout-patterns.md)** — Flexbox, grid, spacing, typography, colors138- **[references/component-patterns.md](references/component-patterns.md)** — Cards, navigation, forms, modals, React patterns139- **[references/responsive-design.md](references/responsive-design.md)** — Responsive patterns, dark mode, container queries140- **[references/animations.md](references/animations.md)** — Transitions, transforms, built-in animations, motion preferences141- **[references/performance.md](references/performance.md)** — Bundle optimization, CSS optimization, production builds142- **[references/accessibility.md](references/accessibility.md)** — Focus management, screen readers, color contrast, ARIA143- **[references/configuration.md](references/configuration.md)** — CSS-first config, JavaScript config, plugins, presets144- **[references/reference.md](references/reference.md)** — Additional reference materials145146## External Resources147148- [Tailwind CSS Docs](https://tailwindcss.com/docs)149- [Tailwind UI](https://tailwindui.com)150- [Tailwind Play](https://play.tailwindcss.com)
legions-developer