enhance-web-ui

界面路由：/uiux。当前技能：enhance-web-ui。原生 iOS/Android（SwiftUI / Compose，不含 Web 层）不在范围内——请直接使用 Apple HIG / Material。

优化页面 UI

自由度：混合。 布局和层级判断 [高自由度]；实时读取、DOM rects、三视口验证 [低自由度——严格照做]。

将现有屏幕改造为布局得当的界面：层级更清晰、内容放置更合理、动效富有表现力且服务于目的，并采用有助于理解的精巧过渡效果。这不是一种“添加更多标签/卡片/阴影”的技能。应先重新布局、删减和安排信息，再添加装饰。

用户模糊却直觉强烈的反馈（“笨重”“糟糕透顶”“空间浪费”“高度不协调”）几乎总是指向下方 §X 中的 Hidden Failure Mode——请从那里入手，而不是从用户提到的表面装饰着手。

如果使用浏览器自动化，请先遵循 protocol-browser-anti-stall 技能（如果存在）。

推理方式

1. 侦察——基础组件、设计令牌、真实数据契约
2. 排序——主要内容 / 次要内容 / 元数据 / 操作 / 环境元素
3. 布局——删减 → 分组 → 固定 → 安排，然后再装饰
4. 验证——1440/1024/800 + 两次眯眼检查 + rect 一致性

示例

**侦察：**学习应用（A 级）；统计卡片共用一个 Tooltip 包装器；“今天 0/10”出现了三次。 **排序：**主要内容是“下一课” CTA。计数属于元数据，不是第三个标题。 **布局：**将 Tooltip 修复为 block w-full；删除两处重复计数；不添加额外标签。 **验证：**卡片宽度一致；分类眯眼检查能看出不同色相；CTA 仍然只有一个品牌色目标。

汇报前自我检查

• 先布局——装饰不是第一项修改
• 使用真实数据——不使用模拟状态/计数；如果问题重复出现，则修复基础组件
• 三个视口——CTA 不换行；内容为空时，空白位置应折叠
• 找对负责人——流程/信息架构 → enhance-web-ux；仅涉及断点 → audit-responsive

---

规则

先构建，再装饰。 在添加渐变、动效、模糊、蒙版或阴影之前，先调整层级、分组、对齐和节奏。

用结构取代杂乱。 不要在拥挤的界面上继续堆叠徽章、标签、卡片、分隔线或辅助文本。将次要信息移到更安静的区域、页脚栏、悬停/聚焦时显示的内容、抽屉或渐进式披露层中。

一眼就能看出层级。 用户无需读完每个字，就应能知道焦点元素、辅助内容、元数据和操作的位置。

动效必须能说明问题。 仅为反馈、状态变化、空间关系、可操作性提示或吸引注意而添加动效。除非循环闪光效果承载状态或品牌调性，且遵循减少动态效果的设置，否则不要使用。

使用本地设计系统。 重用现有基础组件、设计令牌、圆角、间距、字体排版、动画辅助工具以及深色/浅色表面。需要扩展时，先扩展本地基础组件，不要另造一个专用组件。

绝不交付模拟、无效或游离的 UI。 增强内容必须接入产品真实的数据契约、后端/API 状态、数据库架构或现有领域辅助工具。如果 UI 需要更好的视觉反馈，先寻找应当驱动反馈的真实状态、时间戳、数量、负责人、错误、进度、权限或生命周期数据。如果不存在必要数据，但完善用户体验离不开它，应提出或实现最小范围的后端/架构/API 扩展，而不是在组件中伪造状态。

根据视口控制信息密度。 桌面端可以容纳分层元数据。平板端需要更紧凑的分组。窄屏需要渐进式披露，且 CTA 不得换行。

扩展规则 — 根据产品领域调整饱和度；检查条件插槽是否存在无效状态；扫描单个视口内是否有信息重复；修补基础组件，而不是整个站点；装饰内容前先让界面框架更简洁；每个视觉区域只放置一个品牌色元素；激活状态 ≠ 更厚重的布局：references/live-read.md §扩展规则。

重新设计时应避免的常见默认选项。 如果没有明确指引，模型总会选用相同的几种样式：Inter / Roboto、所有控件都使用药丸形按钮、等宽字体或「01 / 02 / 03」式分区标签、奶油色/米白色画布、紫色渐变、三张等宽卡片、标题中使用斜体强调词。请改用仓库自身的字体、圆角和调色板令牌；如果初稿采用了其中任何一种，请在说明中指出并替换。

---

工作流检查清单

复制并跟踪：

UI ENHANCE /<route-or-component>
- [ ] 0. DOMAIN: product class -> colour-tier + density-tier (see Domain Colour Tier)
- [ ] 1. RECON: route, component tree, data fields, tokens, primitives, wrappers
- [ ] 2. CONTENT RANK: primary, secondary, metadata, actions, ambient
- [ ] 3. LIVE READ: 1440 / 1024 / 800 screenshots + DOM rect measurements
- [ ] 4. PAIN MAP: crowding, dead space, weak hierarchy, dup info, wrapper collapse,
 conditional-slot zero-state, monochromatic surfaces, hard cuts, bland motion
- [ ] 5. COMPOSITION PLAN: move, group, pin, crop, reveal, fade, animate
- [ ] 6. IMPLEMENT: primitive-level fixes first, smallest site-level diffs after
- [ ] 7. VERIFY: three viewports + DOM uniformity + squint-for-colour-distinction
 + reduced motion + dark/light if supported
- [ ] 8. WRITE-UP: before pain -> design principle -> after behavior

---

步骤 1 - 侦察：了解现有视觉系统 [HIGH freedom]

完整阅读路由/组件。然后检查：

• 布局基础组件：Card、Section、Drawer、Tabs、Badge、Button、 Tooltip、网格/列表辅助工具。
• 样式系统：Tailwind 配置、CSS 变量、设计令牌、主题上下文、 动画工具、现有圆角/阴影。
• 数据形状：所有可用字段，尤其是目前被塞入标题或隐藏在模态框中的元数据。
• 数据来源：API 端点、加载器/操作、数据库架构、缓存键、 后端状态枚举、验证错误、权限，以及能让 UI 反馈真实而非装饰性的生命周期事件。
• 现有注释：搜索 "DO NOT"、"avoid"、"deprecated"、"design"、 "layout"、"spacing"、"motion"、"overflow"。

输出一份简短的组件图：

<Page>
|-- Header - title, context, primary action
|-- Body/Grid/List - main content
|-- Detail/Drawer - progressive disclosure
`-- Footer/Chrome - metadata, controls, scroll status

还要列出从网格单元到渲染子元素这一链路上的每个包装器/布局基础组件：Tooltip、Trigger、Popover、Slot、 AnimatedDiv、Tippy、motion.div 等。注明每个组件默认的 display、 width 和 flex-shrink。包装器折叠问题就藏在这里；第 6 步中是否采用基础组件优先的修补方式也由此决定。

---

步骤 1.5 - 领域色彩与密度层级 [自由度高]

在使用任何颜色之前，先明确产品类别。同一种 /8 色调，用在金融仪表盘上会显得“高端而克制”，用在学习应用中却会显得“单调乏味”。先选择一个层级，再始终如一地应用——切勿在同一款产品中混用不同层级。

层级	示例	表面背景色调	强调色填充	分类色调的用法	来源
A — 鲜明 / 游戏化	Duolingo、Drops、Habitica、Strava、儿童/学习、健身、休闲游戏	/15–/25 渐变 + /30–/40 环形边框	实色令牌（bg-success、bg-cta），实色背景上的白色文本	每个有意义的类别都使用不同色调（成功/错误/连续记录/经验值/信息/高级）——颜色本身就是游戏化的一部分	Duolingo 设计系统；Figma 2026 趋势报告
B — 富有表现力的消费级产品	Spotify、Notion 的活泼界面、Robinhood 引导流程、内容/生活方式应用	/10–/18 渐变 + /20–/28 环形边框	半实色（bg-cta/85）	使用 3–5 种语义色调，装饰性配色保持克制	Spotify、Notion
C — 效率 / 专业工具	Linear、GitHub、Vercel、Figma 界面、设计工具	/6–/12 色调 + /15 环形边框	一种强调色 + 4 种语义状态色	强调色仅用于主要操作；语义状态色仅用于表示状态	Linear、Radix
D — 克制 / 数据密集型	Stripe 仪表盘、AWS 控制台、可观测性/金融/管理/医疗保健	表面基本使用中性色；仅在状态标签上使用 /4–/8	CTA 使用一种强调色；语义状态色分为 4 类（成功/警告/错误/信息）	颜色仅用于表示数据信号；界面元素保持无彩色——NN/g 60-30-10	Stripe、ColorArchive SaaS 仪表盘

如何判断层级（设计前先完成）：

1. 阅读产品的营销文案、README 或引导流程——出现 play、streak、level、fun、journey、daily、habit、master 等词 → 层级 A 或 B；出现 workspace、dashboard、report、audit、query、pipeline 等词 → 层级 C 或 D。
2. 查看现有的主要 CTA：饱和的实色搭配厚重阴影 → A；柔和的实色 → B/C；以描边或幽灵按钮为主 → D。
3. 查看语义状态令牌（success、warning、error、info，以及应用专属的 xp、streak、premium、ai、tone-1..6）。具有品牌含义的语义色调超过 5 种 → 层级 A。只有基础的 4 种 → 层级 C/D。

层级不匹配是消费级应用收到“单调”反馈的首要隐性原因。 层级 A 的产品若使用层级 D 的 /8 色调，就会显得黯淡、像是 AI 生成的，尽管每个令牌从技术上说都“正确”。

---

步骤 2 - 排版前确定内容优先级 [自由度高]

对每个可见元素进行分类：

优先级	含义	默认处理方式
主要	页面所展示的内容	尺寸最大、对比最强、空间最充足
次要	帮助理解主要内容	靠近主要内容，尺寸更小，分组呈现
元数据	日期、计数、统计数据、状态	固定在页脚/侧栏/表格列中，而非标题区域
操作	用户可执行的操作	靠近目标，点击区域大小稳定，不换行
氛围	品牌、情绪、装饰性信号	放置于背景，以遮罩降低对比度，并可移除

规则：

• 如果所有内容都是主要内容，就没有真正的主要内容。
• 如果元数据挤占标题空间，将其移至底部区域、侧栏、表格列、工具提示或详情抽屉。
• 如果操作文本换行，逐步缩写，或改用图标 + 工具提示。
• 如果网格中存在空白区域，先调整跨度、紧凑布局、宽高比或内容锚点，再添加更多内容。

---

步骤 3 - 实时检查 [自由度低 — 严格执行]

检查以下页面：

1440 x 900 desktop composition
1024 x 700 tablet / split-screen stress
800 x 700 narrow desktop / large mobile stress

针对每个视口，记录：

• 首要视觉焦点。
• 哪些地方显得拥挤。
• 哪些地方显得空旷或失衡。
• 哪些标签会换行或被截断。
• 滚动边缘是生硬截断，还是有柔和的提示。
• 悬停／聚焦状态是否说明了交互方式。
• 控制台／运行时错误。

进行眯眼测试：在脑海中模糊截图。页面仍应通过比例、对比度、分组和留白呈现主要区域。

然后执行四项子检查：

• 3a 两轮眯眼检查 — 层级（“我的视线首先被吸引到哪里？”）和类别（“仅凭颜色／形状能否区分相关条目？”）；A/B 层级的图块应模糊成不同色调，D 层级则应近乎统一。
• 3b DOM 统一性门槛检查 — 查询重复元素的矩形尺寸；在共享的 grid-cols-N 父元素下，宽度差异超过 1px 即表示包装器塌缩。应在包装器处修复。
• 3c 条件槽位零状态检查 — 为每个可选槽位填入最小但符合实际的内容进行渲染；保留的 min-h / aspect-ratio 下限就是一个空槽位。
• 3d 信息重复扫描 — 列出每屏出现多次的所有数据；只保留一个规范位置。 矩形尺寸脚本、包装器塌缩的成因和每屏扫描示例见：references/live-read.md §Step 3。

---

步骤 4 - 构图调整 [自由度高]

优先按以下顺序进行调整：

1. 删减：移除重复提示、重复标签、价值较低的图标、嘈杂的界面元素，以及“以防万一”添加的元数据。
2. 分组：利用邻近关系和共同区域，让相关元素读起来像一个整体。增大组间距，缩小组内间距。
3. 固定位置：将统计数据、代码元数据、时间戳或进度信息移至卡片页脚、侧边栏、底部区域、粘性摘要或列中。
4. 分阶段展示：仅在有帮助时，通过悬停、聚焦、标签页、折叠面板、抽屉、详情面板或“显示更多”来呈现次要内容。
5. 重新平衡：调整卡片跨度、网格密度、宽高比、顺序或对齐方式，为重要内容留出空间，并让留白显得合理。
6. 柔化：用渐隐、蒙版、滚动阴影、遮罩层、粘性渐变或适配视口边缘的样式替代生硬裁切。
7. 添加动画：仅在静态构图奏效后，再加入微交互。

---

隐藏故障模式（难以察觉的问题）

这些是“用户提到了，但你初次检查时没发现”的问题模式。当反馈模糊却强烈（如“笨重”“糟糕透顶”“浪费空间”“高度不协调”“感觉像 AI 生成”）时，先检查此列表，再调整装饰元素。每项都包含一个检测探针（应检查的内容）和一个修复方式（解决问题的最小改动）。适用于各种技术栈。

逐一检查 H1–H16 的检测探针和修复方式：H1 活跃状态的视觉体量不匹配、H2 根路由上的界面元素同义反复、H3 卡片套卡片的界面装饰、H4 品牌色相互争夺注意力、H5 库注入的内联宽度、H6 浪费空间／挤压内容的成对列、H7 仅悬停时才可见的交互提示、H8 内置于界面装饰中的点击区域、H9 过时的数据优先级、H10 缺少 aria-current、H11 相互冲突的动效、H12 为缺失内容预留空间的槽位、H13 包装器塌缩的图块、H14 每屏重复信息、H15 单色表面、H16 左侧锚定的堆叠布局。 完整目录、模式库、原语优先修补规则、动效和实现规则、计划模板及合理性检查见：references/details.md。

延伸阅读

• 扩展规则和步骤 3 子检查（眯眼检查、DOM 统一性、零状态、信息重复）
• 隐藏故障模式 H1–H16、模式库、原语优先修补规则、模板、合理性检查