# Viewer UX 设计依据

本指南记录了稳定的设计决策，这些决策此前分散在一次性的实现规格中。

## 导航顺序

键盘与触控导航必须遵循侧边栏展示的同一视觉顺序。

- 侧边栏的分组与排序定义了用户预期的导航顺序。
- `j/k` 与方向键导航应按 DOM 顺序在可见项间移动。
- 移动端上一条/下一条控件应与桌面键盘导航保持相同顺序。

## Mobile-First 约束

viewer 在窄屏下必须保持可用，且不能出现水平溢出。

- 移动端布局应优先一次只显示一个主 pane。
- detail view 的操作区需要触控友好的控件和清晰边界。
- diff 与内容密集视图在移动端应切换为堆叠布局。

## Diff 匹配语义

diff 质量取决于是否比较了相关 turn。

- 优先使用带历史感知的匹配（共享消息前缀或等价线程信号）。
- 如果 fallback 匹配是近似的，应在 UI 中明确给出警告。
- 允许手动选择目标，使用户可以覆盖自动匹配结果。

## 国际化

新增面向用户的 UI 文案必须保持一致的本地化策略。

- 所有字符串都要经过翻译层。
- 增加新 key 时保持 language pack 完整。

## 测试与范围纪律

viewer UX 相关工作应保持聚焦且可验证。

- 可行时优先在 `claude_tap/viewer.html` 中做受限改动。
- 在改进移动端 UX 的同时保持桌面行为稳定。
- 通过测试与手动 trace-viewer 验证来确认行为。
