tailwind-best-practices
Tailwind CSS patterns and conventions. Use when writing responsive designs, implementing dark mode, creating reusable component styles, configuring Tailwind, or migrating from v3 to v4. Triggers on tasks involving Tailwind classes, responsive design, dark mode, CSS styling, or "migrate to Tailwind v4".
- License 许可
- MIT
- 最近更新
- 2026-09-01
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- tailwind-best-practices
- license
- MIT
- metadata
- { "author": "agent-skills", "version": "1.0.0", "tailwindVersion": "3.4+ / 4.0+" }
- description
- Tailwind CSS patterns and conventions. Use when writing responsive designs, implementing dark mode, creating reusable component styles, configuring Tailwind, or migrating from v3 to v4. Triggers on tasks involving Tailwind classes, responsive design, dark mode, CSS styling, or "migrate to Tailwind v4".
02 资源文件 33
- 参考文档AGENTS.md12.7 KB
- 参考文档README.md1.8 KB
- 参考文档rules/_sections.md4.0 KB
- 参考文档rules/_template.md4.1 KB
- 参考文档rules/comp-clsx-cn.md5.1 KB
- 参考文档rules/component-btn-variants.md6.1 KB
- 参考文档rules/component-card-patterns.md6.4 KB
- 参考文档rules/component-form-elements.md8.3 KB
- 参考文档rules/component-modals.md7.7 KB
- 参考文档rules/component-navigation.md8.9 KB
- 参考文档rules/component-tables.md8.5 KB
- 参考文档rules/config-custom-colors.md5.7 KB
- 参考文档rules/config-custom-fonts.md6.4 KB
- 参考文档rules/config-custom-spacing.md4.7 KB
- 参考文档rules/config-extend-theme.md5.5 KB
- 参考文档rules/config-plugins.md7.2 KB
- 参考文档rules/config-presets.md5.7 KB
- 参考文档rules/dark-class-strategy.md4.2 KB
- 参考文档rules/dark-color-scheme.md5.0 KB
- 参考文档rules/dark-custom-colors.md5.5 KB
- 参考文档rules/dark-media-strategy.md4.4 KB
- 参考文档rules/dark-setup.md5.6 KB
- 参考文档rules/dark-transitions.md4.7 KB
- 参考文档rules/resp-mobile-first.md3.4 KB
- 参考文档rules/responsive-aspect-ratio.md3.1 KB
- 参考文档rules/responsive-breakpoint-order.md2.0 KB
- 参考文档rules/responsive-container-queries.md3.5 KB
- 参考文档rules/responsive-fluid-typography.md3.2 KB
- 参考文档rules/responsive-grid-system.md3.7 KB
- 参考文档rules/v4-custom-utilities.md3.9 KB
- 参考文档rules/v4-installation.md2.5 KB
- 参考文档rules/v4-migration.md5.7 KB
- 参考文档rules/v4-theme-configuration.md2.4 KB
03 SKILL.md 正文
Tailwind CSS Best Practices
Comprehensive patterns for building consistent, maintainable interfaces with Tailwind CSS v3.4+ and v4. Contains 29 rules covering responsive design, dark mode, component patterns, configuration, and v4 migration.
Metadata
- Version: 1.0.0
- Framework: Tailwind CSS v3.4+ / v4.0+
- Rule Count: 29 rules across 8 categories
- License: MIT
- Documentation: tailwindcss.com/docs
Step 1: Detect Tailwind Version
Always check the version before giving any advice. v3 and v4 are fundamentally different.
Check package.json for the installed version:
{ "tailwindcss": "^3.x" } // → v3 rules apply
{ "tailwindcss": "^4.x" } // → v4 rules apply
Also check for these signals:
| Signal | Version |
|---|---|
tailwind.config.js exists |
v3 |
@import "tailwindcss" in CSS |
v4 |
@tailwindcss/vite in dependencies |
v4 |
@tailwindcss/postcss in dependencies |
v4 |
@theme {} block in CSS |
v4 |
If v3: Apply resp-, dark-, comp-, config- rules. Note that v4 is available.
If v4: Apply v4- rules. tailwind.config.js patterns do NOT apply — use @theme {} instead.
If migrating v3 → v4: Follow v4-migration rules directly.
When to Apply
Reference these guidelines when:
- Writing responsive layouts
- Implementing dark mode
- Creating reusable component styles
- Configuring Tailwind (v3 or v4)
- Migrating a project from v3 to v4
- Setting up a new project with v4
Rule Categories by Priority
| Priority | Category | Impact | Prefix | Version |
|---|---|---|---|---|
| 1 | Responsive Design | CRITICAL | resp- |
v3 / v4 |
| 2 | Dark Mode | CRITICAL | dark- |
v3 / v4 |
| 3 | Component Patterns | HIGH | comp- |
v3 / v4 |
| 4 | Custom Configuration | HIGH | config- |
v3 |
| 5 | V4 & Migration | HIGH | v4- |
v4 only |
| 6 | Spacing & Typography | MEDIUM | space- |
v3 / v4 |
| 7 | Animation | MEDIUM | anim- |
v3 / v4 |
| 8 | Performance | LOW | perf- |
v3 / v4 |
Quick Reference
1. Responsive Design (CRITICAL)
resp-mobile-first- Mobile-first approachresp-breakpoints- Use breakpoints correctlyresp-container- Container patternsresp-grid-flex- Grid vs Flexbox decisionsresp-hidden-shown- Conditional display
2. Dark Mode (CRITICAL)
dark-setup- Configure dark modedark-classes- Apply dark mode classesdark-toggle- Implement dark mode toggledark-system-preference- Respect system preferencedark-colors- Design for both modes
3. Component Patterns (HIGH)
comp-clsx-cn- Conditional classes utilitycomp-variants- Component variants patterncomp-slots- Slot-based componentscomp-composition- Composing utilities
4. Custom Configuration — v3 only (HIGH)
config-extend- Extend vs override themeconfig-colors- Custom color paletteconfig-fonts- Custom fontsconfig-screens- Custom breakpointsconfig-plugins- Using plugins
5. V4 & Migration (HIGH)
v4-installation- Install v4 with Vite or PostCSS,@source,@referencev4-theme-configuration- Replacetailwind.config.jswith@theme {}in CSSv4-custom-utilities-@utility,@custom-variant,@variant,@pluginv4-migration- Step-by-step v3 → v4 migration with renamed utilities,starting:,forced-colors:
6. Spacing & Typography (MEDIUM)
space-consistent- Consistent spacing scalespace-margins- Margin patternsspace-padding- Padding patternstypo-scale- Typography scaletypo-line-height- Line height
7. Animation (MEDIUM)
anim-transitions- Transition utilitiesanim-keyframes- Custom keyframesanim-reduced-motion- Respect motion preferences
8. Performance (LOW)
perf-purge- Content configurationperf-jit- JIT mode benefitsperf-arbitrary- Arbitrary values usage
Essential Patterns
Mobile-First Responsive Design
// ✅ Mobile-first: start with mobile, add larger breakpoints
<div className="
w-full // Mobile: full width
md:w-1/2 // Tablet: half width
lg:w-1/3 // Desktop: third width
">
<p className="
text-sm // Mobile: small text
md:text-base // Tablet: base text
lg:text-lg // Desktop: large text
">
Content
</p>
</div>
// ❌ Don't think desktop-first
<div className="w-1/3 md:w-1/2 sm:w-full"> // Confusing
Dark Mode Implementation
v3 — tailwind.config.js:
module.exports = { darkMode: 'class' }
v4 — CSS only, no config file:
@import "tailwindcss";
/* dark mode is class-based by default in v4 — no config needed */
Component — identical in both versions:
<div className="bg-white dark:bg-gray-900 text-gray-900 dark:text-white">
<h2 className="text-gray-900 dark:text-white">Title</h2>
<p className="text-gray-600 dark:text-gray-400">Description</p>
</div>
function toggleDarkMode() {
document.documentElement.classList.toggle('dark')
}
Conditional Classes with clsx/cn
import { clsx, type ClassValue } from 'clsx'
import { twMerge } from 'tailwind-merge'
// cn utility - merges Tailwind classes intelligently
export function cn(...inputs: ClassValue[]) {
return twMerge(clsx(inputs))
}
// Usage
interface ButtonProps {
variant?: 'primary' | 'secondary' | 'danger'
size?: 'sm' | 'md' | 'lg'
className?: string
children: React.ReactNode
}
function Button({ variant = 'primary', size = 'md', className, children }: ButtonProps) {
return (
<button
className={cn(
// Base styles
'inline-flex items-center justify-center rounded-md font-medium transition-colors',
'focus:outline-none focus:ring-2 focus:ring-offset-2',
// Variants
{
'bg-blue-600 text-white hover:bg-blue-700 focus:ring-blue-500':
variant === 'primary',
'bg-gray-100 text-gray-900 hover:bg-gray-200 focus:ring-gray-500':
variant === 'secondary',
'bg-red-600 text-white hover:bg-red-700 focus:ring-red-500':
variant === 'danger',
},
// Sizes
{
'px-3 py-1.5 text-sm': size === 'sm',
'px-4 py-2 text-base': size === 'md',
'px-6 py-3 text-lg': size === 'lg',
},
// Allow override
className
)}
>
{children}
</button>
)
}
Theme Configuration — v3 vs v4
v3 — tailwind.config.js:
/** @type {import('tailwindcss').Config} */
module.exports = {
content: ['./resources/**/*.{blade.php,js,ts,jsx,tsx}'],
darkMode: 'class',
theme: {
extend: {
colors: { primary: { 500: '#0ea5e9', 600: '#0284c7' } },
fontFamily: { sans: ['Inter', 'sans-serif'] },
spacing: { '18': '4.5rem' },
},
},
plugins: [require('@tailwindcss/forms')],
}
v4 — app.css only, no JS config:
@import "tailwindcss";
@theme {
--color-primary-500: #0ea5e9;
--color-primary-600: #0284c7;
--font-sans: Inter, sans-serif;
--spacing-18: 4.5rem;
--breakpoint-3xl: 1920px;
}
See
v4-theme-configurationandv4-migrationrules for full details.
Responsive Grid Layout
// Product grid - responsive columns
<div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4 gap-6">
{products.map(product => (
<ProductCard key={product.id} product={product} />
))}
</div>
// Dashboard layout - sidebar + main
<div className="flex flex-col lg:flex-row min-h-screen">
<aside className="
w-full lg:w-64
bg-gray-900
lg:min-h-screen
">
<nav>...</nav>
</aside>
<main className="flex-1 p-4 lg:p-8">
<div className="max-w-7xl mx-auto">
{children}
</div>
</main>
</div>
Form Styling
<form className="space-y-6">
<div>
<label htmlFor="email" className="block text-sm font-medium text-gray-700 dark:text-gray-300">
Email
</label>
<input
type="email"
id="email"
className="
mt-1 block w-full rounded-md
border-gray-300 dark:border-gray-600
bg-white dark:bg-gray-800
text-gray-900 dark:text-white
shadow-sm
focus:border-blue-500 focus:ring-blue-500
disabled:bg-gray-100 disabled:cursor-not-allowed
"
/>
</div>
<button
type="submit"
className="
w-full flex justify-center
py-2 px-4
border border-transparent rounded-md
shadow-sm text-sm font-medium
text-white bg-blue-600
hover:bg-blue-700
focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-blue-500
disabled:opacity-50 disabled:cursor-not-allowed
"
>
Submit
</button>
</form>
Animations with Reduced Motion
// Respect user's motion preferences
<div className="
transition-transform duration-300
hover:scale-105
motion-reduce:transition-none
motion-reduce:hover:transform-none
">
Card content
</div>
// Custom animation
<div className="animate-fade-in motion-reduce:animate-none">
Content
</div>
// tailwind.config.js
module.exports = {
theme: {
extend: {
keyframes: {
'fade-in': {
'0%': { opacity: '0' },
'100%': { opacity: '1' },
},
},
animation: {
'fade-in': 'fade-in 0.3s ease-out',
},
},
},
}
How to Use
Always run Step 1 (version detection) first, then read the relevant rule files:
v3 projects:
rules/config-extend-theme.md
rules/dark-setup.md
rules/comp-clsx-cn.md
rules/resp-mobile-first.md
v4 projects:
rules/v4-installation.md
rules/v4-theme-configuration.md
rules/v4-custom-utilities.md
Migrating v3 → v4:
rules/v4-migration.md
References
- Tailwind CSS Documentation - Official documentation
- Responsive Design Guide - Mobile-first patterns
- Dark Mode Guide - Theme implementation
- Configuration Guide - Customization
- Tailwind UI - Official component library
- Headless UI - Accessible components
- Heroicons - Icon library
Ecosystem Tools
- Tailwind CSS IntelliSense - VS Code autocomplete and linting
- Prettier Plugin - Automatic class sorting
- tailwind-merge - Conflict-free class merging
- clsx - Conditional class utility
- CVA - Component variant system
License
MIT License - See repository for full license text.
This skill is part of the Agent Skills collection, providing AI-powered development assistance with industry best practices.
04 同仓库更多 Skills
wordpress-pro
Develops custom WordPress themes and plugins, creates and registers Gutenberg blocks and block patterns, configures WooCommerce stores, implements WordPress REST API endpoints, applies security hardening (nonces, sanitization, escaping, capability checks), and optimizes performance through caching and query tuning. Use when building WordPress themes, writing plugins, customizing Gutenberg blocks, extending WooCommerce, working with ACF, using the WordPress REST API, applying hooks and filters, or improving WordPress performance and security.
websocket-engineer
Use when building real-time communication systems with WebSockets or Socket.IO. Invoke for bidirectional messaging, horizontal scaling with Redis, presence tracking, room management.
webapp-testing
Toolkit for interacting with and testing local web applications using Playwright. Supports verifying frontend functionality, debugging UI behavior, capturing browser screenshots, and viewing browser logs.
web-design-guidelines
UI/UX best practices and accessibility audit. Use when reviewing UI code, checking accessibility, running accessibility audits, auditing forms, or ensuring web interface best practices. Triggers on "audit accessibility", "check WCAG", "review UI", "check accessibility", "audit design", "review UX", or "check best practices".
web-artifacts-builder
Suite of tools for creating elaborate, multi-component claude.ai HTML artifacts using modern frontend web technologies (React, Tailwind CSS, shadcn/ui). Use for complex artifacts requiring state management, routing, or shadcn/ui components - not for simple single-file HTML/JSX artifacts.
vue-expert
Builds Vue 3 components with Composition API patterns, configures Nuxt 3 SSR/SSG projects, sets up Pinia stores, scaffolds Quasar/Capacitor mobile apps, implements PWA features, and optimises Vite builds. Use when creating Vue 3 applications with Composition API, writing reusable composables, managing state with Pinia, building hybrid mobile apps with Quasar or Capacitor, configuring service workers, or tuning Vite configuration and TypeScript integration.