chengma/cmshoppe
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
5469479f3e08615dee2916f9cb10f351229a63c8
cmshoppe/docs/ui-color-design.md
T

9.3 KiB
Raw Blame History

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

立场：以 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；● 未登录 / 检测失败 = danger #cf222e；● 未检测 / 已启动 / 检测中 = muted #6e7781 或 info #0969da。落地时优先在④账号表登录状态单元格显示 ● 状态文本，并通过 QTableWidgetItem.setForeground(QColor(...)) 上色，保留文字，不只靠颜色。

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

  • 给 ③ 更新shopee 加一个克制的暖色标识时，不依赖 QSS 硬选第 3 个 Tab。普通 QTabBar stylesheet 没有稳定的 nth-tab 选择器；本轮 T-513 采用 QTabWidget.setTabIcon(2, ...) 设置 10-12px warning 小圆点图标，Tab 文案仍保持 ③ 更新shopee，不改文字色、不整条刷红。目的：让用户始终知道自己在"碰线上"的那个 Tab。

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

  • 删除批次（①）、删除账号（④）等不可逆动作：按钮文字和描边用 danger #cf222e，与普通灰按钮区分；保持原有启用/禁用和二次确认逻辑不变。二次确认弹窗仍是主防线，颜色只是二级提示。

7）状态栏全局提示色（T-543 已落地）

左下角状态栏是低打扰反馈，不应做成醒目的大色块。建议只改变状态栏文字颜色，并在每次显示普通提示时重置样式，避免上一条红色/绿色残留到下一条普通消息。

提示类型 语义色 示例
普通/就绪 muted #6e7781 或系统默认 就绪、当前：② AI生成
信息/进行中 info #0969da 正在生成标题 3/10、检测登录中
成功 success #1a7f37 设置已保存、AI 生成完成、已回写 Excel
警告/需用户处理 warning #bc4c00 或 pending #9a6700 当前筛选结果没有待生成任务、请先到①完成旧数据采集、请先配置 cmhub
错误/阻断 danger #cf222e 更新失败、账号未登录、点数不足
  • 状态栏只做辅助反馈，不能替代弹窗、空状态、运行日志和按钮禁用等主反馈。
  • 高频进度信息用 info；不会继续执行、但用户可通过配置/选择修复的问题用 warning；已经失败或阻断当前动作的问题用 danger。
  • 不建议给所有状态栏消息都上强颜色；普通导航、就绪、筛选数量等信息保持 muted 或默认色，避免长期使用时视觉疲劳。
  • T-543 已统一使用 MainWindow.show_status(message, level)；新增状态栏提示必须显式传入 level，现有旧回调保留轻量兜底分类以兼容测试和旧入口。
  • T-543 第一版已覆盖主窗口和 ①②③④⑤ Tab 现有状态栏调用；状态栏只作为辅助反馈，不改变弹窗、空状态、运行日志、任务状态列或按钮禁用的主反馈职责。

实现映射（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。
  • 状态栏：T-543 已在 MainWindow 增加统一入口 show_status(message, level="muted")，内部映射 level 到色板、设置状态栏文字色并调用 statusBar().showMessage(message)；普通/就绪提示会重置为 muted，避免上一条 danger/success 残留。现有 self.statusBar().showMessage(...) 已收口到该入口；传给 Tab 的 status_callback 也改为 show_status。第一版为兼容旧测试和旧入口保留轻量关键词兜底分类（失败/错误/异常/点数不足/未登录→danger，完成/成功/已保存/已回写→success，没有/请先/未配置→warning，正在/开始/进度/检测中→info），但新增代码必须显式传 level，不要长期依赖中文字符串匹配。
  • 复用：所有红/绿/蓝/琥珀只从色板常量取值，新增组件一律引用，不新造颜色。

非目标（明确不做）

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

落地建议顺序

  1. 状态列上色（映射 1）——收益最高、风险最低，建议先做。
  2. ③ 高风险按钮 + 校验数字标红（映射 2、3）——直接服务防误操作与导入纠错；无效行第一版只标红，不做筛表。
  3. 登录点、③ Tab 标识、破坏性按钮（映射 4、5、6）——体验打磨。
  4. 状态栏提示色（映射 7）——低风险体验增强，适合在现有语义色稳定后作为小任务落地。

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

Reference in New Issue View Git Blame Copy Permalink