# 界面配色设计（语义色规范）

> 立场：以 UI 设计师视角，为当前灰白 GUI 定义一套**语义色**规范。核心原则是"颜色编码含义、加速判断、降低误操作"，不是装饰。
> 基线：`app/gui.py` 现状——除顶部 Tab 栏（`TAB_STYLE`，GitHub 风浅灰/悬停浅蓝）外，任务状态、校验数字、登录状态、动作按钮均为 Qt 默认灰白。
> 性质：设计规范，不改代码。落地时按文末"实现映射"接入，遵守 `docs/05-coding-rules.md` 验证清单。

## 为什么上色（用户视角）

本工具是**带风险分级的流水线**（①②只读/安全 → ③写 Shopee 线上，高风险）。纯灰白本身不是缺点：中性界面对长时间操作不易疲劳、显得专业。所以目标不是"变好看"，而是让**承载判断的关键信息**用颜色加速识别、并对高风险动作形成潜意识提醒。

**反面**：给大面积表格/面板刷底色、堆品牌色、加渐变，会让密集工具界面变吵、变"玩具感"，是负分。因此本规范只给"承载含义的元素"上色。

## 三条纪律（决定成败）

1. **背景保持中性**：只给状态文字、关键按钮、指示点上色；不给表格行/面板大面积刷底色（失败行可用极浅底色，见下）。
2. **不能只靠颜色**：色盲用户约 8%。状态必须"颜色 + 文字/图标"双编码——现有状态已有中文文字（达标）；③ 高风险按钮第一版不强制图标，避免 Windows/Qt 字体渲染不稳。
3. **一套色板全局复用 + 对比度达标**：绿/红/琥珀/蓝各定唯一值，禁止每处手写不同的红；文字色对白底满足 WCAG AA（对比度 ≥ 4.5）。

## 语义色板（浅色主题）

| 语义 | 名称 | 十六进制 | 用途 | 白底对比 |
| --- | --- | --- | --- | --- |
| 成功 | success | `#1a7f37` | 已更新成功、已登录 | AA ✓ |
| 失败 | danger | `#cf222e` | 失败状态、校验错误数、破坏性按钮文字 | AA ✓ |
| 进行中 | info | `#0969da` | 采集中/生成中/更新中、安全主操作按钮 | AA ✓ |
| 待处理 | pending | `#9a6700` | 待采集/待生成/待更新 | AA ✓ |
| 略过/禁用 | muted | `#6e7781` | 略过、禁用态、次级文字 | AA ✓ |
| 危险动作强调 | warning | `#bc4c00` | ③ 写线上的高风险按钮 | AA ✓ |
| 极浅失败底 | danger-bg | `#ffebe9` | 失败行可选浅底（谨慎用） | 底色 |

> 若将来做深色主题，另出一套等义映射；本规范先服务当前浅色。

## 组件配色映射（按价值排序）

### 1）任务状态列（①②③表格核心）— 最高 ROI

`TaskTableModel` / `GenerateTaskTableModel` / `ApplyTaskTableModel` 的状态/阶段列，按值上前景色：

| 显示 | 语义色 |
| --- | --- |
| 已采集 / 已生成 / 已更新成功 | success `#1a7f37` |
| 失败 | danger `#cf222e` |
| 略过 | muted `#6e7781` |
| 待采集 / 待生成 | pending `#9a6700` |
| 采集中 / 生成中 / 更新中（如有进行态） | info `#0969da` |

- 收益：扫上百行时一眼分辨成功/失败/待办，是全项目颜色投入产出比最高处。
- 可选：失败行整行加 `danger-bg #ffebe9` 极浅底，但仅失败一种、不叠加其他行底色，避免花。

### 2）③ 高风险动作按钮

- `开始更新`（写 Shopee 线上，`objectName=startUpdateButton`，现仅粗体）：改用 **warning `#bc4c00`** 系（暖色描边或填充；图标可后置评估），与②安全流程的 info 蓝主操作明确区分。目的是每次点它都有"这一步动线上"的潜意识提醒。
- `停止`：保持中性或 muted，不与主操作抢视觉。

### 3）校验数字（①导入汇总栏）

- 未匹配数 **> 0** 时用 danger `#cf222e`，并保持当前「未匹配(n)」按钮可点击筛出；= 0 时保持中性。
- 无效行数 **> 0** 时同样用 danger 标红提示，但第一版不承诺在任务表筛出，因为脏行不会入库；若要点击查看，需要后续新增「导入错误明细」。匹配数可用 success 或保持中性。

### 4）登录状态点（④账号管理）

- `● 已登录` = success `#1a7f37`；`● 未登录 / 未检测` = muted `#6e7781` 或 danger（未登录用 danger 更醒目）。文字保留，圆点只是加速扫读。

### 5）③ Tab 危险区标识（克制）

- 给 ③ 更新shopee 加一个**克制**的暖色标识时，不依赖 QSS 硬选第 3 个 Tab。普通 `QTabBar` stylesheet 没有稳定的 nth-tab 选择器；优先用 `QTabWidget.setTabIcon(2, ...)` 设置 warning 小圆点图标，或第一版先跳过 Tab 标识。目的：让用户始终知道自己在"碰线上"的那个 Tab。切忌整条 Tab 刷红。

### 6）破坏性按钮（低优先）

- `删除批次`（①）、`删除账号`（④）等不可逆动作：按钮文字或描边用 danger `#cf222e`，与普通灰按钮区分。二次确认弹窗仍是主防线，颜色只是二级提示。

## 实现映射（PySide6，落地时参考）

- **状态色**：在各 TableModel 的 `data()` 里响应 `Qt.ForegroundRole`（必要时 `Qt.BackgroundRole`）按内部 `stage/status` 返回 `QColor`；不要按中文显示文案硬匹配，不要在 QSS 里做，表格单元格上色走 model role 最稳。
- **按钮/汇总数字**：用 `objectName` + 集中 QSS。建议把语义色板定义为 `app/gui.py` 顶部的一组常量（如 `COLOR_SUCCESS = "#1a7f37"`），QSS 与 `QColor` 都引用同一常量，杜绝散落硬编码。③ Tab 单独标识如需落地，用 `setTabIcon(2, ...)`，不要试图用 QSS nth 选择器。
- **登录点**：文字前缀 `●` 用 `QColor`，或状态列走 ForegroundRole。
- **复用**：所有红/绿/蓝/琥珀只从色板常量取值，新增组件一律引用，不新造颜色。

## 非目标（明确不做）

- 不做整体换肤 / 品牌主题 / 渐变 / 大面积彩色背景。
- 不给普通只读表格行刷底色（失败行浅底是唯一例外且可选）。
- 不改变顶部 Tab 栏既有的防误点尺寸与灰白基调；③ 风险标识必须克制，且可在第一版跳过。
- 不引入第三方 QSS 主题库；用现有 `TAB_STYLE` + objectName + model role 即可。

## 落地建议顺序

1. 状态列上色（映射 1）——收益最高、风险最低，建议先做。
2. ③ 高风险按钮 + 校验数字标红（映射 2、3）——直接服务防误操作与导入纠错；无效行第一版只标红，不做筛表。
3. 登录点、③ Tab 标识、破坏性按钮（映射 4、5、6）——体验打磨。

> 每步落任务时补现状/方案/验收，并跑 `python -m unittest discover -s tests`（GUI 逻辑测试）确认无回归。