tailwind-ui-refactor

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Refactoring UI Tailwind CSS Best Practices

Tailwind CSS UI重构最佳实践

Comprehensive UI refactoring guide based on Refactoring UI by Adam Wathan & Steve Schoger, implemented with Tailwind CSS utility classes. Contains 52 rules across 9 categories, prioritized by design impact to guide automated refactoring and code generation. Uses Tailwind CSS v4 syntax (v3 notes provided where syntax differs).

Important: Think first, style second. Before applying any visual rule, understand the UI's purpose, identify what matters to the user, and remove unnecessary elements. The Design Intent category (priority 1) must be considered before any styling changes. A simpler component with fewer elements always beats a decorated component with unnecessary markup.

本指南基于Adam Wathan和Steve Schoger所著的《Refactoring UI》，结合Tailwind CSS工具类实现了一套全面的UI重构方案。包含9个分类下的52条规则，按设计影响优先级排序，可用于指导自动化重构和代码生成。使用Tailwind CSS v4语法（在语法不同的地方会提供v3说明）。

重要提示：先思考，再样式化。 在应用任何视觉规则之前，先理解UI的用途，识别对用户重要的内容，并移除不必要的元素。必须优先考虑优先级1的「设计意图」分类，再进行任何样式修改。一个元素更少的简洁组件，永远比带有不必要标记的装饰性组件更优。

When to Apply

适用场景

Reference these guidelines when:

Refactoring existing Tailwind CSS components
Writing new UI with Tailwind utility classes
Reviewing code for visual hierarchy and spacing issues
Improving design quality without a designer
Fixing accessibility contrast problems

在以下场景中可以参考本指南：

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

Rule Categories by Priority

按优先级排序的规则分类


intent-
hier-
space-
type-
color-
depth-
sep-
img-
polish-

Priority	Category	Impact	Prefix
1	Design Intent	CRITICAL	`intent-`
2	Visual Hierarchy	CRITICAL	`hier-`
3	Layout & Spacing	CRITICAL	`space-`
4	Typography	HIGH	`type-`
5	Color Systems	HIGH	`color-`
6	Depth & Shadows	MEDIUM	`depth-`
7	Borders & Separation	MEDIUM	`sep-`
8	Images & Content	LOW-MEDIUM	`img-`
9	Polish & Details	LOW	`polish-`


intent-
hier-
space-
type-
color-
depth-
sep-
img-
polish-

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

Quick Reference

快速参考

1. Design Intent (CRITICAL)

1. 设计意图（关键）

```
intent-audit-before-styling
```
- Audit what each element communicates before changing any CSS
```
intent-remove-before-decorating
```
- Remove unnecessary elements before styling what remains
```
intent-reduce-cognitive-load
```
- Reduce choices per screen — fewer options beat prettier options
```
intent-progressive-disclosure
```
- Hide secondary information behind interactions
```
intent-content-drives-layout
```
- Let real content determine layout — not the other way around
```
intent-simplify-over-decorate
```
- Prefer removing a wrapper over adding 5 utility classes to it
```
intent-match-context-fidelity
```
- Match design polish to context — admin vs consumer vs product
```
intent-match-existing-patterns
```
- Audit sibling component patterns before restyling

```
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. Visual Hierarchy (CRITICAL)

2. 视觉层级（关键）

```
hier-size-weight-color
```
- Use size, weight, and color for hierarchy — not just size
```
hier-deemphasize-secondary
```
- De-emphasize secondary content instead of emphasizing primary
```
hier-button-hierarchy
```
- Style buttons by visual hierarchy, not semantic importance
```
hier-label-value-pairs
```
- Combine labels and values into natural language
```
hier-semantic-vs-visual
```
- Separate visual hierarchy from document hierarchy
```
hier-icon-sizing
```
- Size icons relative to adjacent text, not to fill space
```
hier-color-hierarchy-on-dark
```
- Use opacity or muted colors for hierarchy on colored backgrounds

```
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. Layout & Spacing (CRITICAL)

3. 布局与间距（关键）

```
space-start-generous
```
- Start with too much whitespace, then remove
```
space-systematic-scale
```
- Use a constrained spacing scale, not arbitrary values
```
space-relationship-proximity
```
- Use spacing to show relationships between elements
```
space-dont-fill-screen
```
- Constrain content width — avoid filling the whole screen
```
space-grids-not-required
```
- Use fixed widths when grids are not needed
```
space-relative-sizing-fails
```
- Avoid raw viewport units without clamping
```
space-mobile-first
```
- Design mobile-first at ~400px, then expand

```
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. Typography (HIGH)

4. 排版（高）

```
type-line-length
```
- Keep line length between 45-75 characters
```
type-line-height-inverse
```
- Line height and font size are inversely proportional
```
type-font-weight-variety
```
- Choose fonts with at least 5 weight variations
```
type-no-center-long-text
```
- Left-align body content — avoid centering long-form text
```
type-letter-spacing
```
- Tighten letter spacing for headlines, loosen for uppercase
```
type-align-numbers-right
```
- Align numbers right in tables for easy comparison

```
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 Systems (HIGH)

5. 色彩系统（高）

```
color-define-palette-upfront
```
- Define a complete color palette upfront — don't pick colors ad-hoc
```
color-grayscale-first
```
- Design in grayscale first, add color last
```
color-accessible-contrast
```
- Ensure 4.5:1 contrast ratio for body text
```
color-dark-gray-not-black
```
- Use dark gray instead of pure black for text
```
color-saturated-grays
```
- Add subtle saturation to grays for warmth or coolness
```
color-light-backgrounds-dark-text
```
- Use light-colored backgrounds with dark text for badges

```
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 & Shadows (MEDIUM)

6. 层次感与阴影（中）

```
depth-shadow-scale
```
- Define a fixed shadow scale — small to extra large
```
depth-shadow-vertical-offset
```
- Use vertical offset for natural-looking shadows
```
depth-interactive-elevation
```
- Use shadow changes to communicate interactivity
```
depth-light-closer-dark-recedes
```
- Lighter colors feel closer, darker colors recede
```
depth-overlap-layers
```
- Overlap elements to create visual layers

```
depth-shadow-scale
```
- 定义固定的阴影比例——从小到超大
```
depth-shadow-vertical-offset
```
- 使用垂直偏移来营造自然的阴影效果
```
depth-interactive-elevation
```
- 使用阴影变化来传达可交互性
```
depth-light-closer-dark-recedes
```
- 浅色看起来更近，深色看起来更远
```
depth-overlap-layers
```
- 让元素重叠以创建视觉层级

7. Borders & Separation (MEDIUM)

7. 边框与分隔（中）

```
sep-fewer-borders
```
- Use fewer borders — replace with spacing, shadows, or background color
```
sep-background-color-separation
```
- Use background color differences to separate sections
```
sep-table-spacing-not-lines
```
- Use spacing instead of lines in simple tables
```
sep-card-radio-buttons
```
- Upgrade radio buttons to selectable cards for key choices

```
sep-fewer-borders
```
- 减少边框的使用——用间距、阴影或背景色替代
```
sep-background-color-separation
```
- 使用背景色差异来分隔区块
```
sep-table-spacing-not-lines
```
- 在简单表格中使用间距而非线条
```
sep-card-radio-buttons
```
- 将关键选项的单选按钮升级为可选择的卡片

8. Images & Content (LOW-MEDIUM)

8. 图片与内容（低-中）

```
img-control-user-content
```
- Control user-uploaded image size and aspect ratio
```
img-text-overlay
```
- Add overlays or reduce contrast for text over images
```
img-dont-scale-up-icons
```
- Avoid scaling up icons designed for small sizes
```
img-empty-states
```
- Design meaningful empty states with clear CTAs

```
img-control-user-content
```
- 控制用户上传图片的尺寸和宽高比
```
img-text-overlay
```
- 在图片上的文本添加遮罩或降低对比度
```
img-dont-scale-up-icons
```
- 避免放大为小尺寸设计的图标
```
img-empty-states
```
- 设计有意义的空状态页面，并包含清晰的CTA

9. Polish & Details (LOW)

9. 精致化细节（低）

```
polish-accent-borders
```
- Add accent borders to highlight important elements
```
polish-custom-bullets
```
- Replace default bullets with icons or checkmarks
```
polish-border-radius-personality
```
- Match border radius to brand personality
```
polish-gradient-close-hues
```
- Use gradients with hues within 30 degrees of each other
```
polish-inner-shadow-images
```
- Add inner shadow to prevent image background bleed

```
polish-accent-borders
```
- 添加强调边框以突出重要元素
```
polish-custom-bullets
```
- 用图标或对勾替换默认项目符号
```
polish-border-radius-personality
```
- 让边框圆角与品牌个性匹配
```
polish-gradient-close-hues
```
- 使用色相相差30度以内的渐变色
```
polish-inner-shadow-images
```
- 添加内阴影以防止图片背景溢出

Scope & Limitations

范围与限制

This skill covers layout, hierarchy, spacing, color, and polish based on Refactoring UI principles. It does NOT cover:

Font selection & pairing — choosing distinctive typefaces, avoiding generic AI defaults (Inter, Arial, system-ui), or pairing display + body fonts
Animation & motion — meaningful transitions, micro-interactions, page load sequences, or scroll-triggered reveals
Creative direction — establishing an aesthetic vision, choosing a tone (minimal, maximalist, brutalist, etc.), or differentiating from generic "AI slop" aesthetics
Spatial composition — asymmetric layouts, grid-breaking elements, or unconventional visual flow

For these concerns, pair this skill with a design-thinking or frontend-design skill that covers creative direction and aesthetic execution.

本技能基于《Refactoring UI》原则，涵盖布局、层级、间距、色彩和精致化细节。但不包括以下内容：

字体选择与搭配——选择独特字体、避免通用AI默认字体（Inter、Arial、system-ui），或搭配展示字体与正文字体
动画与动效——有意义的过渡、微交互、页面加载序列或滚动触发的显示效果
创意方向——确立美学愿景、选择风格（极简、极繁、粗野主义等），或与通用“AI模板化”美学形成差异
空间构图——非对称布局、打破网格的元素或非常规视觉流

若需处理这些问题，请将本技能与涵盖创意方向和美学执行的设计思维或前端设计技能结合使用。

How to Use

使用方法

Read individual reference files for detailed explanations and code examples:

Section definitions - Category structure and impact levels
Rule template - Template for adding new rules

阅读单个参考文件以获取详细说明和代码示例：

区块定义 - 分类结构和影响级别
规则模板 - 添加新规则的模板

Reference Files

参考文件

File	Description
references/_sections.md	Category definitions and ordering
assets/templates/_template.md	Template for new rules
metadata.json	Version and reference information

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