visual-hierarchy-refactoring

视觉层级重构

选取一个真实屏幕或组件进行重构，让视线按正确顺序落在正确的内容上。交付内容是重构后的代码，以及一份重构前后的层级审查——而不是设计评论。指导原则：层级取决于尺寸、字重和明度对比——颜色是最后的手段；最快的修复方式是弱化强调：先降低噪声，再放大信号。

适用场景 / 交接

• 当某个具体屏幕杂乱、扁平、难以浏览，或在设计令牌合理的情况下仍然“看起来不对劲”时使用。
• 完全没有统一的令牌（每次修复都要新增一个神奇数值）→ 先处理 skills/frontend-design/design-foundation。
• 问题在于结构（列未对齐、在移动设备上显示异常）→ skills/frontend-design/layout-system。
• 整个应用的字号本身杂乱无章 → skills/frontend-design/typography-system。
• 问题出在调色板（色相冲突、到处都有对比度问题）→ skills/frontend-design/color-system。

第 1 步 — 检查目标

1. 获取实际组件。 阅读用户指定屏幕对应的文件；如果用户未指定，请询问最重要的那个屏幕（这是唯一会阻塞流程的初始问题）。如果环境允许，请将其渲染或截图。
2. 读取可用的设计令牌（间距比例、文本尺寸、灰度阶）——每项修复都必须使用这些令牌。
3. 通过代码检测层级问题，并统计数量：
   • 强调膨胀：每个屏幕上有多少元素使用了粗体、彩色、大字号或边框？（超过 3 个相互竞争的强调元素 = 没有任何内容真正突出）
   • 间距拥挤：无关组之间的内边距/外边距 ≤8px
   • 纯灰色 / 纯黑色：#808080 系列、#000、彩色表面上的 text-gray-500
   • 尺寸一致：标题、正文和元数据之间的字号级差不超过一级
   • 到处间距相同：组内和组间的间距完全一致（破坏格式塔分组）
   • 边框过度使用：用层层方框划分区域，而不是通过间距分隔

第 2 步 — 编制层级审查

针对目标屏幕，列出每个可见元素并分配：

• 预期优先级：P1（此屏幕存在的核心目的——一个元素，也可能是两个）、P2（辅助内容）、P3（元数据/界面装饰）。
• 当前视觉权重：醒目 / 中等 / 轻淡，根据尺寸、字重、颜色和周边内容判断。

每项不匹配都是一项待处理工作。如果无法指出唯一的 P1，请问用户一个问题：“用户在这个屏幕上应该先做什么或先看到什么？”——然后继续。

第 3 步 — 按此顺序重构

严格按以下顺序应用更改——每轮调整通常都能减少下一步所需的工作：

1. 先调整留白。 先留得太多，再逐步收紧。将无关组之间的间距加倍；相关项则保持紧凑（标签与输入框相距 8px；表单组之间至少相距 24px）。如果标准边距为 16px，尝试将区块之间的间距设为 32–48px。间距必须来自设计令牌比例。
2. 先弱化 P2/P3，再处理 P1。 去掉标签的粗体，将元数据颜色调浅至中灰阶（gray-500/600），移除将次要内容框起来的边框或背景，缩小三级操作的尺寸或改为仅显示图标。次要按钮使用描边或幽灵样式；破坏性操作在确认前保持低调。
3. 然后突出 P1——通常消除噪声后只需做一项调整：字号增大一级，或字重从 600 提至 700，或使用最深的文本色阶，或使用唯一一个高饱和度 CTA。不要四项都做。
4. 通过明度而非色相建立对比阶梯： P1 文本使用最深的灰阶，P2 使用 gray-600/700，P3 使用 gray-500。仅使用色调匹配品牌冷暖倾向的灰色——绝不使用 #808080/#000。高饱和度颜色仅用于交互元素和状态。
5. 按照格式塔原则分组： 邻近性（通过间距体现关系——组间距至少为组内间距的 2 倍）、相似性（相同角色的元素外观一致）、共同区域（只有在间距无法完成分组时才使用卡片/背景）。完整原则集及 CSS 示例：references/gestalt-principles.md。
6. 尺寸比例： 相邻层级的尺寸相差约 1.25–1.5 倍；P1 与正文相差约 1.5–2 倍。如果两个层级相差不到 10%，就将它们合并。

典型的修改前后示例（大多数修复的形式）

/* BEFORE: cramped, uniform, grey-on-grey */
.card { padding: 8px; }
.card h2 { font-size: 16px; font-weight: 400; color: #666; margin-bottom: 4px; }
.card p  { font-size: 14px; color: #999; line-height: 1.3; }

/* AFTER: room, clear ladder, tinted greys */
.card { padding: var(--space-6); }
.card h2 { font-size: var(--text-xl); font-weight: 600; color: var(--gray-900); margin-bottom: var(--space-2); }
.card p  { font-size: var(--text-base); color: var(--gray-600); line-height: 1.6; }
.card .meta { font-size: var(--text-sm); color: var(--gray-500); }

必需的输出格式

交付代码以及以下审查结果：

## Hierarchy audit — [screen name]
| Element | Intended | Was | Problem | Change |
| Submit button | P1 | quiet (same as Cancel) | competing siblings | solid brand bg; Cancel → ghost |
| Section labels | P3 | loud (bold, dark) | emphasis inflation | weight 400, gray-500 |
| Card metadata | P3 | medium | too prominent | text-sm, gray-500 |
| ... every element with a mismatch |

## Refactored code
[full component/CSS — same styling system, tokens only]

## What changed and why (≤5 bullets)
- [pass applied → effect, e.g. "Doubled inter-group spacing (space-4 → space-8): groups now scannable"]

## Scan test
First / second / third thing the eye hits now: [P1] → [P2] → [P2]. Matches intent: [yes / remaining gap]

质量标准（交付前检查）

• 每个屏幕恰好有一个 P1，且它能在 5 秒内浏览时脱颖而出
• 每个屏幕最多有 3 个强调元素；其余内容都应明显低调
• 无关组之间的间距至少为组内间距的 2 倍；所有间距均使用设计令牌比例
• 最终结果最多使用 3 种字重；绝不将整段文字设为粗体
• 文本阶梯使用色调匹配的灰色明度阶；不使用 #808080、#000，也不为强调而引入新色相
• 弱化后的文本仍符合 WCAG AA（4.5:1）——低调不等于难以辨认；仅在大字号下，P3 才可降至 3:1
• 相邻字号层级相差至少 1.25 倍；不存在相差不到 10% 的两个层级
• 只要单靠间距就能完成内容分组，就移除边框/框线
• 每项更改都引用一个设计令牌——不新增任何魔法数字

集成

• 输入：skills/frontend-design/design-foundation 中的设计令牌、skills/frontend-design/typography-system 中的字号阶梯、skills/frontend-design/color-system 中的灰阶、skills/frontend-design/layout-system 中的页面结构。
• 输出：经重构的组件，供 skills/frontend-design/component-architecture 泛化并纳入组件库；对比度决策由 skills/frontend-design/accessibility-excellence 验证。
• 在 skills/frontend-design/frontend-orchestrator 路径中，此步骤在设计令牌就绪后运行（路径 B 第 2 步），或作为边距级别的细化（路径 C）。

参考资料

• references/gestalt-principles.md — 六项格式塔原则（邻近性、相似性、图形/背景、闭合、对称性、共同区域）及其 CSS 应用，还有更多重构前后示例。当分组问题无法仅靠邻近性解决，或需要更多具体示例时，请阅读。