Back to Details

tailwindcss-design

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

TailwindCSS Design Patterns

TailwindCSS 设计模式

TailwindCSS implementation companion for web-design-mastery skill. Translates Refactoring UI principles into Tailwind utility classes.
Prerequisite: This skill provides Tailwind-specific syntax. For design theory and decision-making, reference 
web-design-mastery
skill.
这是web-design-mastery技能的TailwindCSS实现配套指南。将Refactoring UI原则转化为Tailwind工具类的使用方案。
前提条件： 本技能提供Tailwind专属语法。若需设计理论与决策相关内容，请参考
web-design-mastery
技能。

⚠️ CRITICAL: Project Brand Colors First

⚠️ 重要提示：优先使用项目品牌色

ALWAYS check 
tailwind.config.js
for custom colors before using generic colors.
If the project defines 
primary
, 
secondary
, 
brand
, or similar custom colors, USE THEM:
js
// tailwind.config.js
colors: {
  primary: { 50: '...', 500: '...', 900: '...' },
  secondary: { ... },
  brand: { ... }
}
Priority order:
  1. Project-defined colors (
    primary
    , 
    secondary
    , 
    brand
    , 
    accent
    )
  2. Generic Tailwind colors (
    zinc
    , 
    gray
    , 
    slate
    ) as fallback only
Usage examples with project colors:
html
<!-- ✅ CORRECT: Use project colors -->
<button class="bg-primary-600 hover:bg-primary-700 text-white">
<a class="text-primary-600 hover:text-primary-700">
<div class="border-primary-500 bg-primary-50">
<input class="focus:border-primary-500 focus:ring-primary-500">

<!-- Active/selected states -->
<nav class="bg-primary-50 text-primary-700">

<!-- ❌ AVOID when project colors exist -->
<button class="bg-blue-600">  <!-- Generic, ignores brand -->
<button class="bg-zinc-900">  <!-- Only if no primary defined -->
Rules:
  • Primary = main CTAs, active states, links, focus rings
  • Secondary = alternative actions, supporting elements
  • Brand/Accent = highlights, decorative elements
  • Neutral (zinc/gray) = structure, text, borders only
在使用通用颜色前，请务必检查
tailwind.config.js
中的自定义颜色配置。
如果项目中定义了
primary
、
secondary
、
brand
或类似的自定义颜色，请优先使用这些颜色：
js
// tailwind.config.js
colors: {
  primary: { 50: '...', 500: '...', 900: '...' },
  secondary: { ... },
  brand: { ... }
}
优先级顺序：
  1. 项目自定义颜色（
    primary
    、
    secondary
    、
    brand
    、
    accent
    ）
  2. 通用Tailwind颜色（
    zinc
    、
    gray
    、
    slate
    ）仅作为备选
项目颜色使用示例：
html
<!-- ✅ 正确用法：使用项目颜色 -->
<button class="bg-primary-600 hover:bg-primary-700 text-white">
<a class="text-primary-600 hover:text-primary-700">
<div class="border-primary-500 bg-primary-50">
<input class="focus:border-primary-500 focus:ring-primary-500">

<!-- 激活/选中状态 -->
<nav class="bg-primary-50 text-primary-700">

<!-- ❌ 当项目存在自定义颜色时避免使用 -->
<button class="bg-blue-600">  <!-- 通用颜色，未遵循品牌规范 -->
<button class="bg-zinc-900">  <!-- 仅在未定义primary时使用 -->
规则：
  • Primary = 主要CTA按钮、激活状态、链接、焦点环
  • Secondary = 次要操作、辅助元素
  • Brand/Accent = 高亮元素、装饰性元素
  • Neutral（zinc/gray）= 仅用于结构、文本、边框

Spacing Classes (4px Grid)

间距类（4px网格系统）

TokenSizeClassesUse Case
14px
gap-1
, 
p-1
, 
m-1
Micro gaps
28px
gap-2
, 
p-2
, 
m-2
Tight, within components
312px
gap-3
, 
p-3
, 
m-3
Related elements
416px
gap-4
, 
p-4
, 
m-4
Standard padding
624px
gap-6
, 
p-6
, 
m-6
Between sections
832px
gap-8
, 
p-8
, 
m-8
Major separation
1248px
gap-12
, 
p-12
Large gaps
1664px
gap-16
, 
py-16
Hero spacing
Rule: Symmetric padding by default. 
p-4
not 
pt-6 pb-2 pl-4 pr-8
.
标识尺寸类名使用场景
14px
gap-1
, 
p-1
, 
m-1
微小间距
28px
gap-2
, 
p-2
, 
m-2
紧凑间距，组件内部使用
312px
gap-3
, 
p-3
, 
m-3
关联元素之间
416px
gap-4
, 
p-4
, 
m-4
标准内边距
624px
gap-6
, 
p-6
, 
m-6
区块之间
832px
gap-8
, 
p-8
, 
m-8
主要分隔区域
1248px
gap-12
, 
p-12
大间距
1664px
gap-16
, 
py-16
英雄区间距
规则： 默认使用对称内边距。优先使用
p-4
而非
pt-6 pb-2 pl-4 pr-8
。

Typography Classes

排版类

SizeClassUse Case
12px
text-xs
Labels, meta, fine print
14px
text-sm
Body text, default
16px
text-base
Emphasis
18px
text-lg
Subheadings
20px
text-xl
Card titles
24px
text-2xl
Page titles
30px
text-3xl
Hero subheading
36px+
text-4xl
, 
text-5xl
Hero heading
Weight Classes:
RoleClass
Body
font-normal
Labels
font-medium
Headings
font-semibold
Tracking (Letter-spacing):
html
<!-- Headlines: tighter -->
<h1 class="text-3xl font-semibold tracking-tight">

<!-- All-caps: wider -->
<span class="text-xs font-medium uppercase tracking-wide">
尺寸类名使用场景
12px
text-xs
标签、元信息、小字说明
14px
text-sm
正文文本、默认字体
16px
text-base
强调文本
18px
text-lg
子标题
20px
text-xl
卡片标题
24px
text-2xl
页面标题
30px
text-3xl
英雄区副标题
36px+
text-4xl
, 
text-5xl
英雄区主标题
字重类：
用途类名
正文
font-normal
标签
font-medium
标题
font-semibold
字间距：
html
<!-- 标题：字间距更紧凑 -->
<h1 class="text-3xl font-semibold tracking-tight">

<!-- 全大写文本：字间距更宽松 -->
<span class="text-xs font-medium uppercase tracking-wide">

Color Hierarchy

颜色层级

Text Colors (4-Level System)

文本颜色（4级系统）

html
<!-- Light mode -->
<span class="text-zinc-900">Primary</span>
<span class="text-zinc-600">Secondary</span>
<span class="text-zinc-400">Muted</span>
<span class="text-zinc-300">Faint</span>

<!-- Dark mode -->
<span class="dark:text-zinc-100">Primary</span>
<span class="dark:text-zinc-400">Secondary</span>
<span class="dark:text-zinc-500">Muted</span>
<span class="dark:text-zinc-600">Faint</span>
html
<!-- 浅色模式 -->
<span class="text-zinc-900">主文本</span>
<span class="text-zinc-600">次要文本</span>
<span class="text-zinc-400">弱化文本</span>
<span class="text-zinc-300">极淡文本</span>

<!-- 深色模式 -->
<span class="dark:text-zinc-100">主文本</span>
<span class="dark:text-zinc-400">次要文本</span>
<span class="dark:text-zinc-500">弱化文本</span>
<span class="dark:text-zinc-600">极淡文本</span>

Status Colors

状态颜色

html
<span class="text-emerald-600 dark:text-emerald-400">Success</span>
<span class="text-amber-600 dark:text-amber-400">Warning</span>
<span class="text-red-600 dark:text-red-400">Error</span>
<span class="text-blue-600 dark:text-blue-400">Info</span>
html
<span class="text-emerald-600 dark:text-emerald-400">成功</span>
<span class="text-amber-600 dark:text-amber-400">警告</span>
<span class="text-red-600 dark:text-red-400">错误</span>
<span class="text-blue-600 dark:text-blue-400">信息</span>

Brand Colors (Priority)

品牌颜色（优先使用）

Check 
tailwind.config.js
first. If 
primary
/
secondary
defined, use them:
html
<button class="bg-primary-600 hover:bg-primary-700">
<a class="text-primary-600 hover:text-primary-700">
<div class="border-primary-500 bg-primary-50">
请先检查
tailwind.config.js
。如果已定义
primary
/
secondary
，请使用这些颜色：
html
<button class="bg-primary-600 hover:bg-primary-700">
<a class="text-primary-600 hover:text-primary-700">
<div class="border-primary-500 bg-primary-50">

Shadow & Depth Strategies

阴影与层级策略

Pick ONE per project:
每个项目选择一种策略：

Strategy A: Flat (Borders)

策略A：扁平化（使用边框）

html
<div class="border border-zinc-200 dark:border-zinc-800">
html
<div class="border border-zinc-200 dark:border-zinc-800">

Strategy B: Subtle Lift

策略B：轻微悬浮

html
<div class="shadow-sm border border-zinc-200/50">
html
<div class="shadow-sm border border-zinc-200/50">

Strategy C: Layered (Premium)

策略C：分层式（高端风格）

html
<div class="shadow-sm ring-1 ring-black/5">
html
<div class="shadow-sm ring-1 ring-black/5">

Strategy D: Surface Shift

策略D：背景色区分

html
<div class="bg-zinc-50"> <!-- page -->
  <div class="bg-white"> <!-- elevated -->
Shadow Scale:
LevelClassUse Case
1
shadow-sm
Cards, buttons
2
shadow
Dropdowns
3
shadow-md
Popovers
4
shadow-lg
Modals
5
shadow-xl
Full-screen overlays
html
<div class="bg-zinc-50"> <!-- 页面背景 -->
  <div class="bg-white"> <!-- 悬浮元素 -->
阴影层级：
层级类名使用场景
1
shadow-sm
卡片、按钮
2
shadow
下拉菜单
3
shadow-md
弹出框
4
shadow-lg
模态框
5
shadow-xl
全屏遮罩

Component Recipes

组件编写方案

Cards

卡片

html
<!-- Flat -->
<div class="rounded-lg border border-zinc-200 bg-white p-4 dark:border-zinc-800 dark:bg-zinc-900">

<!-- Elevated -->
<div class="rounded-lg bg-white p-4 shadow-sm ring-1 ring-black/5 dark:bg-zinc-900">
html
<!-- 扁平化 -->
<div class="rounded-lg border border-zinc-200 bg-white p-4 dark:border-zinc-800 dark:bg-zinc-900">

<!-- 悬浮式 -->
<div class="rounded-lg bg-white p-4 shadow-sm ring-1 ring-black/5 dark:bg-zinc-900">

Buttons

按钮

html
<!-- Primary -->
<button class="rounded-md bg-zinc-900 px-3 py-1.5 text-sm font-medium text-white hover:bg-zinc-800 dark:bg-zinc-100 dark:text-zinc-900 dark:hover:bg-zinc-200">

<!-- Secondary -->
<button class="rounded-md border border-zinc-300 bg-white px-3 py-1.5 text-sm font-medium text-zinc-700 hover:bg-zinc-50 dark:border-zinc-700 dark:bg-zinc-800 dark:text-zinc-300">

<!-- Ghost -->
<button class="rounded-md px-3 py-1.5 text-sm font-medium text-zinc-600 hover:bg-zinc-100 hover:text-zinc-900 dark:text-zinc-400 dark:hover:bg-zinc-800 dark:hover:text-zinc-100">
html
<!-- 主按钮 -->
<button class="rounded-md bg-zinc-900 px-3 py-1.5 text-sm font-medium text-white hover:bg-zinc-800 dark:bg-zinc-100 dark:text-zinc-900 dark:hover:bg-zinc-200">

<!-- 次按钮 -->
<button class="rounded-md border border-zinc-300 bg-white px-3 py-1.5 text-sm font-medium text-zinc-700 hover:bg-zinc-50 dark:border-zinc-700 dark:bg-zinc-800 dark:text-zinc-300">

<!-- 幽灵按钮 -->
<button class="rounded-md px-3 py-1.5 text-sm font-medium text-zinc-600 hover:bg-zinc-100 hover:text-zinc-900 dark:text-zinc-400 dark:hover:bg-zinc-800 dark:hover:text-zinc-100">

Inputs

输入框

html
<input class="w-full rounded-md border border-zinc-300 bg-white px-3 py-2 text-sm text-zinc-900 placeholder:text-zinc-400 focus:border-zinc-500 focus:outline-none focus:ring-1 focus:ring-zinc-500 dark:border-zinc-700 dark:bg-zinc-900 dark:text-zinc-100" />
html
<input class="w-full rounded-md border border-zinc-300 bg-white px-3 py-2 text-sm text-zinc-900 placeholder:text-zinc-400 focus:border-zinc-500 focus:outline-none focus:ring-1 focus:ring-zinc-500 dark:border-zinc-700 dark:bg-zinc-900 dark:text-zinc-100" />

Navigation Item

导航项

html
<!-- Default -->
<a class="flex items-center gap-2 rounded-md px-3 py-2 text-sm font-medium text-zinc-600 hover:bg-zinc-100 hover:text-zinc-900 dark:text-zinc-400 dark:hover:bg-zinc-800 dark:hover:text-zinc-100">

<!-- Active -->
<a class="flex items-center gap-2 rounded-md bg-zinc-100 px-3 py-2 text-sm font-medium text-zinc-900 dark:bg-zinc-800 dark:text-zinc-100">
html
<!-- 默认状态 -->
<a class="flex items-center gap-2 rounded-md px-3 py-2 text-sm font-medium text-zinc-600 hover:bg-zinc-100 hover:text-zinc-900 dark:text-zinc-400 dark:hover:bg-zinc-800 dark:hover:text-zinc-100">

<!-- 激活状态 -->
<a class="flex items-center gap-2 rounded-md bg-zinc-100 px-3 py-2 text-sm font-medium text-zinc-900 dark:bg-zinc-800 dark:text-zinc-100">

Animation Classes

动画类

DurationClassUse Case
150ms
duration-150
Hovers, toggles
200ms
duration-200
Standard transitions
300ms
duration-300
Page transitions
html
<div class="transition-all duration-200 ease-out">
<div class="transition-colors duration-150">
Staggered Animation:
html
<div class="animate-fade-in [animation-delay:0ms]">
<div class="animate-fade-in [animation-delay:50ms]">
<div class="animate-fade-in [animation-delay:100ms]">
时长类名使用场景
150ms
duration-150
悬停效果、切换效果
200ms
duration-200
标准过渡动画
300ms
duration-300
页面过渡
html
<div class="transition-all duration-200 ease-out">
<div class="transition-colors duration-150">
** stagger动画（依次触发）：**
html
<div class="animate-fade-in [animation-delay:0ms]">
<div class="animate-fade-in [animation-delay:50ms]">
<div class="animate-fade-in [animation-delay:100ms]">

Dark Mode Pattern

暗黑模式实现模式

html
<div class="bg-white dark:bg-zinc-950">
  <h1 class="text-zinc-900 dark:text-zinc-100">
  <p class="text-zinc-600 dark:text-zinc-400">
  <div class="border-zinc-200 dark:border-zinc-800">
Dark mode adjustments:
  • Borders > shadows (shadows less visible)
  • Desaturate status colors slightly
  • Reduce contrast on secondary elements
html
<div class="bg-white dark:bg-zinc-950">
  <h1 class="text-zinc-900 dark:text-zinc-100">
  <p class="text-zinc-600 dark:text-zinc-400">
  <div class="border-zinc-200 dark:border-zinc-800">
暗黑模式调整规则：
  • 优先使用边框而非阴影（阴影在深色模式下可见度低）
  • 适当降低状态颜色的饱和度
  • 降低次要元素的对比度

Anti-Patterns

反模式（错误用法）

html
<!-- ❌ NEVER -->
<div class="shadow-2xl">           <!-- Too dramatic -->
<button class="rounded-2xl px-3">  <!-- Radius too large for size -->
<div class="pt-8 pb-2 pl-6 pr-3">  <!-- Asymmetric without reason -->
<div class="border-4 border-purple-500"> <!-- Thick decorative -->
<div class="animate-bounce">       <!-- Bouncy in enterprise UI -->

<!-- ✅ INSTEAD -->
<div class="shadow-sm">
<button class="rounded-md px-3">
<div class="p-4">
<div class="border border-zinc-200">
<div class="transition-all duration-200">
html
<!-- ❌ 禁止使用 -->
<div class="shadow-2xl">           <!-- 效果过于夸张 -->
<button class="rounded-2xl px-3">  <!-- 圆角过大，与尺寸不匹配 -->
<div class="pt-8 pb-2 pl-6 pr-3">  <!-- 无理由使用不对称内边距 -->
<div class="border-4 border-purple-500"> <!-- 过厚的装饰性边框 -->
<div class="animate-bounce">       <!-- 企业级UI中避免弹跳动画 -->

<!-- ✅ 推荐用法 -->
<div class="shadow-sm">
<button class="rounded-md px-3">
<div class="p-4">
<div class="border border-zinc-200">
<div class="transition-all duration-200">

Reference Files

参考文档

TopicFile
Component depth patternsdepth-strategies.md
Complete component librarycomponents.md
Responsive patternsresponsive.md
主题文件
组件层级模式depth-strategies.md
完整组件库components.md
响应式设计模式responsive.md