visual-hierarchy-refactoring

用途

Visual Hierarchy Refactoring 用于把一个真实的界面或组件重构为视觉顺序清晰的版本，让眼睛先落在正确的内容上，再依次看到次级信息。它强调的目标是“重构后的代码加前后层级审计”，而不是纯设计评论。

其核心理念是：层级由尺寸、字重和明度对比决定，颜色是最后手段；最快的修复方式是先弱化噪音，再强化信号。

适用场景与交接

适用于某个具体页面杂乱、扁平、难以扫读，或虽然设计令牌合理但“看起来不太对”的情况。
如果完全没有一致的令牌（每次修复都会产生新的魔法数字），应先使用 skills/frontend-design/design-foundation。
如果问题是结构性的（列未对齐、移动端断行异常），应转向 skills/frontend-design/layout-system。
如果全应用字号混乱，应转向 skills/frontend-design/typography-system。
如果问题出在配色（色相冲突、到处对比度不足），应转向 skills/frontend-design/color-system。

使用方式

第一步：检查目标

获取实际组件。读取用户指定页面的文件；如果未指定，则询问最重要的是哪一个页面（这是唯一会阻塞流程的提问）。在环境允许时进行渲染或截图。

读取可用令牌（间距刻度、文字尺寸、灰阶），每个修复都必须使用这些令牌。

在代码中检测层级异味并统计数量：

强调膨胀：每个页面有多少元素是加粗、着色、放大或有边框的（超过 3 个相互竞争的强调项，等于没有强调）。
间距拥挤：不相关分组之间的内边距或外边距不超过 8px。
纯灰或纯黑：#808080 系列、#000、在有色背景上使用 text-gray-500。
字号一致：标题、正文和元数据之间差距只有一个步进。
间距均匀：分组内部与分组之间使用相同间隔，破坏格式塔分组。
边框滥用：本可用间距分隔的地方使用了层层嵌套的盒子。

第二步：构建层级审计

对目标页面，列出每个可见元素并标注：

预期优先级：P1（该页面存在的主要目的，只能一到两个元素）、P2（支持性）、P3（元数据或界面框架）。
当前视觉重量：响、中、静，依据尺寸、字重、颜色和周围环境判断。

每个错配都是一项待办工作。如果无法确定唯一的 P1，向用户提问一次：“用户在这个页面上首先应该做什么或看到什么？”然后继续。

第三步：按顺序重构

严格按以下顺序应用改动，每一轮常常会消除下一轮的必要性：

留白优先。从偏多开始再收回。不相关分组之间的间距加倍；相关项保持靠近（标签距其输入框 8px；表单分组之间 24px 以上）。如果标准外边距是 16px，区块之间尝试 32–48px。间距必须来自令牌刻度。
在触碰 P1 之前先弱化 P2/P3：去掉标签的加粗，把元数据调淡到中间灰阶（gray-500/600），移除将次要内容框住的边框或背景，缩小或把三级操作改为图标。次要按钮改为描边或幽灵样式；破坏性操作在确认前保持安静。
然后强化 P1，噪音消除后通常只需一个动作：升一个字号步进，或字重从 600 到 700，或使用最深的文字阶，或唯一的高饱和 CTA。不要四个全用。
用明度而非色相建立对比梯：P1 文字用最深灰阶，P2 用 gray-600/700，P3 用 gray-500。只使用带色调的灰色（匹配品牌冷暖），绝不用 #808080 或 #000。饱和色只留给交互元素和状态。
用格式塔规则分组：接近性（间距表达关系，分组之间的间隙至少是组内间隙的 2 倍）、相似性（相同角色看起来相同）、共同区域（仅当间距无法完成工作时才使用卡片或背景）。完整原则与 CSS 见 references/gestalt-principles.md。
尺寸比例：相邻层级相差约 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 路径中，它在令牌存在后运行（Path B 第 2 步），或作为边距级细化（Path C）。

参考资料

references/gestalt-principles.md：全部六个格式塔原则（接近性、相似性、图形与背景、闭合、对称、共同区域）及其 CSS 应用，外加扩展的前后重构示例。当分组问题仅靠接近性无法解决，或需要更多完整示例时阅读。

限制

资料未提供该技能的具体收费、价格、支持平台或效果数据；以上内容仅依据已有描述整理，未作推断。