orisys-app/apps/studio/docs/ui-palette.md

Orisys Studio 配色规范

本文件记录客户端的品牌配色体系、它与 UI 设计稿的关系，以及每一处有意偏离设计稿 的理由。所有色值都存放在主题令牌文件里，控件代码中不允许出现十六进制颜色：

orisys-app/shared/src/orisys_app_shared/theme/colors_dark.json
orisys-app/shared/src/orisys_app_shared/theme/colors_light.json

规则由 apps/studio/tools/ui_check.py 的 audit_palette() 机械校验，pytest 套件 （tests/test_ui_smoke.py::test_palette_rules_hold）复用它，因此只有一个真值来源。

---

1. 设计稿色号 → 令牌映射

设计稿	角色	落地令牌
#003893	品牌主色 / 底图色	accent、plot_fn（浅色）；arrow_canvas 使用了更深的 logo 藏青
#4D62BE	交互蓝	accent_hover（浅色）、accent（深色）、focus_ring（浅色）
#12315D	logo 实际藏青（见 §3.1）	brand_bar_bg、arrow_canvas（浅色）
#FA02F3	洋红	flow_ramp 第 3 档（原值保留）
#FE5853	珊瑚	flow_ramp 第 4 档（提亮为 #FF8A6B，见 §3.2）；danger 家族取自同一色相
#D8FF00	柠檬绿	flow_ramp 第 5 档（原值保留）、plot_fy（深色）
#D5D5D5	应用画布	未采用，改为 #E1E6EF（见 §3.3）

1.1 三轴分类色（蓝 / 橙 / 绿）

界面改版把三个力通道统一成"蓝 = 法向、橙 = 切向 X、绿 = 切向 Y"。它们是 分类色（三条曲线各自一个身份），与 §4 的箭头色带（顺序色带）是两件事，因此落在 plot_fn / plot_fx / plot_fy 三个令牌上。这三个令牌同时被实时曲线、录制回放、 标定面板与标定点详情对话框引用，换值即全局统一。

主题	plot_fn（法向，蓝）	plot_fx（切向 X，橙）	plot_fy（切向 Y，绿）
深色	#6FA8FF	#FF9A4D	#7CE0A0
浅色	#003893（品牌藏青，见 §3.1）	#B45309	#2E7D32

浅色主题的 FN 保持品牌藏青 #003893（与 accent 同值），这样品牌蓝在三轴里仍是 "主通道"；橙色与绿色在浅底上取深色相，才够对比度。深色主题的霓虹洋红/柠檬绿被替换， 原因是它们是色带用色：作为分类色时洋红与橙的色相差偏小，而柠檬绿在浅底上不可用 （§2.1）。替换后三个通道在灰度打印下也靠亮度分开，不再依赖单一色相。

---

2. 实测对比度（WCAG）

对比度用标准相对亮度公式实算（tools/ui_check.py 中的 contrast_ratio）。 正文门槛 4.5:1，图形/控件/状态指示门槛 3.0:1。

2.1 设计稿本身的实测结果

组合	比值	判定
白字 on #003893	10.57	AAA ✅
白字 on #4D62BE	5.52	AA ✅
#4D62BE on #D5D5D5	3.76	图形达标，12–13px 文字不达标 ⚠️
#D5D5D5 vs 白卡	1.47	卡片层次偏弱 ⚠️
#D8FF00 on #D5D5D5	1.27	不可用 ❌
#D8FF00 on #003893	9.17	极佳 ✅
#FA02F3 on #003893	3.20	达标 ✅
#FE5853 on #003893	3.39	达标 ✅
#FA02F3 vs #FE5853	1.06	色带中段的亮度平台 ❌
白字 on #FE5853	3.12	珊瑚色不能承载白字 ❌

设计稿的色相选择是可靠的；三个霓虹色的相对亮度为 0.268 → 0.287 → 0.861， 色相沿 302° → 2° → 69° 单调前进 127°，作为"位移幅值 → 颜色"的顺序色带是正确用法。 问题在于中段：洋红与珊瑚亮度几乎相同（1.06:1），只靠 60° 色相差区分，在灰度 打印与色觉障碍下会糊成一片。

2.2 落地后

浅色主题（节选）：白字 on accent 10.57，白字 on accent_hover 5.52， plot_fn/fx/fy 对 plot_bg 分别 10.11 / 4.80 / 4.90， brand_bar_fg on brand_bar_bg 12.94，input_border 对四种底均 ≥3.08。

深色主题（节选）：白字 on accent 5.52，accent 对 panel_bg 3.09（贴线但仍达标）， plot_fn/fx/fy 对 plot_bg 分别 7.53 / 8.62 / 11.25，focus_ring 对 input_bg 6.51。

语义色（danger / warning / success / status_*）额外对 toolbar_bg 审计：它们会 出现在顶栏状态行上（记录状态、数据有效性、阶段指示），实测浅色 4.65–6.66、深色 5.60–9.13， 全部 ≥4.5。在这一步之前它们只在 panel_bg / card_bg 上被检查，顶栏是一个未经审计的底色。

三通道可分辨性（色相差 / 相对亮度比）：

主题	FN vs FX	FN vs FY	FX vs FY
浅色	168.8° / 2.10	94.1° / 2.06	97.1° / 1.02
深色	169.7° / 1.14	74.7° / 1.49	115.6° / 1.31

规则是"色相差 ≥90° 或 相对亮度比 ≥1.2"，两主题均满足（深色 FN vs FY 靠 1.49 的亮度比 过关，浅色 FX vs FY 靠 97.1° 的色相差过关）。颜色在任何情况下都不是唯一编码：每个曲线有 文字标签，每张数值卡有同色通道徽标与通道名。

---

3. 对设计稿的四处有意偏离

3.1 品牌藏青用 logo 实际取色 #12315D

logo.png 与 logo_topbar.png 采样后字形的实际颜色都是 #12315D （H215 S80.6% V36.5%），而设计稿写的是 #003893（H217 但 S100% V57.6%）。 两者同色相家族，但后者明显更亮更艳。顶栏品牌条与浅色主题的箭头画布采用 logo 实际色，以保证"标识色"与"界面色"一致。

3.2 色带第 4 档由 #FE5853 提亮为 #FF8A6B

见 §2.1：保留设计稿珊瑚色会在色带中段留下 1.06:1 的亮度平台。提亮后色带相对亮度 为 0.031 → 0.128 → 0.268 → 0.405 → 0.861，严格单调。 第 3 档洋红与第 5 档柠檬绿保留设计稿原值不动。

3.3 画布 #D5D5D5 → #E1E6EF

#D5D5D5 是无彩色（H=0 S=0% L=84%）。现代浅色画布普遍在 96–98% 亮度，目的是让 白卡"浮起来"；而在 #D5D5D5 上白卡只有 1.47:1，且 Qt 的 QSS 不支持 box-shadow， 卡片只能靠 1px 描边分离，观感会发平、发旧。改为品牌微蓝灰后：

• 保留设计稿"灰底 + 白卡"的角色分工；
• #4D62BE 在画布上的对比度从 3.76 升到 4.41。

3.4 补齐语义色与深色主题

设计稿没有 success/warning/error/info，也只有浅色版；本应用默认主题是深色。 同时原深色主题的语义色是一整套 Google Material 色 （#8ab4f8 / #34a853 / #fbbc04 / #ea4335 / #1a73e8），对一个测量仪器 产品属于即时可识别的品牌冲突，已全部替换为品牌衍生色。

danger 在深色主题被拆成两个令牌：danger（亮，用于卡片上的红字与状态指示） 与 danger_fill（暗，用于承载白字的危险按钮）—— 一个色值无法同时满足两个方向。

---

4. 品牌化箭头色带

设计稿的霓虹三色是一张 colormap（按位移幅值着色），不是三个分类色。因此它落在 箭头可视化上，而不是 UI 控件上：

flow_ramp = 画布色, #6E4AD0, #FA02F3, #FF8A6B, #D8FF00

• 第 1 档等于画布色，这样零位移区域自然融入背景；
• 由 orisys_app_shared.acquisition.arrows.flow_colormap(theme) 生成 256 档 BGR 查找表，经 draw_arrows(colormap=...) 注入 SDK（SDK 无需改动）；
• LUT 缓存的键是 ramp 字符串本身，因此切换主题后立刻生效；
• 非法 ramp 永不抛异常，回退到内置默认色带。

箭头画布在两个主题里都是品牌深蓝（浅 #12315D / 深 #0B1830），这也是霓虹色带 唯一可用的背景 —— 色带第 3 档起对画布均 ≥3.0:1。绘图区（plot_bg）保持浅色， 所以浅色主题下霓虹只出现在箭头画布上，力曲线使用浅色安全的品牌三色。

---

5. 有记录在案的豁免

以下项目不被 audit_palette() 检查，理由是它们属于装饰而非状态指示：

项	现状	理由
装饰性 1px 容器描边	card_border / panel_border / plot_grid / separator（1.16–1.45:1）	WCAG 1.4.11 针对交互控件的边界与状态指示；容器轮廓属于装饰
禁用态文字	深色 text_muted on button_bg = 4.07	WCAG 1.4.3 明确豁免禁用控件

输入框的静止描边不在豁免之列 —— 它被强制要求对 input_bg/panel_bg/card_bg/toolbar_bg 四种底均 ≥3.0:1（实测 3.08–4.09），这与 Material 3 描边式输入框的做法一致。焦点态同样由 focus_ring 保证 ≥3.0:1。

深色主题的 accent 对 panel_bg 为 3.09:1（设计稿原值 #4D62BE），贴线但达标； 若后续视觉上偏软，可单点提升为 #5468C6（白字仍为 5.03）。

---

6. 顶栏：一件仪器只有一条读数线

顶部由两条细轨组成，合计在 1440×880 下不超过 78 px（ui_check.py 的 top area 段与 tests/test_ui_smoke.py::test_top_area_stays_compact 都断言这一点）：

轨	高度	承载
品牌轨（QFrame#brandBar）	28 px	logo + 字标 + 三个顶层视图（实时监测 / 历史回放 / 标定）+ 右侧产品名
状态轨（ToolbarWidget 的 rail）	~30 px	传感器摘要按钮、阶段、当前视图的来源选择（摄像机编号 + 搜索 / 使用摄像机）、标定状态、数据有效性、记录状态、记录/运行/重置/设置
设置区（默认收起）	0 / ~40 px	单位、记录模式、预览
回放条（已取消）	0 px	回放视图与实时同布局：运输控制就是状态轨的主按钮（实时=运行，回放=回放/暂停）

四点规则：

1. 传感器区是一个摘要按钮，不是两个下拉。轨上只有 BOX · box/sensor.json；类型、配置 与「当前生效的标定 / 最近导出的系数」都在它打开的 SensorDialog 里（见 docs/shell-lifecycle.md §1.2）。摘要按钮属于状态轨，因此文本必须完整显示（见第 5 条）。

2. 来源选择随视图：实时视图显示摄像机编号 + 搜索；回放视图显示「选择录制视频…」，视频名 写在来源摘要里（只在回放视图）。没有「来源」下拉，因此没有"先选来源才能用"的状态。

3. 导航按钮在品牌底上取品牌前景色。navButton 用 brand_bar_fg_muted，当前视图用 brand_bar_fg + navActive="true"；两者都在 §2 的品牌底对比度审计里（7.67 / 12.94）， 不新增色值。

4. 状态轨上的语义色一律算在 toolbar_bg 上审计。记录状态（status_idle / status_running / status_connecting / status_error）、丢帧提示（warning）与数据 有效性（success / warning）此前只检查 panel_bg，而它们实际画在顶栏底色上。

5. 同一时刻只有一个实心按钮（ToolbarWidget._refresh_emphasis）：

   状态	实心	描边
   空闲	运行（primaryButton）	—
   连接中	取消连接（dangerButton）	—
   采集中	开始记录（primaryButton）	停止（dangerOutline）
   记录中	停止记录（dangerButton）	停止（dangerOutline）

   dangerOutline：透明底 + danger 文字与描边，hover/pressed 才填充 danger_fill； :checked（即"采集正在跑"）仍保持描边——否则一圈红边会在会话开始后悄悄变成整块红色。

6. 状态轨上的事实不得被压缩（ui_check.rail_squeezed）。中文、英文、1280 与 1440 四种组合下，轨上的按钮与下拉都必须显示完整文本；只有带 tooltip 的 ShrinkableLabel 允许在窗口极窄时被裁切。这也是"记录模式"下拉被挪进设置区的原因：英文的 Start recording + Sensor config 与它挤在同一行时，第一个被压缩的就是按钮文字。

7. 曲线表头只有符号，符号的颜色仍来自令牌。全程总览 / 框选 / 返回最新三个按钮是 纯图标（QPushButton[iconOnly="true"]），图标由 ui/icons.py 用 text_secondary 实时绘制、切主题时按新令牌重画，因此配色审计的结论对它们同样成立，也不需要新增色值。 单位芯片 QPushButton#unitBadge 用 card_bg 底 + card_border 描边 + text_secondary 文字，hover 才换成 text_primary 文字与 accent 描边，它是"可点的状态"而不是实心主 按钮，所以不参与 §6.5 的"同一时刻只有一个实心按钮"计数（QLabel#unitBadge 仍是通道 徽标与传感器缩略图的样式，两者靠控件类型区分）。

8. 数值卡的小字用等宽体，且不会把面板顶宽。选区统计（均值 · σ）画在数值卡内的 9pt 等宽小字上，与 16pt 的大号数字同一列；底部状态栏不再出现长句，因此曲线面板的宽度由 三个数值卡决定，而不是由一行统计文字决定。ui_check.py 的 session browsing 段断言 该小字 width() >= sizeHint().width()（中文与英文都不裁切）。

9. 两个视图共用一条状态轨：来源槽是唯一的差别（实时=摄像机、回放=「选择录制视频…」）， 因此轨上的文字宽度预算对两个视图是同一个。回放的视频名写在来源摘要里，只在回放视图 （_refresh_status_rail 按 _view_preset 决定），中英与 1280/1440 都由 ui_check.rail_squeezed 覆盖。

---

7. 三个顶层视图 = 同一窗口的三套布局

导航不再打开对话框，而是切换主窗口的布局（ViewLayoutController.apply_preset）：

视图	面板	曲线模式	分割比例（3D, 2D, 曲线, 标定）
实时监测	2D 图像 + 力曲线（+ 手指三维）	跟随实时	620, 300, 520, 0
历史回放	2D 图像 + 力曲线	读打开的录制（全程浏览）	620, 300, 520, 0（与实时相同）
标定	标定面板 + 力曲线	不变	0, 0, 560, 880
自由（custom，启动默认）	由视图菜单决定	不变	用户在分割条上摆的位置

• 标定视图给标定面板 880 px：六列诊断表头与九个动作按钮不再被挤压；标定面板自身还有 纵向滚动区，窗口再矮也够得到「应用到设备」。
• 标定面板列宽改为 ResizeToContents：诊断列头宁可让表格横向滚动，也不截成 「FN 均」这种看不懂的缩写。
• 2D 图像区域固定为所显示图像的宽高比（AspectImageLabel）。横向分割器不会向子控件 询问 heightForWidth，所以宽高比由 ArrowPanel.resizeEvent 主动施加；box 传感器的 画面旋转 90° 显示，因此其显示宽高比是 9:16 而不是 16:9。
• 视图 → 标定面板 与「标定」导航是同一个开关：勾上进入标定视图，取消回到实时视图， 不会留下"面板已隐藏但导航还亮着"的矛盾状态。

---

8. 复核方式

$py = "D:\orisys_ws\orisys-app\.venv-build\Scripts\python.exe"
$env:PYTHONPATH = "D:\orisys_ws\orisys-app\shared\src;D:\orisys_ws\orisys-app\apps\studio\src"
cd D:\orisys_ws\orisys-app\apps\studio

& $py tools/ui_check.py                                   # 含 palette 规则段落
& $py tools/ui_snapshot.py --theme dark  --lang zh_CN --demo --out outputs/_snap_dark.png
& $py tools/ui_snapshot.py --theme light --lang en_US --sensor finger --panels cal,3d --size 1600x900 --demo --out outputs/_snap_light.png
& $py tools/ui_snapshot.py --theme dark  --lang zh_CN --demo --scene recording --out outputs/_snap_recording.png
& $py tools/ui_snapshot.py --theme dark  --lang zh_CN --demo --preset calibration --out outputs/_snap_calibration.png

视图切换与关闭流程另见 apps/studio/docs/shell-lifecycle.md。