ui-fidelity-playbook v1.0.3A

Immutable. This exact content never changes and is served at /api/v1/blob/95b17c2eb37a212d.

---
name: ui-fidelity-playbook
description: 按设计意图（设计稿/截图/线框/明确视觉参考）高保真实现 UI 的方法论。指导如何先探索项目约束、先对齐结构与交互再打磨细节、避免常见失真、提交前自验。适用"UI 还原""按设计稿还原""高保真对齐""还原度不够""交互与视觉对齐"等场景。
metadata:
  author: "devkeel"
  version: "1.0.3"
---

# UI Fidelity Playbook

当已有可参考的设计意图（设计稿/截图/线框/明确视觉参考）时，使用本 skill。

这个 skill 不是替代设计工具或设计获取流程，而是补充"如何更早把实现做对"的方法论。它既指导编码，也指导提交前自验，但不是事后 code review 流程。

## 何时使用

适用于以下场景：

- 参考设计意图（设计稿/截图/线框/明确视觉参考）实现页面、区块、组件或弹窗
- 需要高保真还原，而不是"差不多"
- 需要同时对齐视觉和交互
- 页面已经有实现，但还原度不足
- 用户反馈"和设计稿不一致""交互没对齐""布局节奏不对"

常见触发语句包括：

- "参考设计稿实现"
- "按设计稿还原"
- "高保真对齐"
- "交互也要按设计稿"
- "这个页面还原度不够"

## 何时不使用

以下场景不要使用本 skill：

- 完全没有设计事实（无设计稿/截图/线框/明确视觉参考，仅有口头需求）——这属于创造设计而非还原实现；如已安装设计类 skill（如 `ui-ux-pro-max` 等），可先用其产出设计意图，再回到本 skill 做高保真实现
- 任务主要是业务逻辑或接口联调
- 用户要的是纯 code review
- 用户要的是开放式设计讨论，而不是实现对齐

## 设计事实来源

无论设计意图来自 Figma、Sketch、截图、线框还是口头描述加草图，使用本 skill 前至少明确三件事：

1. 本轮参考的是什么来源
2. 已拿到哪些事实——结构/截图/资源/状态变体
3. 还缺什么

来源不同只是填这个契约的方式不同，方法论本身来源无关。不要在只有口头描述、没有任何可对照事实时直接套用本 skill——那属于创造设计，先产出设计意图再回来。

### 来源为 Figma 时的最佳实践

当来源是 Figma 时，用其 MCP 可拿到结构化程度最高的事实，效果最佳。推荐顺序：

1. 确认目标节点或页面
2. 获取 `get_design_context`
3. 获取 `get_screenshot`
4. 必要时获取子节点上下文和设计资源
5. 使用本 skill 指导实现、收敛与自验

来源不是 Figma 时，按上方最小契约自行获取可对照的视觉事实（截图/线框/资源等）。

## 编码前必须探索的内容

如果任务涉及任何项目相关约束，必须先探索当前仓库，而不是假设。

重点探索：

- 当前作用域 `AGENTS.md`
- 相关 `.harness/rules/`
- 路由入口与页面挂载方式
- 页面布局 ownership
- 宿主容器（host container）或上层壳子结构
- 设计系统、共享组件、样式约束
- 图片与资产规范
- 测试与运行时验证路径

如果设计图里包含外围导航、窗口壳子、外层容器、标签栏或其它页面外 chrome，必须先判断它是不是当前页面的一部分，再决定落点。

## 高保真实现流程

### 1. 明确范围

先确认本轮到底实现什么：

- 整页
- 页面中的一个区块
- 弹窗或抽屉
- 一个可复用组件
- 宿主容器中的内容区
- 一个或多个状态变体

不要默认整张截图都属于当前实现范围。

### 2. 识别运行时层次

把目标拆成运行时层次，而不是只按视觉看：

- 宿主层
- 页面布局层
- 组件层
- 浮层或条件层
- 状态层

如果边界不清楚，先查代码结构和运行容器，不直接改样式。

### 3. 识别高风险失真点

优先关注最容易做歪的地方：

- 容器尺寸和定位
- 间距节奏
- 对齐关系
- 背景与覆盖层
- 图标与图片资产
- 字体层级
- 滚动、裁切、sticky 行为
- 交互切换与状态跳转

### 4. 先做结构，再做细节

先把这些做对：

- 区域归属
- 布局模型
- 宽高关系
- 持久区域和条件区域
- 溢出行为

结构错了，后续像素微调通常会返工。

### 5. 分轮次收敛 fidelity

推荐顺序：

1. 结构
2. 尺寸与间距
3. 字体层级
4. 表面样式：背景、边框、圆角、阴影
5. 资源替换
6. 交互路径
7. 状态切换
8. 运行时容器下的最终表现

### 6. 提交前先自验

至少对照两类对象：

- 设计事实（设计稿/截图等）与设计上下文
- 真实运行容器中的最终页面

当容器关系重要时，不要只看孤立组件渲染效果。

## 不可妥协的约束

- 架构、层次、宿主容器不清楚时，必须先探索仓库。
- 不要默认整张截图都要由当前页面实现。
- 不要在没确认 ownership 前复制外围壳子 UI。
- 不要只做静态默认态；关键交互和状态也必须对齐。
- 不要只凭肉眼接近就声称"已按设计意图对齐"。

## References

- 详细流程：`references/workflow.md`
- 常见失真点：`references/traps.md`
- 提交前自验：`references/checklist.md`