tailwind-ui-refactor

Refactoring UI Tailwind CSS 最佳实践

这是一份全面的 UI 重构指南，基于 Adam Wathan 和 Steve Schoger 编写的 Refactoring UI，并使用 Tailwind CSS 工具类实现。指南包含 9 个类别中的 52 条规则，并按设计影响排序，以指导自动化重构和代码生成。使用 Tailwind CSS v4 语法（语法不同之处提供 v3 说明）。

重要：先思考，再设计样式。 在应用任何视觉规则之前，先了解 UI 的用途，确定哪些内容对用户重要，并移除不必要的元素。必须在进行任何样式更改之前考虑设计意图类别（优先级 1）。与其装饰包含多余标记的组件，不如使用元素更少的简洁组件。

何时应用

在以下情况参考这些指南：

• 重构现有的 Tailwind CSS 组件
• 使用 Tailwind 工具类编写新的 UI
• 检查代码中的视觉层级和间距问题
• 在没有设计师的情况下提升设计质量
• 修复无障碍对比度问题

按优先级划分的规则类别

优先级	类别	影响	前缀
1	设计意图	关键	intent-
2	视觉层级	关键	hier-
3	布局与间距	关键	space-
4	排版	高	type-
5	色彩系统	高	color-
6	深度与阴影	中	depth-
7	边框与分隔	中	sep-
8	图片与内容	低至中	img-
9	润色与细节	低	polish-

快速参考

1. 设计意图（关键）

• intent-audit-before-styling - 更改任何 CSS 之前，先审查每个元素传达的信息
• intent-remove-before-decorating - 先移除不必要的元素，再为剩余内容添加样式
• intent-reduce-cognitive-load - 减少每个屏幕上的选项——选项更少胜过选项更漂亮
• intent-progressive-disclosure - 将次要信息隐藏在交互之后
• intent-content-drives-layout - 让真实内容决定布局，而不是反过来
• intent-simplify-over-decorate - 与其给一个包装元素添加 5 个工具类，不如直接移除它
• intent-match-context-fidelity - 让设计精致度与使用场景相匹配——管理后台、消费者产品或产品界面
• intent-match-existing-patterns - 重新设计样式之前，先检查同级组件的模式

2. 视觉层级（关键）

• hier-size-weight-color - 使用字号、字重和颜色建立层级，而不只是字号
• hier-deemphasize-secondary - 弱化次要内容，而不是强化主要内容
• hier-button-hierarchy - 根据视觉层级而非语义重要性设置按钮样式
• hier-label-value-pairs - 将标签和值组合成自然语言
• hier-semantic-vs-visual - 将视觉层级与文档层级区分开
• hier-icon-sizing - 根据相邻文本调整图标大小，而不是为了填满空间
• hier-color-hierarchy-on-dark - 在有色背景上使用透明度或柔和颜色来建立层级

3. 布局与间距（关键）

• space-start-generous - 先留出过多的空白，再逐步删减
• space-systematic-scale - 使用有限的间距比例，不要随意设值
• space-relationship-proximity - 用间距体现元素之间的关系
• space-dont-fill-screen - 限制内容宽度，避免铺满整个屏幕
• space-grids-not-required - 无需网格时使用固定宽度
• space-relative-sizing-fails - 避免使用未经限制的原始视口单位
• space-mobile-first - 优先针对约 400px 的移动设备进行设计，再逐步扩展

4. 字体排印（高）

• type-line-length - 将行长控制在 45-75 个字符
• type-line-height-inverse - 行高与字号成反比
• type-font-weight-variety - 选择至少有 5 种字重的字体
• type-no-center-long-text - 正文左对齐，避免长篇文本居中
• type-letter-spacing - 标题缩小字间距，全大写文本则增大字间距
• type-align-numbers-right - 表格中的数字右对齐，便于比较

5. 色彩系统（高）

• color-define-palette-upfront - 预先定义完整的调色板，不要临时挑选颜色
• color-grayscale-first - 先以灰度进行设计，最后再添加颜色
• color-accessible-contrast - 确保正文的对比度达到 4.5:1
• color-dark-gray-not-black - 文本使用深灰色，而非纯黑色
• color-saturated-grays - 在灰色中加入微妙的色彩倾向，营造暖色或冷色效果
• color-light-backgrounds-dark-text - 徽章使用浅色背景和深色文本

6. 深度与阴影（中）

• depth-shadow-scale - 定义固定的阴影比例，从小到特大
• depth-shadow-vertical-offset - 使用垂直偏移，打造自然的阴影效果
• depth-interactive-elevation - 通过阴影变化传达交互性
• depth-light-closer-dark-recedes - 较浅的颜色显得更近，较深的颜色则显得更远
• depth-overlap-layers - 通过重叠元素创建视觉层次

7. 边框与分隔（中）

• sep-fewer-borders - 减少边框，改用间距、阴影或背景色
• sep-background-color-separation - 使用不同的背景色分隔区块
• sep-table-spacing-not-lines - 简单表格使用间距而非线条
• sep-card-radio-buttons - 将单选按钮升级为可选卡片，供用户做出重要选择

8. 图像与内容（低至中）

• img-control-user-content - 控制用户上传图像的尺寸和宽高比
• img-text-overlay - 为图像添加叠加层，或降低图像对比度以便显示文字
• img-dont-scale-up-icons - 避免放大专为小尺寸设计的图标
• img-empty-states - 设计有意义且包含明确 CTA 的空状态

9. 润色与细节（低）

• polish-accent-borders - 为重要元素添加强调边框
• polish-custom-bullets - 用图标或勾选标记替换默认项目符号
• polish-border-radius-personality - 让圆角与品牌个性相匹配
• polish-gradient-close-hues - 使用色相相差不超过 30 度的渐变
• polish-inner-shadow-images - 添加内阴影，避免图像背景透出

范围与限制

此技能依据 Refactoring UI 的原则，涵盖布局、层级、间距、颜色和润色。它不涵盖：

• 字体选择与搭配——选择具有鲜明特色的字体、避免使用常见的 AI 默认字体（Inter、Arial、system-ui），或搭配展示字体与正文字体
• 动画与动效——有意义的过渡效果、微交互、页面加载序列或滚动触发的显示效果
• 创意方向——确立美学愿景、选择风格（极简、极繁、粗野主义等），或区别于千篇一律的“AI 垃圾”美学
• 空间构图——非对称布局、打破网格的元素或非常规的视觉流动

对于这些方面，请将此技能与涵盖创意方向和美学实现的设计思维或前端设计技能搭配使用。

使用方法

阅读各个参考文件，了解详细说明和代码示例：

• 章节定义 - 类别结构和影响等级
• 规则模板 - 添加新规则的模板

参考文件

文件	描述
references/_sections.md	类别定义与排序
assets/templates/_template.md	新规则模板
metadata.json	版本和参考信息