tailwind-best-practices by asyrafhussin/agent-skills
npx skills add https://github.com/asyrafhussin/agent-skills --skill tailwind-best-practices使用 Tailwind CSS v3.4+ 和 v4 构建一致、可维护界面的综合模式。包含 29 条规则,涵盖响应式设计、深色模式、组件模式、配置和 v4 迁移。
在给出任何建议之前,务必检查版本。 v3 和 v4 有根本性的不同。
检查 package.json 中的已安装版本:
{ "tailwindcss": "^3.x" } // → 应用 v3 规则
{ "tailwindcss": "^4.x" } // → 应用 v4 规则
同时检查以下信号:
| 信号 | 版本 |
|---|---|
存在 tailwind.config.js |
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
| v3 |
CSS 中有 @import "tailwindcss" | v4 |
依赖项中有 @tailwindcss/vite | v4 |
依赖项中有 @tailwindcss/postcss | v4 |
CSS 中有 @theme {} 块 | v4 |
如果是 v3:应用 resp-、dark-、comp-、config- 规则。注意 v4 已可用。 如果是 v4:应用 v4- 规则。tailwind.config.js 模式不适用——请改用 @theme {}。 如果正在从 v3 迁移到 v4:直接遵循 v4-migration 规则。
在以下情况下参考这些指南:
| 优先级 | 类别 | 影响 | 前缀 | 版本 |
|---|---|---|---|---|
| 1 | 响应式设计 | 关键 | resp- | v3 / v4 |
| 2 | 深色模式 | 关键 | dark- | v3 / v4 |
| 3 | 组件模式 | 高 | comp- | v3 / v4 |
| 4 | 自定义配置 | 高 | config- | v3 |
| 5 | V4 与迁移 | 高 | v4- | 仅 v4 |
| 6 | 间距与排版 | 中 | space- | v3 / v4 |
| 7 | 动画 | 中 | anim- | v3 / v4 |
| 8 | 性能 | 低 | perf- | v3 / v4 |
resp-mobile-first - 移动优先方法resp-breakpoints - 正确使用断点resp-container - 容器模式resp-grid-flex - Grid 与 Flexbox 决策resp-hidden-shown - 条件性显示dark-setup - 配置深色模式dark-classes - 应用深色模式类dark-toggle - 实现深色模式切换dark-system-preference - 尊重系统偏好dark-colors - 为两种模式设计comp-clsx-cn - 条件类实用工具comp-variants - 组件变体模式comp-slots - 基于插槽的组件comp-composition - 组合实用工具config-extend - 扩展与覆盖主题config-colors - 自定义调色板config-fonts - 自定义字体config-screens - 自定义断点config-plugins - 使用插件v4-installation - 使用 Vite 或 PostCSS 安装 v4,@source,@referencev4-theme-configuration - 在 CSS 中用 @theme {} 替换 tailwind.config.jsv4-custom-utilities - @utility,@custom-variant,@variant,@pluginv4-migration - 分步 v3 → v4 迁移,包含重命名的实用工具,starting:,forced-colors:space-consistent - 一致的间距比例space-margins - 边距模式space-padding - 内边距模式typo-scale - 排版比例typo-line-height - 行高anim-transitions - 过渡实用工具anim-keyframes - 自定义关键帧anim-reduced-motion - 尊重运动偏好perf-purge - 内容配置perf-jit - JIT 模式优势perf-arbitrary - 任意值用法// ✅ 移动优先:从移动端开始,添加更大的断点
<div className="
w-full // 移动端:全宽
md:w-1/2 // 平板:半宽
lg:w-1/3 // 桌面:三分之一宽
">
<p className="
text-sm // 移动端:小文本
md:text-base // 平板:基础文本
lg:text-lg // 桌面:大文本
">
内容
</p>
</div>
// ❌ 不要以桌面优先思考
<div className="w-1/3 md:w-1/2 sm:w-full"> // 混乱
v3 —tailwind.config.js:
module.exports = { darkMode: 'class' }
v4 — 仅 CSS,无配置文件:
@import "tailwindcss";
/* v4 中深色模式默认基于类——无需配置 */
组件 — 两个版本相同:
<div className="bg-white dark:bg-gray-900 text-gray-900 dark:text-white">
<h2 className="text-gray-900 dark:text-white">标题</h2>
<p className="text-gray-600 dark:text-gray-400">描述</p>
</div>
function toggleDarkMode() {
document.documentElement.classList.toggle('dark')
}
import { clsx, type ClassValue } from 'clsx'
import { twMerge } from 'tailwind-merge'
// cn 实用工具 - 智能合并 Tailwind 类
export function cn(...inputs: ClassValue[]) {
return twMerge(clsx(inputs))
}
// 用法
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(
// 基础样式
'inline-flex items-center justify-center rounded-md font-medium transition-colors',
'focus:outline-none focus:ring-2 focus:ring-offset-2',
// 变体
{
'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',
},
// 尺寸
{
'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',
},
// 允许覆盖
className
)}
>
{children}
</button>
)
}
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,无 JS 配置:
@import "tailwindcss";
@theme {
--color-primary-500: #0ea5e9;
--color-primary-600: #0284c7;
--font-sans: Inter, sans-serif;
--spacing-18: 4.5rem;
--breakpoint-3xl: 1920px;
}
查看
v4-theme-configuration和v4-migration规则获取完整详情。
// 产品网格 - 响应式列
<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>
// 仪表板布局 - 侧边栏 + 主区域
<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 className="space-y-6">
<div>
<label htmlFor="email" className="block text-sm font-medium text-gray-700 dark:text-gray-300">
邮箱
</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
"
>
提交
</button>
</form>
// 尊重用户的运动偏好
<div className="
transition-transform duration-300
hover:scale-105
motion-reduce:transition-none
motion-reduce:hover:transform-none
">
卡片内容
</div>
// 自定义动画
<div className="animate-fade-in motion-reduce:animate-none">
内容
</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',
},
},
},
}
始终先运行步骤 1(版本检测),然后阅读相关的规则文件:
v3 项目:
rules/config-extend-theme.md
rules/dark-setup.md
rules/comp-clsx-cn.md
rules/resp-mobile-first.md
v4 项目:
rules/v4-installation.md
rules/v4-theme-configuration.md
rules/v4-custom-utilities.md
从 v3 迁移到 v4:
rules/v4-migration.md
MIT 许可证 - 查看仓库获取完整的许可证文本。
此技能是 Agent Skills 集合的一部分,提供基于 AI 的开发辅助和行业最佳实践。
每周安装数
74
仓库
GitHub 星标数
11
首次出现
2026年1月21日
安全审计
安装于
gemini-cli59
codex56
opencode55
github-copilot51
claude-code49
antigravity47
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.
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.
Reference these guidelines when:
| 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- |
resp-mobile-first - Mobile-first approachresp-breakpoints - Use breakpoints correctlyresp-container - Container patternsresp-grid-flex - Grid vs Flexbox decisionsresp-hidden-shown - Conditional displaydark-setup - Configure dark modedark-classes - Apply dark mode classesdark-toggle - Implement dark mode toggledark-system-preference - Respect system preferencedark-colors - Design for both modescomp-clsx-cn - Conditional classes utilitycomp-variants - Component variants patterncomp-slots - Slot-based componentscomp-composition - Composing utilitiesconfig-extend - Extend vs override themeconfig-colors - Custom color paletteconfig-fonts - Custom fontsconfig-screens - Custom breakpointsconfig-plugins - Using pluginsv4-installation - Install v4 with Vite or PostCSS, @source, @referencev4-theme-configuration - Replace tailwind.config.js with @theme {} in CSSv4-custom-utilities - @utility, @custom-variant, @variant, @pluginspace-consistent - Consistent spacing scalespace-margins - Margin patternsspace-padding - Padding patternstypo-scale - Typography scaletypo-line-height - Line heightanim-transitions - Transition utilitiesanim-keyframes - Custom keyframesanim-reduced-motion - Respect motion preferencesperf-purge - Content configurationperf-jit - JIT mode benefitsperf-arbitrary - Arbitrary values usage// ✅ 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
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')
}
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>
)
}
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.
// 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 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>
// 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',
},
},
},
}
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
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.
Weekly Installs
74
Repository
GitHub Stars
11
First Seen
Jan 21, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykPass
Installed on
gemini-cli59
codex56
opencode55
github-copilot51
claude-code49
antigravity47
Android 整洁架构指南:模块化设计、依赖注入与数据层实现
1,400 周安装
MCP-CLI:命令行访问MCP服务器的工具,支持GitHub、文件系统、数据库交互
8,300 周安装
GitHub Copilot PRD生成工具 - AI产品经理助手,自动创建详细产品需求文档
8,300 周安装
GitHub Copilot代码审查与重构工具 - 资深工程师AI助手,自动优化代码质量与规范
8,400 周安装
Nano Banana Pro OpenRouter:基于OpenRouter的AI图像生成与编辑工具,支持Gemini-3-Pro模型
8,400 周安装
.NET/C# 设计模式代码审查工具 - 自动化分析命令、工厂、仓储等模式实现
8,500 周安装
智能体评估模式详解:agentic-eval 迭代优化与自我提升框架
8,400 周安装
| 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 |
v4-migration - Step-by-step v3 → v4 migration with renamed utilities, starting:, forced-colors: