refactoring-ui

Refactoring UI 设计系统

一种实用且带观点的UI设计方法。在生成前端代码、审查设计或提供视觉改进建议时应用这些原则。

核心原则

先以灰度设计，最后添加颜色。 这迫使你在依赖颜色作为拐杖之前，通过间距、对比度和排版来建立正确的层级。

基础： 优秀的UI不是靠天赋——而是靠系统。间距、排版、颜色和阴影的约束尺度能持续产生专业效果。从过多的空白开始，然后移除；在布局和层级工作完成之前，不要添加细节（图标、阴影、微交互）。

评分

目标：10/10。 通过统计快速诊断中满足的行数（8个是/否检查）来评分：score = round(satisfied / 8 × 10)。等级直接如下：10 = 全部8项通过（层级在模糊和灰度下可读，每个值都在尺度上）；9 = 恰好1项缺失（通常是弱层级或空白不足）；6-8 = 2-3项缺失；<=5 = 4项及以上缺失（任意间距、颜色承担了层级应有的工作，或对比度不足）。始终说明当前分数以及需要修复的具体诊断项以达到10/10。

Refactoring UI 框架

无需设计师即可构建专业界面的七项原则：

1. 视觉层级

核心概念： 并非所有内容都同等重要。通过三个杠杆创建层级：大小、粗细和颜色。

为什么有效： 当每个元素都争夺注意力时，没有元素能脱颖而出；有意识地弱化次要内容，通过对比使主要内容更突出。

关键见解：

• 组合杠杆，不要叠加——主文本 = 大号 或 粗体 或 深色，而不是三者全用；将“三者全用”留给最重要的单个元素
• 标签是次要的——表单标签、表格标题和元数据支持数据，而不是与之竞争；使它们更小、更轻或使用大写小写
• 语义颜色 ≠ 视觉权重——对于常规的破坏性操作，柔和的次要按钮通常比醒目的红色更好

产品应用：

上下文	层级技术	示例
表单字段	弱化标签，强调值	小号大写标签在上，大号值在下
仪表盘	关键指标大，上下文小	"$42,300" 大号，"vs 上月" 小号
表格	弱化表头，强调数据	表头大写小号灰色，数据正常

设计模式：

• 三层级：大小（大/基础/小）、粗细（粗/中/正常）、颜色（深/中/浅灰）
• 按钮层级：主要（填充）、次要（轮廓或柔和）、第三级（仅文本）

道德边界： 不要使用层级技巧隐藏重要信息，如价格、条款或取消选项。

设计超出静态布局的组件时，请参阅 references/advanced-patterns.md —— 交互/悬停/焦点状态、表单设计、空状态、边框半径系统、文本截断和响应式断点。

2. 间距与尺寸

核心概念： 使用约束的间距尺度，而不是任意值。间距定义关系——更近的元素读起来更相关。

为什么有效： 任意间距（padding: 13px）会导致不一致；固定尺度迫使你做出深思熟虑的决定和和谐的布局。宽松的间距感觉高级；密集的间距感觉压抑。

关键见解：

• 使用尺度：4, 8, 16, 24, 32, 48, 64px
• 从过多的空白开始，然后移除——你几乎永远不会移除足够多
• 组之间的间距必须大于组内的间距
• 约束宽度：文本45-75字符（max-w-prose），表单300-500px；全宽几乎永远不正确

产品应用：

上下文	间距策略	示例
图标+标签	紧密耦合（4px）	小间隙保持连接
卡片区域	区域分隔（24px）	标题、内容、页脚块
页面区域	主要区域（48-64px）	英雄、特性、推荐

CSS模式：

• p-1(4px) p-2(8px) p-4(16px) p-6(24px) p-8(32px) p-12(48px) p-16(64px)
• max-w-prose(65ch) max-w-md(28rem) max-w-lg(32rem) max-w-xl(36rem)
• 相关项使用 gap-2，区域分隔使用 gap-6

3. 排版

核心概念： 使用模块化字体尺度，根据上下文约束行高，最多使用两种字体族。

为什么有效： 模块化尺度（每一步增长约1.2倍）创造自然的视觉节奏；标题行高紧凑，正文行高宽松，在每个上下文中提高可读性。

关键见解：

• 尺度：12, 14, 16, 18, 20, 24, 30, 36px（约1.2模块化，手动调整）
• 标题：紧凑行高（1.0-1.25）；正文：宽松（1.5-1.75）；更宽的文本需要更大的行高
• 正文避免使用低于400的字重；使用粗体（600-700）强调，而不是所有内容
• 最多两种字体：一种用于标题，一种用于正文（或一种字体族通过字重变化）

产品应用：

上下文	排版规则	示例
英雄标题	36px，行高1.1，粗体	大型有影响力的陈述
正文	16px，行高1.75，正常	舒适的阅读
说明/标签	12-14px，行高1.5，中灰色	次要信息

CSS模式：

• text-xs(12px) text-sm(14px) text-base(16px) text-lg(18px) text-xl(20px)
• font-normal(400) font-medium(500) font-semibold(600) font-bold(700)
• leading-tight(1.25) leading-normal(1.5) leading-relaxed(1.75)

4. 颜色

核心概念： 构建系统化的调色板，每种颜色5-9个色阶，为灰色添加微妙饱和度，并先以灰度设计。

为什么有效： 随机颜色冲突；预定义的色阶系统确保一致性，HSL调整创建自然感觉的更亮和更暗变体。

关键见解：

• 每种颜色需要5-9个色阶，从近白到近黑（50-900）；最深的不是纯黑——使用 #111827，而不是 #000000
• 纯灰色显得死气沉沉——为其着色（冷色UI：蓝色如 #64748b；暖色UI：黄色/棕色如 #78716c）
• HSL：更亮 = 提高亮度，降低饱和度，色相趋向60°；更暗 = 相反，色相趋向0°/240°
• 对比度最小值：正文4.5:1，大文本3:1（18px+）；在白色上使用 #374151（gray-700），而不是更浅的灰色

产品应用：

上下文	颜色策略	示例
主色调	品牌色的9个色阶（50-900）	Blue-500按钮，Blue-100背景
语义颜色	成功/警告/错误带色阶范围	Green-500成功，Red-500错误
文本颜色	三个级别：深、中、浅	text-gray-900，text-gray-600，text-gray-400

CSS模式：

• text-gray-900(深) text-gray-600(中) text-gray-400(浅)
• 微妙背景使用 bg-blue-50，主要操作使用 bg-blue-500
• 微妙边框使用 border-gray-200，更强边框使用 border-gray-300

构建深色主题时，请参阅 references/theming-dark-mode.md —— 十六进制色阶尺度，为什么最深的颜色是 #111827 而不是黑色（光晕效应），以及通过亮度而非阴影传达层级。当涉及对比度、焦点环、键盘导航或屏幕阅读器支持时，请参阅 references/accessibility-depth.md —— 完整的WCAG 2.1 AA检查清单和修复方法。

5. 深度与阴影

核心概念： 使用阴影尺度传达层级——小阴影用于略微抬起的元素，大阴影用于浮动的元素。

为什么有效： 眼睛将阴影大小解读为页面之上的高度；一致的尺度使层级可读，用户能直观地知道哪些是可交互的、浮动的或背景的。

关键见解：

• 小阴影 = 略微抬起（按钮、卡片）；大阴影 = 浮动（模态框、下拉菜单）
• 好的阴影有两部分：一个紧凑的深色阴影用于清晰度，加上一个更大的柔和阴影用于氛围
• 无阴影的深度：较浅的上边框 + 较深的下边框，微妙的渐变，重叠元素
• 不要过度使用——如果所有东西都浮动，就没有深度；阴影颜色是透明的深色，从不使用不透明的灰色

产品应用：

上下文	阴影级别	示例
按钮	shadow-sm（微妙抬起）	略高于表面
下拉菜单	shadow-lg（浮动）	菜单明显高于内容
模态框	shadow-xl（最高）	覆盖层与页面分离

CSS模式：

• shadow-sm: 0 1px 2px rgba(0,0,0,0.05)
• shadow-md: 0 4px 6px rgba(0,0,0,0.1)
• shadow-lg: 0 10px 15px rgba(0,0,0,0.1)
• shadow-xl: 0 20px 25px rgba(0,0,0,0.15)

为交互元素添加动效时，请参阅 references/animation-microinteractions.md —— 持续时间、缓动曲线、加载状态和 prefers-reduced-motion 规则。

6. 图片与图标

核心概念： 将图片视为设计元素，而非事后想法。有意识地调整图标大小，并使用叠加层使文本在图片上保持可读。

为什么有效： 尺寸不当的图标看起来别扭，未加样式的图片破坏一致性；有意识的处理（叠加层、object-fit、圆角）使界面感觉精致。

关键见解：

• 根据上下文调整图标大小；使用具有一致描边宽度和样式的图标集
• 绝不拉伸或扭曲——使用 object-fit: cover 配合固定宽高比并有意识地裁剪
• 图片上的文本需要叠加层（半透明渐变）
• 空状态是一个机会——使用插图加上清晰的CTA，而不仅仅是文本

产品应用：

上下文	图片/图标技术	示例
英雄图片	半透明渐变叠加层	文本在任何照片上可读
头像	一致大小、圆角、回退首字母	40px圆形，object-fit cover
空状态	自定义插图 + CTA	友好的插图加上“开始使用”

CSS模式：

• 使用 object-fit: cover 配合固定 aspect-ratio 实现一致显示
• 图标尺寸：内联 w-4 h-4，导航 w-6 h-6，特性图标 w-8 h-8
• 叠加层：图片上的文本使用 bg-gradient-to-t from-black/60 to-transparent

7. 布局与构成

核心概念： 不要居中所有内容。使用对齐、重叠和强调变化来创建引人入胜的构成。

为什么有效： 一致的左边缘为眼睛提供了每行的固定返回点，因此扫描成本更低；居中的多行文本每行都会移动该边缘，减慢阅读速度。

关键见解：

• 默认左对齐；仅居中短标题、英雄区、单一操作CTA和空状态
• 卡片不需要包含所有内容——让图片延伸到边缘或重叠容器
• 在列表和提要中变化视觉处理——突出某些项目，最小化其他项目
• 使用对齐在不相关元素之间创建关系

产品应用：

上下文	布局策略	示例
英雄区域	居中文本，宽松间距	短标题 + 副文本 + 单一CTA
博客提要	变化的卡片大小以强调	第一篇文章大，其余在2列网格中
内容页面	约束宽度，左对齐	max-w-prose 容器，文本左对齐

CSS模式：

• 默认 text-left，仅英雄区和短标题使用 text-center
• 特性网格使用 grid grid-cols-3 gap-6；页面容器使用 max-w-4xl mx-auto
• 卡片上使用 overflow-hidden，配合延伸到边缘的 object-fit: cover 图片

布局图表、表格或仪表盘时，请参阅 references/data-visualization.md —— 图表类型选择、图表中的颜色使用、表格密度和仪表盘构成。

常见错误

错误	失败原因	修复方法
“看起来业余”	空白不足，宽度未约束	增加空白，约束内容宽度
“感觉扁平”	没有深度区分	微妙阴影，区域底部边框
“文本难以阅读”	行高不佳，太宽，对比度低	增加行高，约束宽度，提高对比度
“所有东西看起来都一样”	没有视觉层级	在主要和次要之间变化大小/粗细/颜色
“感觉杂乱”	所有地方间距相同	分组相关项，组之间更大间距
“颜色冲突”	随机选择，没有系统	降低饱和度，增加灰色，限制在调色板内
“按钮不突出”	与周围对比度低	增加对比度，添加阴影
任意值	像13、17、23这样的px值导致不一致	坚持使用间距和字体尺度

快速诊断

审计任何UI设计：

问题	如果否	操作
眯眼看时层级是否可读（模糊测试）？	元素在竞争	增加主要/次要对比度
在灰度下是否有效？	颜色是拐杖	加强大小/粗细/间距层级
是否有足够的空白？	可能没有——大多数设计过于密集	增加间距，尤其是组之间
标签是否相对于值被弱化？	标签与数据竞争	更小、更轻或大写小写标签
间距是否遵循一致的尺度？	任意间距 = 视觉噪音	仅使用4/8/16/24/32/48/64
文本宽度是否被约束？	长行使读者疲劳	应用 max-w-prose（~65ch）
颜色是否有足够的对比度？	可访问性失败	WCAG检查；在白色上使用gray-700+
阴影是否适合层级？	元素在错误级别浮动	将阴影尺度与元素用途匹配

延伸阅读

关于带有视觉前后对比示例的完整系统：

• 《重构UI》 by Adam Wathan & Steve Schoger（包含数百个视觉示例的完整书籍）
• 《设计心理学》 by Don Norman（基础设计思维和可用性）
• 《不要让我思考》 by Steve Krug（补充重构UI的网页可用性原则）
• Refactoring UI —— 官方站点，包含资源和示例

关于作者

Adam Wathan，Tailwind CSS的创建者，以及Steve Schoger，其设计语言的视觉设计师，撰写了《重构UI》以教授开发者系统化、可重复的设计技术。他们的方法用约束系统——间距、排版、颜色和阴影的固定尺度——取代了艺术天赋，从而产生专业效果。