# tty7 界面设计规范

本规范约束应用界面，不重写 shell、TUI、代码语法的颜色。实现入口是
`src/ui/presets.rs` 的 `Neutrals`、`Interactions`、`Semantics`，以及
`src/ui/theme.rs` 的组件映射。组件应引用这些角色，不在页面里另配颜色。

## 信息优先级

1. **工作内容**：终端、正在编辑的文档、正在查看的 diff。主区域最大，正文对比度最高。
2. **当前位置与下一步**：当前工作区/标签页、键盘当前选项、可执行的主操作。
3. **辅助导航**：右侧信息/Git/文件页签、展开收起、新建、更多。中性图标，始终可见。
4. **说明与元数据**：路径、分支、数量、快捷键、设置描述。次级文字，不用饱和色抢正文。
5. **异常**：失败、冲突、需要处理的警告。局部状态色，加文字或形状，不单靠颜色。

同屏不能把所有选中项都画成主按钮。工作区使用淡强调色；右侧面板当前页签使用中性底；
真正可执行的主按钮才使用实色强调色。每个任务区只突出一个主操作。

## 颜色角色

| 角色 | 使用位置 | 规则 |
| --- | --- | --- |
| `Neutrals.background` | 工作内容、设置内容、输入框 | 安静的基础表面。输入框未聚焦时不能像已选中列表行 |
| `Neutrals.sidebar` | 两侧导航 | 与内容轻微分层；用细分隔线补充边界 |
| `Neutrals.popover` | 菜单、命令面板、对话框 | 浅色下保持明亮，深色下抬高亮度；只给浮层阴影 |
| `foreground` | 正文、标题、当前项 | 正常文字至少 4.5:1；不把普通正文全部加粗 |
| `muted_foreground` | 描述、路径、快捷键 | 与主文字明确区分，但仍保持可读性 |
| `border` / `divider` | 控件边界 / 区域分隔 | 控件边界较强，区域分隔较弱；不能把页面画成表格线框 |
| `Interactions.input_border` | 输入框与普通按钮轮廓 | 对应组件库的 `input` 边框角色，不能误用内容背景色导致边界消失 |
| `Interactions.primary` | 保存、连接、有效的提交等主操作 | 强调色实底，成对配置前景色；hover/pressed 保持标签对比度 |
| `Interactions.navigation` | 当前标签页、设置导航 | 低饱和淡色底 + 清晰文字；不使用主按钮实色 |
| `Interactions.choice` | 菜单、命令面板的键盘当前行 | 强调色浅底，区别于鼠标经过的中性 hover |
| 中性 `secondary` | 面板页签、分段选项、普通按钮 | 次级导航不能与主要操作争夺注意力 |
| `Semantics.danger` | 失败、Git 冲突、破坏性动作 | 红；必须同时有文字/图标/确认语义 |
| `Semantics.warning` | 需要留意的状态 | 琥珀；Git 普通修改只用于尾部标记，不能染黄整个文件树 |
| `Semantics.success` | 成功、Git 新增标记 | 绿；不用于装饰性按钮 |
| `Semantics.info/link` | 信息、可点击链接 | 使用当前主题的强调色，与焦点指示同族 |

默认浅色以白/浅灰为底，蓝色 `#007AFF` 为强调色。
默认深色以 `#191B20` 为内容底，`#E2E5EB` 为正文，`#78A8F5` 为强调色。
其他主题保留自己的背景与强调色，但红/绿/琥珀的**状态含义**不随 ANSI 槽位变化。
所有文字、状态色和主按钮前景色须在实际背景上验证对比度。

## 状态不能混用

- Rest：中性、稳定。工具按钮不因鼠标移出而消失。
- Hover：轻微中性填充，只用于可交互目标。设置说明行不整体发亮。
- Selected：表达持久的当前位置。工作区用淡强调色，辅助页签用中性底。
- Keyboard focus：清晰的强调色焦点环/当前行，不能仅靠 hover 表达。
- Pressed：同一色系的短暂加深，不能跳到另一个主题色。
- Disabled：保留边界与标签；降低对比，不能像可执行的主按钮。
- Error：状态色、说明和恢复入口一起出现。普通 Git 修改不升级为错误/警报。

标签页关闭按钮、渐变遮挡等局部覆盖层必须使用所在行的**实际**背景，不能复用过期色值。

## 图标、文字与间距

- 界面 SVG 使用 24×24 坐标系、1.8 线宽、圆端点；工具栏按 16px 显示，命中区 32px。
- 行内辅助按钮至少保留现有 24px 命中区域；增大图标不能挤掉文本预算。
- 工具图标使用中性文字色。品牌用小图形识别，饱和色留给状态点。
- 字号跟随界面缩放；正文 14/16rem，说明 12/16rem，章节标题 16/16rem。
- 选中名称用 medium，章节标题用 semibold；正文和辅助说明保持 regular。
- 以 4px 为间距基础：紧密内容 4–8，行内 8–12，区块 24–32。列表外边距与文字预算同步。
- 控件和列表行圆角 6–8px；浮层 12px。除头像/状态点外，避免胶囊泛滥。

## 各界面约束

- **侧栏**：名称优先于分支和 diff 数量；当前项清晰，品牌头像不形成彩色墙。
- **侧栏顶部**：导航与内容用留白衔接，不加贯穿的 header 底部分隔线；左右侧栏保持连续表面。
- **右侧文字层级**：文件树名称使用侧栏标题色，不能整体降为辅助灰；当前项使用 selected 文字色与 medium 字重，根目录以字重区分。Git 普通文件名使用 resting 文字色与界面字体，路径、数量与说明保持次级；信息页的路径前缀弱化，末级名称突出。
- **文件树**：文件名中性；A/M/? 等尾部字符承载 Git 状态；目录用小点表示子项变化；冲突才整行提升。
- **Git 面板**：改动列表是主体。可执行的提交按钮才突出；未填写信息或不可提交时保持次级。
- **设置**：章节标题 > 标签 > 描述；开关/滑块/主操作共享强调色；分隔线弱于控件边界。
- **菜单与命令面板**：亮度抬升、有限阴影；当前键盘行清楚，普通项不着色；小窗口内可滚动。
- **终端**：ANSI 是用户内容，不拿来充当 UI 错误/成功配色；应用设计调整不得反转状态含义。

## 验证要求

`cargo test -p tty7 --bin tty7-app --locked ui::` 覆盖内置主题的文字、语义色、
交互状态对比度及已有 UI 行为。另需在真实窗口检查浅色/深色、宽/窄窗口、侧栏、文件、
Git、设置、菜单与命令面板。测试通过不能替代视觉层级检查。