Back to Details

refactoring-ui

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Refactoring UI Design System

Refactoring UI设计系统

A practical, opinionated approach to UI design. Apply these principles when generating frontend code, reviewing designs, or advising on visual improvements.
这是一种务实、有明确主张的UI设计方法。在生成前端代码、评审设计或提供视觉优化建议时，均可应用这些原则。

Core Philosophy

核心理念

Design in grayscale first. Add color last. This forces proper hierarchy through spacing, contrast, and typography before relying on color as a crutch.
Start with too much white space, then remove. Dense interfaces feel overwhelming. Generous spacing feels premium.
Details come later. Don't obsess over icons, shadows, or micro-interactions until the layout and hierarchy work.
先以灰度模式设计，最后再添加色彩。 这能迫使你在依赖色彩之前，通过间距、对比度和排版来构建合理的层级结构。
先设置充足留白，再按需缩减。 布局紧凑的界面会给人压迫感，充足的留白则能营造高端感。
细节后置。 在布局和层级结构确定之前，不要纠结于图标、阴影或微交互细节。

Scoring

评分体系

Goal: 10/10. When reviewing or creating UI designs or frontend code, rate it 0-10 based on adherence to the principles below. A 10/10 means full alignment with all guidelines; lower scores indicate gaps to address. Always provide the current score and specific improvements needed to reach 10/10.
目标：10/10分。 在评审或创建UI设计或前端代码时，根据对以下原则的遵循程度给出0-10分的评分。10分表示完全符合所有准则；分数越低说明存在需要改进的地方。请始终提供当前评分以及达到10分所需的具体改进措施。

Visual Hierarchy

视觉层级

Not everything can be important. Create hierarchy through three levers:
LeverPrimarySecondaryTertiary
SizeLargeBaseSmall
WeightBold (600-700)Medium (500)Normal (400)
ColorDark gray (#111)Medium gray (#666)Light gray (#999)
Combine levers, don't multiply. Primary text = large OR bold OR dark, not all three. Save "all three" for the single most important element.
并非所有元素都同等重要。可通过三个维度来构建层级结构：
维度主要元素次要元素三级元素
尺寸大基础尺寸小
字重粗体（600-700）中等字重（500）常规字重（400）
颜色深灰（#111）中灰（#666）浅灰（#999）
组合维度，而非叠加所有维度。 主要文本只需满足大尺寸、粗体或深色中的一个即可，无需同时具备三者。仅将三者叠加用于单个最重要的元素。

Labels Are Secondary

标签属于次要元素

Form labels, table headers, metadata labels → these support the data, not compete with it. Make labels smaller, lighter, or uppercase-small.
❌ Name: John Smith     (label and value same weight)
✅ NAME                  (de-emphasized label)
   John Smith           (emphasized value)
表单标签、表格表头、元数据标签——这些元素是为数据提供支持，而非与数据争夺注意力。应让标签更小、字重更轻，或使用小型大写字母。
❌ Name: John Smith     (label and value same weight)
✅ NAME                  (de-emphasized label)
   John Smith           (emphasized value)

Semantic Color ≠ Visual Weight

语义颜色 ≠ 视觉权重

Don't make every destructive button bright red. A muted red secondary button often works better than screaming danger for routine actions.
不要让所有破坏性按钮都使用亮红色。对于常规操作，使用柔和的红色次要按钮往往比醒目的警示红色效果更好。

Spacing System

间距系统

Use a constrained spacing scale, not arbitrary values:
4px  → tight coupling (icon + label)
8px  → related elements
16px → standard gap
24px → section separation  
32px → major sections
48px → page sections
64px → hero spacing
Spacing defines relationships. Elements closer together = more related. Don't use the same spacing everywhere.
使用受限的间距刻度，而非任意数值：
4px  → 紧密关联（图标 + 标签）
8px  → 相关元素
16px → 标准间距
24px → 区块分隔  
32px → 主要区块
48px → 页面区块
64px → Hero区域间距
间距定义元素关系。 元素间距越近，关联性越强。不要在所有地方都使用相同的间距。

Container Width

容器宽度

  • Text blocks: 45-75 characters (use 
    max-w-prose
    or ~65ch)
  • Forms: 300-500px max width
  • Cards: Size to content, not viewport
  • Full-width is almost never right for content
  • 文本块： 每行45-75个字符（使用
    max-w-prose
    或约65ch）
  • 表单： 最大宽度300-500px
  • 卡片： 根据内容调整尺寸，而非视口
  • 内容几乎不适合使用全屏宽度

Typography

排版

Font Size Scale

字体尺寸刻度

Use a modular scale. Example (1.25 ratio):
12px → fine print, captions
14px → secondary text, labels  
16px → body text (base)
20px → subheadings
24px → section titles
30px → page titles
36px → hero headlines
使用模块化刻度。示例（比例1.25）：
12px → 小字、说明文字
14px → 次要文本、标签  
16px → 正文文本（基础）
20px → 副标题
24px → 区块标题
30px → 页面标题
36px → Hero区域标题

Line Height Rules

行高规则

  • Headings: 1.0 - 1.25 (tight)
  • Body text: 1.5 - 1.75 (relaxed)
  • Wider text = more line height needed
  • 标题： 1.0-1.25（紧凑）
  • 正文： 1.5-1.75（宽松）
  • 文本宽度越宽，所需行高越大

Font Weight Strategy

字重策略

Avoid font weights below 400 for body text—they become unreadable. Use bold (600-700) for emphasis, not for everything.
Two fonts maximum: one for headings, one for body. Or use one font family with weight variation.
正文字重不要低于400，否则会难以阅读。使用粗体（600-700）来强调内容，但不要过度使用。 最多使用两种字体：一种用于标题，一种用于正文。或者使用同一字体家族的不同字重变体。

Color

色彩

Build a Palette, Not Random Colors

构建调色板，而非随意选色

Each color needs 5-9 shades from near-white to near-black:
Gray:    50, 100, 200, 300, 400, 500, 600, 700, 800, 900
Primary: 50, 100, 200, 300, 400, 500, 600, 700, 800, 900
The darkest shade isn't black. Use 900-level dark grays (e.g., 
#111827
) instead of pure 
#000000
.
每种颜色需要5-9种色调，从近白色到近黑色：
Gray:    50, 100, 200, 300, 400, 500, 600, 700, 800, 900
Primary: 50, 100, 200, 300, 400, 500, 600, 700, 800, 900
最深的色调并非纯黑色。 使用900级深灰色（例如
#111827
）而非纯黑色
#000000
。

Grays Need Saturation

灰色需要添加饱和度

Pure gray (
#808080
) looks lifeless. Add subtle saturation:
  • Cool UI: Slight blue tint (
    #64748b
    )
  • Warm UI: Slight yellow/brown tint (
    #78716c
    )
纯灰色（
#808080
）看起来毫无生气。可添加轻微饱和度：
  • 冷色调UI：略带蓝色色调（
    #64748b
    ）
  • 暖色调UI：略带黄/棕色色调（
    #78716c
    ）

HSL Adjustments

HSL调整规则

When deriving shades:
  • Lighter = higher lightness, lower saturation, shift hue toward 60° (yellow)
  • Darker = lower lightness, higher saturation, shift hue toward 0°/240° (red/blue)
生成色调时：
  • 浅色：更高明度，更低饱和度，色相向60°（黄色）偏移
  • 深色：更低明度，更高饱和度，色相向0°/240°（红色/蓝色）偏移

Accessible Contrast

可访问的对比度

  • Body text: minimum 4.5:1 contrast ratio
  • Large text (18px+): minimum 3:1
  • Use 
    #374151
    (gray-700) on white, not lighter grays
  • 正文文本：对比度至少4.5:1
  • 大文本（18px及以上）：对比度至少3:1
  • 在白色背景上使用
    #374151
    （gray-700），而非更浅的灰色

Depth & Shadows

深度与阴影

Shadow Scale

阴影刻度

Small shadows = raised slightly (buttons, cards) Large shadows = floating (modals, dropdowns)
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);
Shadows have two parts: A tight, dark shadow for crispness + a larger, softer shadow for atmosphere.
小阴影 = 轻微凸起（按钮、卡片） 大阴影 = 悬浮效果（模态框、下拉菜单）
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);
阴影包含两部分： 紧凑的深色阴影用于营造清晰感，较大的柔和阴影用于营造氛围。

Creating Depth Without Shadows

无需阴影即可营造深度

  • Lighter top border, darker bottom border
  • Subtle gradient backgrounds (lighter at top)
  • Overlapping elements with offset
  • 顶部边框较浅，底部边框较深
  • 微妙的渐变背景（顶部更浅）
  • 元素偏移重叠

Layout Patterns

布局模式

Don't Center Everything

不要让所有内容居中

Left-aligned text is easier to read. Center only:
  • Short headlines
  • Hero sections
  • Single-action CTAs
  • Empty states
左对齐文本更易阅读。仅对以下内容使用居中对齐：
  • 短标题
  • Hero区域
  • 单一行动的CTA
  • 空状态

Break Out of the Box

打破容器限制

Cards don't need to contain everything. Let images bleed to edges, overlap containers, or extend beyond their bounds.
卡片无需包含所有内容。可让图片延伸至边缘、与容器重叠或超出边界。

Alternate Emphasis

交替突出显示

In lists/feeds, vary the visual treatment. Not every card needs the same layout—feature some, minimize others.
在列表/信息流中，改变视觉处理方式。并非所有卡片都需要相同布局——突出部分卡片，弱化其他卡片。

Practical Checklist

实用检查清单

Before considering UI "done":
  • Squint test: Does hierarchy still read when blurred?
  • Grayscale test: Does it work without color?
  • Is there enough white space? (Probably not)
  • Are labels de-emphasized vs. their values?
  • Does spacing follow a consistent scale?
  • Is text width constrained for readability?
  • Do colors have sufficient contrast?
  • Are shadows appropriate for elevation level?
在认为UI已完成之前，请检查：
  • 眯眼测试：模糊后是否仍能识别层级结构？
  • 灰度测试：去掉色彩后是否仍能正常使用？
  • 是否有足够的留白？（可能没有）
  • 标签是否比对应内容更弱化？
  • 间距是否遵循统一的刻度？
  • 文本宽度是否为了可读性而受限？
  • 颜色是否有足够的对比度？
  • 阴影是否与层级高度匹配？

Quick Fixes for Common Problems

常见问题快速修复

ProblemFix
"Looks amateur"Add more white space, constrain widths
"Feels flat"Add subtle shadows, border-bottom on sections
"Text is hard to read"Increase line-height, constrain width, boost contrast
"Everything looks the same"Vary size/weight/color between primary and secondary elements
"Feels cluttered"Group related items, increase spacing between groups
"Colors clash"Reduce saturation, use more grays, limit palette
"Buttons don't pop"Increase contrast with surroundings, add shadow
问题修复方案
"看起来很业余"增加更多留白，限制宽度
"感觉很扁平"添加微妙阴影，在区块底部添加边框
"文本难以阅读"增加行高，限制宽度，提高对比度
"所有元素看起来都一样"区分主要和次要元素的尺寸/字重/颜色
"感觉杂乱"分组相关项，增加组间间距
"颜色冲突"降低饱和度，使用更多灰色，限制调色板
"按钮不突出"提高与周围环境的对比度，添加阴影

Tailwind Quick Reference

Tailwind快速参考

For Tailwind CSS implementations:
Spacing:    p-1(4px) p-2(8px) p-4(16px) p-6(24px) p-8(32px)
Text size:  text-xs(12) text-sm(14) text-base(16) text-lg(18) text-xl(20)
Font weight: font-normal(400) font-medium(500) font-semibold(600) font-bold(700)  
Text color: text-gray-900(dark) text-gray-600(medium) text-gray-400(light)
Max width:  max-w-prose(65ch) max-w-md(28rem) max-w-lg(32rem) max-w-xl(36rem)
Shadow:     shadow-sm shadow-md shadow-lg shadow-xl
适用于Tailwind CSS实现：
Spacing:    p-1(4px) p-2(8px) p-4(16px) p-6(24px) p-8(32px)
Text size:  text-xs(12) text-sm(14) text-base(16) text-lg(18) text-xl(20)
Font weight: font-normal(400) font-medium(500) font-semibold(600) font-bold(700)  
Text color: text-gray-900(dark) text-gray-600(medium) text-gray-400(light)
Max width:  max-w-prose(65ch) max-w-md(28rem) max-w-lg(32rem) max-w-xl(36rem)
Shadow:     shadow-sm shadow-md shadow-lg shadow-xl

Advanced Topics

进阶主题

For deeper guidance on specific patterns, see references/advanced-patterns.md:
  • Empty states design
  • Form design & input states
  • Image treatment & overlays
  • Icon sizing & usage
  • Interaction states (hover, focus, active)
  • Color psychology
  • Border radius systems
  • Text truncation
  • Responsive breakpoints
如需特定模式的深入指导，请参阅references/advanced-patterns.md：
  • 空状态设计
  • 表单设计与输入状态
  • 图片处理与叠加层
  • 图标尺寸与使用规范
  • 交互状态（hover、focus、active）
  • 色彩心理学
  • 圆角系统
  • 文本截断
  • 响应式断点

Additional Reference Files

其他参考文件

  • animation-microinteractions.md: When to animate, easing functions, durations, loading states, performance
  • accessibility-depth.md: WCAG 2.1 AA checklist, focus management, screen reader support
  • data-visualization.md: Chart selection, color in charts, table design, dashboard layouts
  • theming-dark-mode.md: Dark palette creation, elevation in dark mode, implementation strategies
  • animation-microinteractions.md：动画使用场景、缓动函数、时长、加载状态、性能优化
  • accessibility-depth.md：WCAG 2.1 AA检查清单、焦点管理、屏幕阅读器支持
  • data-visualization.md：图表选择、图表配色、表格设计、仪表盘布局
  • theming-dark-mode.md：深色调色板创建、深色模式下的层级、实现策略