tailwindcss-design

TailwindCSS 设计模式

web-design-mastery 技能的 TailwindCSS 实现指南。将 Refactoring UI 原则转化为 Tailwind 工具类。

前置条件： 此技能提供 Tailwind 专用语法。有关设计理论和决策，请参考 web-design-mastery 技能。

---

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

使用通用颜色前，务必先检查 tailwind.config.js 中的自定义颜色。

如果项目定义了 primary、secondary、brand 或类似的自定义颜色，请使用它们：

// tailwind.config.js
colors: {
  primary: { 50: '...', 500: '...', 900: '...' },
  secondary: { ... },
  brand: { ... }
}

优先级顺序：

1. 项目定义的颜色（primary、secondary、brand、accent）
2. Tailwind 通用颜色（仅在没有项目颜色时使用 zinc、gray、slate 作为后备）

项目颜色用法示例：

<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 = 主要 CTA、激活状态、链接、焦点环
• Secondary = 备选操作、辅助元素
• Brand/Accent = 高亮、装饰元素
• Neutral（zinc/gray）= 仅用于结构、文本、边框

---

间距类（4px 网格）

令牌	尺寸	类	使用场景
1	4px	gap-1、p-1、m-1	微小间距
2	8px	gap-2、p-2、m-2	紧凑间距、组件内部
3	12px	gap-3、p-3、m-3	相关元素
4	16px	gap-4、p-4、m-4	标准内边距
6	24px	gap-6、p-6、m-6	区块之间
8	32px	gap-8、p-8、m-8	较大的间隔
12	48px	gap-12、p-12	大间距
16	64px	gap-16、py-16	Hero 区域间距

规则： 默认使用对称内边距。使用 p-4，而不是 pt-6 pb-2 pl-4 pr-8。

---

排版类

尺寸	类	使用场景
12px	text-xs	标签、元信息、小字
14px	text-sm	正文、默认字号
16px	text-base	强调
18px	text-lg	小标题
20px	text-xl	卡片标题
24px	text-2xl	页面标题
30px	text-3xl	Hero 副标题
36px+	text-4xl、text-5xl	Hero 标题

字重类：

角色	类
正文	font-normal
标签	font-medium
标题	font-semibold

字距（字母间距）：

<h1 class="text-3xl font-semibold tracking-tight">


<span class="text-xs font-medium uppercase tracking-wide">

---

颜色层级

文本颜色（4 级系统）

<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>


<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>

状态颜色

<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>

品牌色（优先级）

先检查 tailwind.config.js。如果定义了 primary/secondary，请使用它们：

<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">

---

阴影与层次策略

每个项目选择一种：

策略 A：扁平（边框）

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

策略 B：轻微浮起

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

策略 C：分层（高端）

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

策略 D：表面变化

<div class="bg-zinc-50"> 
  <div class="bg-white"> 

阴影级别：

级别	类	使用场景
1	shadow-sm	卡片、按钮
2	shadow	下拉菜单
3	shadow-md	弹出框
4	shadow-lg	模态框
5	shadow-xl	全屏覆盖层

---

组件示例

卡片

<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">

按钮

<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">

输入框

<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" />

导航项

<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">

---

动画类

时长	类	使用场景
150ms	duration-150	悬停、切换
200ms	duration-200	标准过渡
300ms	duration-300	页面过渡

<div class="transition-all duration-200 ease-out">
<div class="transition-colors duration-150">

交错动画：

<div class="animate-fade-in [animation-delay:0ms]">
<div class="animate-fade-in [animation-delay:50ms]">
<div class="animate-fade-in [animation-delay:100ms]">

---

深色模式模式

<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">

深色模式调整：

• 优先使用边框而非阴影（阴影不太明显）
• 略微降低状态颜色的饱和度
• 降低辅助元素的对比度

---

反模式

<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">       


<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">

---

参考文件

主题	文件
组件层次模式	depth-strategies.md
完整组件库	components.md
响应式模式	responsive.md