<!-- cache:start -->
Tailwind CSS v4 Best Practices
You have access to up-to-date Tailwind CSS documentation via MCP tools. Use these tools to provide accurate, current information.
Available MCP Tools
Use these tools for dynamic, up-to-date Tailwind information:
mcp__tailwindcss__search_tailwind_docs
Use when user asks about any Tailwind feature, utility, or concept.
Examples:
- "How do I use dark mode in Tailwind?"
- "What are container queries?"
- "How do responsive breakpoints work?"
mcp__tailwindcss__get_tailwind_utilities
Use when user needs utility classes for a specific CSS property.
Examples:
- "What utilities are available for flexbox?"
- "Show me spacing utilities"
- "What text alignment classes exist?"
mcp__tailwindcss__get_tailwind_colors
Use when user asks about colors, palettes, or color-related utilities.
Examples:
- "What colors are available?"
- "Show me the blue palette shades"
- "How do I use custom colors?"
mcp__tailwindcss__convert_css_to_tailwind
Use when user has CSS they want to convert to Tailwind utility classes.
Examples:
- "Convert this CSS to Tailwind: display: flex; justify-content: center;"
- "What's the Tailwind equivalent of margin: 0 auto?"
mcp__tailwindcss__generate_component_template
Use when user needs a component template with Tailwind styling.
Examples:
- "Generate a button component"
- "Create a card template"
- "Show me a navbar example"
Official Documentation URLs
When MCP tools are unavailable, use WebFetch with these URLs to get current documentation:
Getting Started
Core Concepts
Layout
Spacing
Sizing
Typography
Backgrounds & Borders
Effects
Transforms & Animation
Interactivity
Tailwind CSS v4 Core Syntax
CRITICAL: Tailwind v4 changed significantly from v3. Always use v4 syntax.
CSS Entry Point
This single import replaces the old
@tailwind base; @tailwind components; @tailwind utilities;
directives.
Theme Configuration (@theme directive)
All theme customization is done in CSS, not JavaScript:
css
@theme {
/* Colors - use oklch for better color manipulation */
--color-primary: oklch(0.6 0.2 250);
--color-primary-foreground: oklch(1 0 0);
--color-secondary: oklch(0.5 0.02 250);
--color-secondary-foreground: oklch(1 0 0);
/* Semantic colors */
--color-background: oklch(1 0 0);
--color-foreground: oklch(0.145 0 0);
--color-muted: oklch(0.95 0 0);
--color-muted-foreground: oklch(0.4 0 0);
--color-border: oklch(0.9 0 0);
--color-destructive: oklch(0.55 0.25 25);
/* Font families */
--font-sans: "Inter", ui-sans-serif, system-ui, sans-serif;
--font-mono: "Fira Code", ui-monospace, monospace;
/* Custom spacing (extends default scale) */
--spacing-18: 4.5rem;
--spacing-22: 5.5rem;
/* Custom border radius */
--radius-4xl: 2rem;
}
Source Detection (@source directive)
Tailwind auto-detects most template files. Use
for custom paths:
css
@source "./templates/**/*.templ";
@source "./components/**/*.html";
@source "./src/**/*.{js,jsx,ts,tsx,vue,svelte}";
Dark Mode (@variant directive)
css
@variant dark {
--color-background: oklch(0.145 0 0);
--color-foreground: oklch(0.985 0 0);
--color-muted: oklch(0.25 0 0);
--color-muted-foreground: oklch(0.6 0 0);
--color-border: oklch(0.3 0 0);
--color-card: oklch(0.205 0 0);
}
Component Layer (@layer components)
Extract repeated patterns:
css
@layer components {
.btn {
@apply px-4 py-2 rounded-lg font-medium transition-colors;
}
.btn-primary {
@apply btn bg-primary text-primary-foreground hover:bg-primary/90;
}
.btn-secondary {
@apply btn bg-secondary text-secondary-foreground hover:bg-secondary/90;
}
.card {
@apply p-6 bg-card rounded-xl border border-border shadow-sm;
}
}
Plugins (@plugin directive)
css
@plugin "@tailwindcss/typography";
Best Practices
Class Ordering Convention
Order utilities consistently for readability:
Order: layout → spacing → sizing → typography → colors → effects → interactive
html
<!-- Good: Logical order -->
<div class="flex items-center gap-4 p-4 w-full text-sm text-gray-700 bg-white shadow-sm hover:bg-gray-50 transition-colors">
<!-- Bad: Random order -->
<div class="hover:bg-gray-50 flex bg-white p-4 text-sm shadow-sm w-full gap-4 items-center text-gray-700 transition-colors">
Responsive Design
Mobile-first: base styles for mobile, add breakpoints for larger screens.
html
<!-- Mobile first -->
<div class="w-full md:w-1/2 lg:w-1/3">
<!-- Breakpoints -->
sm: 640px <!-- Small devices -->
md: 768px <!-- Medium devices -->
lg: 1024px <!-- Large devices -->
xl: 1280px <!-- Extra large -->
2xl: 1536px <!-- 2X large -->
Component Extraction Rule
Extract when a class combination appears 3+ times:
css
/* Instead of repeating in HTML */
@layer components {
.flex-center {
@apply flex items-center justify-center;
}
.text-muted {
@apply text-sm text-muted-foreground;
}
}
Use Theme Variables
Always prefer theme variables over hardcoded values:
html
<!-- Good: Uses theme variable -->
<div class="bg-primary text-primary-foreground">
<!-- Bad: Hardcoded color -->
<div class="bg-[#3b82f6] text-white">
Accessibility
html
<!-- Focus states -->
<button class="focus-visible:ring-2 focus-visible:ring-primary focus-visible:outline-none">
<!-- Screen reader only -->
<span class="sr-only">Close menu</span>
<!-- Ensure contrast -->
<!-- Use oklch colors with sufficient lightness difference -->
v4 Anti-Patterns to Avoid
DO NOT USE (v3 patterns):
| Wrong (v3) | Correct (v4) |
|---|
| CSS directive |
| |
| (included in import) |
| (included in import) |
| in config | in CSS |
| in JS | in @theme |
| in JS | in CSS |
Common Mistakes
html
<!-- Wrong: Inline styles when utility exists -->
<div style="display: flex; gap: 1rem;">
<!-- Correct -->
<div class="flex gap-4">
<!-- Wrong: px values when scale exists -->
<div class="p-[16px]">
<!-- Correct -->
<div class="p-4">
<!-- Wrong: Duplicate utilities -->
<div class="p-4 p-6">
<!-- Correct -->
<div class="p-6">
<!-- Wrong: Conflicting utilities -->
<div class="flex block">
<!-- Correct: Choose one -->
<div class="flex">
Response Guidelines
When helping with Tailwind CSS:
- Always use v4 syntax - No tailwind.config.js, use @theme in CSS
- Use MCP tools first - Get current documentation before answering
- Prefer theme variables - not
- Include accessibility - Add focus-visible, sr-only where appropriate
- Show complete examples - Include all necessary classes
- Explain class choices - Help users understand why
Example Response Flow
User: "How do I create a button with hover effect?"
Response:
- Use
mcp__tailwindcss__get_tailwind_utilities
- Provide example with proper class ordering:
html
<button class="px-4 py-2 rounded-lg font-medium bg-primary text-primary-foreground hover:bg-primary/90 focus-visible:ring-2 focus-visible:ring-primary focus-visible:outline-none transition-colors">
Click me
</button>
- Explain the classes used
- Suggest extracting to component if used multiple times
Quick Reference
Spacing Scale
| Class | Size |
|---|
| 1 | 0.25rem (4px) |
| 2 | 0.5rem (8px) |
| 3 | 0.75rem (12px) |
| 4 | 1rem (16px) |
| 5 | 1.25rem (20px) |
| 6 | 1.5rem (24px) |
| 8 | 2rem (32px) |
| 10 | 2.5rem (40px) |
| 12 | 3rem (48px) |
| 16 | 4rem (64px) |
Common Patterns
html
<!-- Centered content -->
<div class="flex items-center justify-center">
<!-- Card -->
<div class="p-6 bg-card rounded-xl border border-border shadow-sm">
<!-- Responsive grid -->
<div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
<!-- Truncated text -->
<p class="truncate">Long text that will be truncated...</p>
<!-- Gradient background -->
<div class="bg-gradient-to-r from-primary to-secondary">
<!-- Fixed header -->
<header class="fixed top-0 left-0 right-0 z-50 bg-background/80 backdrop-blur-sm">
For the latest documentation, always refer to https://tailwindcss.com/docs
<!-- cache:end -->