Geopro 3.0 桌面客户端 — 视觉设计规范（Design System）
版本 v1.0 · 适用范围：Geopro 3.0 桌面客户端全部界面
技术载体：Qt 6（QtWidgets）+ Fusion QStyle + QSS + QPalette + QtAwesome + VTK
模式：Light（依据原型还原）/ Dark（同一设计语言派生）
本规范是客户端视觉的单一事实来源。Claude Code 在实现任何界面时，颜色、间距、字号、圆角、控件尺寸、状态表达一律引用本文档的 token，禁止在各 widget 中即兴硬编色值。所有 token 应集中定义在一个主题模块（见 §13），全局通过主题对象访问。
0. 设计原则
- 数据为主，UI 退后：中间的 2D/3D 视图与剖面图是视觉焦点，外围面板（树、列表、属性）使用克制的中性色，不与数据争夺注意力。
- 浅色为默认，深色为派生：原型为浅色界面，Light 为基准模式；Dark 按相同色相、相同层级关系派生，保证两套是「同一语言的明暗版本」。
- 信息密度优先：勘探软件信息密集，控件紧凑、间距节制、对齐严谨，而非消费级 App 的宽松留白。
- 强调色克制：主强调色（科技蓝）只用于可交互的主操作、选中态、链接、聚焦；状态色只用于状态表达，不作装饰。
- 视图区永远深色：无论 Light/Dark 模式，中间的 2D 地图 / 3D 视图 / 剖面图画布始终是深色衬底（原型即如此），让色阶数据更突出。这意味着「模式切换」主要影响外围 UI，视图画布的深色基调保持稳定。
- 双模式同构：同一组件在两种模式下结构、间距、字号完全一致，仅颜色 token 取值不同。
1. 色彩系统（Color Tokens）
色彩采用语义化分层：原始色板（Primitives）→ 语义 token（Semantic）。组件只引用语义 token，不直接引用原始色板，便于换肤。
1.1 原始色板 · 主强调色（Brand / Primary）
科技蓝，取自原型导航高亮、主按钮、链接、选中态。
| Token |
色值 |
用途 |
--primary-50 |
#EFF5FF |
最浅，选中行背景、hover 底 |
--primary-100 |
#DBE8FE |
浅强调背景 |
--primary-200 |
#BFD4FD |
|
--primary-300 |
#93B4FA |
|
--primary-400 |
#5E8DF5 |
|
--primary-500 |
#3B73EC |
主强调色（Light 主按钮、链接） |
--primary-600 |
#2B5FD9 |
主按钮 hover |
--primary-700 |
#2450B8 |
主按钮 pressed |
--primary-800 |
#21478F |
|
--primary-900 |
#1B3A6E |
|
Dark 模式主强调略微提亮以保证深底对比度：Dark 主强调用 --primary-400 (#5E8DF5)，hover 用 --primary-300。
1.2 原始色板 · 中性灰阶（Neutral）
界面骨架色，决定整体气质。
| Token |
色值 |
说明 |
--neutral-0 |
#FFFFFF |
纯白 |
--neutral-25 |
#FCFCFD |
面板底 |
--neutral-50 |
#F7F8FA |
应用背景（Light 工作区底） |
--neutral-100 |
#EFF1F4 |
次级背景、表头底、斑马纹 |
--neutral-200 |
#E3E6EB |
边框、分隔线 |
--neutral-300 |
#CDD2DA |
输入框边框、禁用边框 |
--neutral-400 |
#A8AFBC |
占位文字、禁用文字 |
--neutral-500 |
#7C8493 |
次要文字、图标默认 |
--neutral-600 |
#5A626F |
正文次级 |
--neutral-700 |
#3E4551 |
正文 |
--neutral-800 |
#272C35 |
标题文字 |
--neutral-900 |
#161A20 |
最深文字、Dark 面板底 |
--neutral-950 |
#0E1116 |
Dark 应用背景 |
1.3 原始色板 · 视图画布专用深色（Canvas）
2D/3D/剖面画布的衬底，两种模式通用。
| Token |
色值 |
说明 |
--canvas-bg |
#0B1320 |
视图画布主背景（原型深蓝黑） |
--canvas-bg-soft |
#111B2D |
画布内浮层（如「列表显示栏」浮窗）底 |
--canvas-grid |
#1E2A3D |
画布网格线、坐标轴 |
--canvas-overlay |
rgba(10,17,28,0.82) |
画布上的标签底（如 ERT1 标注牌） |
--canvas-text |
#E6ECF5 |
画布上文字 |
--canvas-text-dim |
#8A97AC |
画布上次要文字（坐标、比例尺） |
1.4 语义色 · 状态色（Status）
来自原型异常分级（红=高/低阻异常、橙=中等、蓝=边界/信息）与通用反馈。每个状态含 主色 / 浅底 / 边框 三档。
| 语义 |
主色(Light) |
主色(Dark) |
浅底(Light) |
浅底(Dark) |
用途 |
| Danger / 高（红） |
#E5484D |
#FF6166 |
#FDECEC |
#3A1D1F |
高等级异常、错误、删除 |
| Warning / 中（橙） |
#E08A1E |
#F5A623 |
#FBF0DD |
#3A2C12 |
中等异常、警告 |
| Success（绿） |
#2E9E5B |
#46C07A |
#E7F6ED |
#16301F |
成功、在线、就绪 |
| Info / 低（蓝） |
#3B73EC |
#5E8DF5 |
#EFF5FF |
#16243F |
信息、低等级、边界过渡 |
| Neutral / 离线（灰） |
#7C8493 |
#8A93A3 |
#F0F1F4 |
#23282F |
离线、停用、未知 |
异常分级专用（原型异常列表左侧圆点 + 标签「高/中/低」）：高=Danger、中=Warning、低=Info，停用/隐藏=Neutral。三维视图与剖面图中的异常标注牌也用同一组色。
1.5 语义 token 映射表（组件取此层）
| 语义 token |
Light 取值 |
Dark 取值 |
bg/app |
neutral-50 |
neutral-950 |
bg/panel |
neutral-0 |
neutral-900 |
bg/panel-subtle |
neutral-25 |
#161B22 |
bg/header |
neutral-0 |
#12161C |
bg/hover |
neutral-100 |
#1B2129 |
bg/selected |
primary-50 |
#16243F |
bg/canvas |
canvas-bg |
canvas-bg |
border/default |
neutral-200 |
#262C35 |
border/strong |
neutral-300 |
#333B45 |
border/focus |
primary-500 |
primary-400 |
text/primary |
neutral-800 |
#E6E9EF |
text/secondary |
neutral-600 |
#A4ADBB |
text/tertiary |
neutral-500 |
#7A8494 |
text/disabled |
neutral-400 |
#5A626F |
text/link |
primary-500 |
primary-400 |
text/on-primary |
neutral-0 |
neutral-0 |
accent/primary |
primary-500 |
primary-400 |
accent/primary-hover |
primary-600 |
primary-300 |
accent/primary-pressed |
primary-700 |
primary-500 |
divider |
neutral-200 |
#22272F |
scrollbar/thumb |
neutral-300 |
#3A424D |
scrollbar/thumb-hover |
neutral-400 |
#4A535F |
2. 字体与排版（Typography）
2.1 字族
| 用途 |
字体栈 |
| 中文 UI |
"Microsoft YaHei UI", "PingFang SC", "Source Han Sans SC", "Noto Sans CJK SC", sans-serif |
| 西文/数字 |
"Segoe UI", "Inter", "Helvetica Neue", Arial, sans-serif |
| 等宽（坐标/数值/编号/日志） |
"Cascadia Code", "JetBrains Mono", "Consolas", monospace |
macOS 优先 PingFang SC + SF Pro。数值、坐标（如 103.85°E · 36.72°N · z=1.0x）、批次号、深度刻度一律用等宽字体，保证对齐。
2.2 字号阶梯（pt，桌面端基准）
| Token |
字号 |
字重 |
行高 |
用途 |
text/display |
18 |
600 |
26 |
空状态大标题（少用） |
text/title |
14 |
600 |
22 |
对话框标题、首选项分组标题 |
text/heading |
12.5 |
600 |
20 |
面板标题栏（「对象显示栏」「属性」等） |
text/body |
11.5 |
400 |
18 |
正文、列表项、表单值 |
text/body-strong |
11.5 |
600 |
18 |
强调正文、选中项 |
text/label |
11 |
400 |
16 |
表单标签、次要说明 |
text/caption |
10 |
400 |
14 |
辅助信息（日期、计数、单位） |
text/mono |
11 |
400 |
16 |
数值/坐标/编号 |
桌面端字号偏小（信息密度优先）。如需适配高 DPI，按系统缩放因子整体放大，不单独改 token。
3. 间距、圆角、阴影、边框（Spacing / Radius / Elevation）
3.1 间距阶梯（px，4 的倍数节奏）
| Token |
值 |
典型用途 |
space/3xs |
2 |
图标与文字微距 |
space/2xs |
4 |
紧凑控件内边距 |
space/xs |
6 |
列表项上下内边距 |
space/sm |
8 |
控件内边距、小间隔 |
space/md |
12 |
面板内边距、表单行距 |
space/lg |
16 |
分组间距 |
space/xl |
24 |
对话框内边距 |
space/2xl |
32 |
大区块分隔 |
3.2 圆角
| Token |
值 |
用途 |
radius/none |
0 |
表格、树（贴合密集布局） |
radius/sm |
4 |
按钮、输入框、标签 |
radius/md |
6 |
卡片、列表项、浮层 |
radius/lg |
8 |
对话框、画布浮窗 |
radius/pill |
999 |
胶囊标签、开关、计数徽标 |
3.3 边框
- 默认边框宽度
1px，颜色 border/default。
- 聚焦态边框
1px border/focus + 外发光 0 0 0 2px primary-100（Light）/ primary-900 透明度 描边（Dark）。
- 分隔线用
divider，1px。
3.4 阴影（仅浮层使用，界面整体扁平）
| Token |
Light |
Dark |
shadow/popover |
0 4px 16px rgba(20,30,50,0.12) |
0 4px 16px rgba(0,0,0,0.5) |
shadow/dialog |
0 12px 40px rgba(20,30,50,0.18) |
0 12px 40px rgba(0,0,0,0.6) |
shadow/dropdown |
0 2px 10px rgba(20,30,50,0.10) |
0 2px 10px rgba(0,0,0,0.45) |
树、列表、表格、面板不使用阴影（扁平、紧凑）。仅菜单、下拉、tooltip、对话框、画布浮窗使用。
4. 布局框架（依据原型还原）
原型即客户端「项目分析视图」工作台，整体为 顶栏 + 三栏主体 + 中列上下分割 的多面板结构（用 ADS 实现停靠）。
4.1 整体栅格
┌──────────────────────────────────────────────────────────────┐
│ 顶栏 TopBar (高 48px) │
├────────────┬───────────────────────────────┬─────────────────┤
│ 左栏 │ 中列上：2D/3D 视图画布 │ 右栏上：异常列表 │
│ 对象显示栏 │ (深色 canvas，含浮窗/工具) │ /对象属性 (Tab) │
│ (树) ├───────────────────────────────┤ │
│ │ 中列下：数据详情 ├─────────────────┤
│ 数据集显示栏 │ (Tab + 工具条 + 剖面图) │ 右栏下：属性 │
│ (列表) │ │ (键值表) │
└────────────┴───────────────────────────────┴─────────────────┘
4.2 各区尺寸建议
| 区域 |
尺寸 |
说明 |
| 顶栏 TopBar |
高 48px |
固定 |
| 左栏 |
默认宽 280px，可拖拽 220–400px |
上下两段：对象树 + 数据集列表 |
| 右栏 |
默认宽 340px，可拖拽 280–460px |
上下两段：异常/属性 Tab + 属性键值表 |
| 中列 |
自适应填充 |
上下分割：视图画布（占比大）+ 数据详情 |
| 面板标题栏 |
高 36px |
含图标 + 标题 + 右侧动作按钮 |
| 面板间分隔条（splitter） |
4px 命中区，视觉 1px |
hover 显示 accent/primary |
4.3 面板标题栏规范（所有可停靠面板统一）
- 左：
14px 图标（QtAwesome）+ text/heading 标题，可带计数（如「异常列表 2/3」）。
- 右：动作按钮区（如 筛选漏斗、+、展开/折叠、全屏），图标按钮
24×24px，hover 显示 bg/hover 底。
- 底部
1px divider。
- 背景
bg/panel。
5. 顶栏 TopBar（依据原型）
从左到右的元素与规范：
| 元素 |
规范 |
| Logo |
左起，高 24px，含下拉箭头（切换工作空间/企业） |
| 项目名 + 区域 |
图标 + 项目名（text/body-strong）+ 区域下拉胶囊（primary 文字 + 浅底） |
| 主导航（视图分析/项目管理/业务工具） |
文字 tab，含图标；当前项 accent/primary + 底部 2px 高亮条；业务工具带下拉箭头 |
| 右侧工具组 |
设备（主按钮样式，accent/primary 填充）、帮助(?)、通知(铃铛，含红点徽标)、设置(齿轮)、用户头像+姓名+角色 |
| 背景 |
bg/header，底部 1px divider |
| 图标按钮尺寸 |
32×32px，hover bg/hover |
| 通知红点 |
8px 圆点，Danger 色，右上角 |
6. 核心组件规范
6.1 对象树（左栏上 · 对象显示栏）
原型特征：多级树，每行含「复选框 + 状态圆点 + 类型图标 + 名称 + 右侧计数」。
| 元素 |
规范 |
| 行高 |
28px |
| 缩进 |
每级 16px，展开箭头 12px |
| 复选框 |
14px，选中 accent/primary 填充 + 白勾；三态（半选）用横线 |
| 状态圆点 |
8px 实心圆，颜色映射对象状态/数据集色（蓝/绿/橙/红，与右侧异常色一致） |
| 类型图标 |
14px QtAwesome，text/secondary 色 |
| 名称 |
text/body；选中行 text/body-strong |
| 计数徽标 |
右对齐，text/caption，text/tertiary 色；可加 pill 浅底 |
| 选中行 |
底 bg/selected，左侧 2px accent/primary 竖条 |
| hover 行 |
底 bg/hover |
| 分组节点（GS） |
名称略强，可加定位图标 |
6.2 数据集列表（左栏下 · 数据集显示栏）
原型特征：顶部 Tab（数据 / 文件，带计数）+ 列表项（含状态点、标题、日期·通道数）。
| 元素 |
规范 |
| 段 Tab |
「数据 2 / 文件 3」，胶囊式分段控件（见 6.9） |
| 列表项高 |
52px（双行：标题 + 元信息） |
| 标题 |
text/body，含前置状态圆点 |
| 元信息行 |
text/caption text/tertiary，如「2026-03-15 09:21 · 64 道」 |
| 选中项 |
bg/selected + 左 2px 竖条 + radius/md |
| 右上工具 |
筛选漏斗、导出图标 |
6.3 异常列表（右栏上 Tab1）
原型特征：每条含左侧状态竖条 + 圆点 + 名称 + 等级标签 + 多行属性 + 右侧眼睛(显隐)。
| 元素 |
规范 |
| 卡片项 |
radius/md，左 3px 状态色竖条，内距 space/sm |
| 卡片底 |
对应状态浅底（高=Danger 浅底、中=Warning 浅底、低=Info 浅底） |
| 名称 |
text/body-strong + 圆点 |
| 等级标签 |
胶囊标签，状态色（见 6.8） |
| 属性行 |
text/caption，如「140m · 18m / 32 Ω·m」，数值用等宽 |
| 显隐开关 |
右侧眼睛图标，开=text/secondary，关=text/disabled + 斜杠眼 |
| 标题计数 |
「异常列表 2/3」=可见/总数 |
6.4 属性键值表（右栏下 · 属性）
原型特征：两列键值，左键右值，多组。
| 元素 |
规范 |
| 行高 |
28px |
| 键 |
左列，text/label text/secondary，定宽约 72px |
| 值 |
右列，text/body text/primary，数值/日期用等宽；可右对齐 |
| 分组标题 |
text/heading，上留 space/md |
| 可编辑值 |
hover 显示编辑图标；进入编辑变为内联输入框 |
| 链接值 |
指向其他数据集的属性显示为 text/link，点击跳转新建详情页 |
6.5 视图画布（中列上 · 2D/3D）
始终深色（bg/canvas），不随模式切换变浅。
| 元素 |
规范 |
| 视图切换 |
左上「二维地图 / 三维视图」分段 tab，深色版分段控件 |
| 画布浮窗（列表显示栏） |
左上浮层，底 canvas-bg-soft + radius/lg + shadow/popover，半透明 |
| 画布内文字 |
canvas-text / canvas-text-dim |
| 标注牌（ERT1 等） |
底 canvas-overlay，白字，radius/sm |
| 右上控件 |
底图切换下拉（天地图等）、缩放 +/-，深色按钮 |
| 右下状态条 |
坐标/比例尺，canvas-text-dim，等宽字体 |
| 缩放按钮 |
28×28px，深色半透明底，hover 提亮 |
| 顶部状态徽标 |
如「3/4 测线可见」，圆点 + text/caption |
6.6 数据详情区（中列下 · 剖面图）
原型特征：Tab（采集批次）+ 二级 Tab（原数据/网格数据）+ 工具条 + 剖面图 + 色阶条。
| 元素 |
规范 |
| 标题栏 |
图标 +「数据详情」+ 右侧设置/下载图标 |
| 批次 Tab |
可关闭的多 Tab（数据集详情以 Tab 呈现，见 6.10） |
| 二级 Tab |
「原数据 / 网格数据」文字 tab |
| 工具条 |
一排工具按钮（异常标注/色阶配置/白化/滤波处理）= 次按钮(描边)样式，带图标；右侧为复选框组（显示异常/等值线等）+ 滑块（简化容差）+ 右端图标按钮（网格/另存为） |
| 复选框组 |
行内排列，14px 复选框 + text/label |
| 滑块 |
见 6.13 |
| 剖面图画布 |
深色衬底；色阶填充用数据色阶（见 §8） |
| 色阶条（legend） |
底部水平色带 + 刻度（等宽数字）+ 单位标签 |
| 深度/距离轴 |
轴标题 text/caption，刻度等宽 |
6.7 按钮（Button）
| 类型 |
Light |
Dark |
用途 |
| Primary（主） |
底 accent/primary 白字，hover accent/primary-hover |
同（用 Dark 强调取值） |
设备、确定、主操作；每个区域≤1个 |
| Secondary（次/描边） |
描边 border/strong + text/primary，hover bg/hover |
同 |
工具条按钮、取消 |
| Tertiary（文字/幽灵） |
无边无底 text/secondary，hover bg/hover |
同 |
次要动作、图标按钮 |
| Danger |
底/描边 Danger |
同 |
删除等破坏性操作 |
| Link |
text/link 无底 |
同 |
内联跳转 |
- 高度：标准
28px，紧凑（工具条）26px，大（对话框主操作）32px。
- 内距：水平
space/md，图标与文字间距 space/xs。
- 圆角
radius/sm。禁用态：text/disabled + 不变底色 + 光标禁用。
6.8 标签 / 徽标（Tag / Badge）
| 类型 |
规范 |
| 状态标签（高/中/低） |
胶囊 radius/pill，状态浅底 + 状态主色文字，text/caption，内距 space/2xs space/sm |
| 计数徽标 |
圆形/胶囊，text/tertiary + neutral-100 底；通知红点为纯 Danger 圆点 |
| 类型徽标 |
中性，neutral-100 底 + text/secondary |
6.9 分段控件（Segmented / 视图切换、数据/文件 Tab）
- 容器：
neutral-100 底（Dark #1B2129）+ radius/md，内距 2px。
- 选中段：
bg/panel 底 + text/primary + 轻阴影（浮起感）。
- 未选段：透明 +
text/secondary，hover text/primary。
- 深色画布上的分段控件（视图切换）用深色版：容器半透明深底，选中段
accent/primary 文字。
6.10 标签页（Tabs · 数据集详情多 Tab）
- 标签：
text/body，当前项 text/primary + 底部 2px accent/primary；非当前 text/secondary。
- 可关闭：每个 Tab 右侧
×（hover 显示），底色 hover bg/hover。
- 新建详情页 = 新增 Tab；列表选中与 Tab 双向联动（选中 Tab 高亮）。
- 溢出：超出宽度显示左右滚动箭头或下拉列出全部 Tab。
6.11 大视图模式（剖面/属性页全屏）
- 触发后该详情页覆盖「标题菜单以下区域」，其余面板隐藏。
- 右上角显示「按 Esc 退出大视图」提示条（
canvas-overlay 底，text/caption，2 秒后淡出）。
6.12 复选框 / 单选 / 开关
| 控件 |
规范 |
| 复选框 |
14px，未选描边 border/strong；选中 accent/primary 填充 + 白勾；半选横线；禁用降透明 |
| 单选框 |
14px 圆，选中 accent/primary 圆环 + 实心点 |
| 开关 Switch |
宽 36px 高 20px 胶囊，关=neutral-300 底，开=accent/primary 底，滑块白色 16px |
6.13 滑块（Slider · 如简化容差）
- 轨道
4px neutral-200（Dark #2A313B），已填充段 accent/primary。
- 滑块手柄
14px 白圆 + 1px border/strong + 轻阴影；hover 放大到 16px。
- 当前值标签：右侧等宽数字。
7. 表单、表格、对话框等通用组件（补充 · 原型未全部出现但客户端必备）
7.1 输入框（Text Input）
| 状态 |
规范 |
| 默认 |
高 28px，底 bg/panel，描边 1px border/default，radius/sm，内距 space/sm，text/body |
| hover |
描边 border/strong |
| focus |
描边 border/focus + 外发光 |
| 禁用 |
底 neutral-50（Dark #1A1F26）+ text/disabled |
| 错误 |
描边 Danger + 下方 text/caption Danger 错误说明 |
| 占位符 |
text/disabled |
| 前/后缀 |
单位、图标置于框内两端，text/tertiary |
7.2 下拉选择（ComboBox / Select）
- 外观同输入框 + 右侧
12px 下拉箭头。
- 展开菜单：
bg/panel + radius/md + shadow/dropdown；项高 28px，hover bg/hover，选中项 bg/selected + 勾。
- 可搜索下拉：顶部带搜索输入框。
- 多选下拉：选中项以 6.8 标签形式回填到框内。
7.3 数字输入 / 步进器（SpinBox）
- 输入框 + 右侧上下步进按钮（各
14px 高）；数值等宽右对齐；支持单位后缀。
7.4 表格（Table / DataGrid）
| 元素 |
规范 |
| 表头 |
底 neutral-100（Dark #161B22），text/label text/secondary，高 32px，可排序列带箭头 |
| 行高 |
标准 32px，紧凑 28px |
| 斑马纹 |
偶数行 bg/panel-subtle（可关闭） |
| 行 hover |
bg/hover |
| 行选中 |
bg/selected + 左 2px 竖条（多选用复选框列） |
| 单元格 |
内距 space/sm，文本 text/body，数值等宽右对齐 |
| 边框 |
仅横向 1px divider（无竖线，保持轻盈）；密集模式可加竖线 |
| 固定列/表头 |
横向滚动时首列与表头固定 |
| 空状态 |
居中插画/图标 + text/secondary 说明 + 可选操作按钮 |
| 分页/加载 |
底部分页器或无限滚动；加载中显示骨架行 |
7.5 对话框（Dialog / Modal）
| 元素 |
规范 |
| 遮罩 |
全屏 rgba(10,16,26,0.45)（Dark rgba(0,0,0,0.6)） |
| 容器 |
bg/panel + radius/lg + shadow/dialog；宽按内容（小 420px / 中 560px / 大 720px） |
| 标题栏 |
text/title + 右上 ×；底 1px divider；内距 space/xl |
| 内容区 |
内距 space/xl，可滚动 |
| 底部操作栏 |
右对齐：次按钮（取消）+ 主按钮（确定）；破坏性操作主按钮用 Danger；内距 space/lg space/xl |
| 进入动画 |
淡入 + 轻微上移（120ms） |
7.6 确认 / 警示框（Confirm / Alert）
- 小对话框，左侧状态图标（Danger/Warning/Info 圆形图标）+ 标题 + 说明文 + 操作按钮。
- 删除类：图标 Danger，主按钮 Danger，文案明确后果。
7.7 提示框（Toast / Notification）
| 类型 |
规范 |
| Toast（瞬时） |
右上或底部居中浮出，bg/panel + 状态色左竖条 + 图标 + 文案；radius/md + shadow/popover；3–4s 自动消失；可手动关闭 |
| 行内提示（Inline alert） |
块状，状态浅底 + 状态色左竖条 + 图标 + 文案；用于表单顶部、面板内提示 |
| 通知中心（铃铛） |
顶栏铃铛下拉面板，列表项含图标/标题/时间/已读态；未读左侧圆点 |
7.8 Tooltip / Popover
- Tooltip：深色小气泡（Light 也用深色
neutral-800 底 + 白字），text/caption，radius/sm，延迟 400ms 显示。
- Popover：
bg/panel + radius/md + shadow/popover，可含富内容（如对象快速属性 tip）。
7.9 菜单（右键菜单 / 下拉菜单）
| 元素 |
规范 |
| 容器 |
bg/panel + radius/md + shadow/dropdown，内距 space/2xs |
| 项 |
高 28px，左图标 14px + 文字 + 右侧快捷键（text/tertiary 等宽） |
| hover |
bg/hover |
| 分隔 |
1px divider，上下 space/2xs |
| 危险项 |
Danger 文字（如删除） |
| 子菜单 |
右侧箭头，hover 展开 |
| 禁用项 |
text/disabled |
对象树/数据集右键菜单按规约功能：显示/隐藏、定位、属性、异常详情、编辑、新建 GS/TM、导入数据集、删除等。
7.10 首选项 / 设置（Preferences）
原型顶栏齿轮入口，客户端必备完整设置界面。
| 元素 |
规范 |
| 结构 |
左侧分类导航（垂直列表）+ 右侧设置项面板（主从布局） |
| 分类项 |
高 32px，图标 + 名称，选中 bg/selected + 左竖条 |
| 设置项行 |
左：标题（text/body）+ 说明（text/caption text/tertiary）；右：控件（开关/下拉/输入） |
| 分组 |
分组标题 text/heading + divider |
| 建议分类 |
外观（主题：跟随系统/浅色/深色、字体、字号缩放）、启动画面与停留时间、默认大屏、语言（中/英）、坐标系默认、底图与缓存、更新（检查/通道）、账户、关于（版本/许可/Qt 源码声明） |
7.11 空状态 / 加载 / 骨架屏
- 空状态：居中
48px 灰度图标 + text/body secondary 主文案 + text/caption 辅助 + 可选主操作按钮。
- 加载：局部用旋转 spinner（
accent/primary）；区块用骨架屏（neutral-100/#1B2129 矩形微动画）。
- 进度：长任务（如在线更新、VTK 大数据加载）用进度条
accent/primary + 百分比等宽数字。
7.12 滚动条
- 细滚动条：宽
8px，thumb scrollbar/thumb + radius/pill，hover scrollbar/thumb-hover，轨道透明；overlay 模式（悬停才显）。
7.13 树/列表筛选器（漏斗）
- 面板标题栏漏斗图标 → 弹出 Popover：含搜索框 + 多选类型复选组 + 日期范围 + 「应用/重置」。
- 激活筛选时漏斗图标显示
accent/primary + 角标计数。
8. VTK 视图配色（与 UI 对齐）
关键约束：QSS/QPalette 不作用于 VTK 渲染窗口。VTK 画布配色须通过 VTK API 单独设置，并与 §1.3 画布 token 手动对齐，避免「UI 深色、视图另一种灰」的割裂。VTK 画布在两种模式下都用深色。
8.1 渲染窗口基础
| VTK 元素 |
取值（对齐 token） |
| 渲染器背景（renderer background） |
canvas-bg #0B1320；可用上下渐变到 #0E1626 |
| 三维网格/地面网格 |
canvas-grid #1E2A3D |
| 坐标轴（axes actor） |
X/Y/Z 用低饱和 红/绿/蓝，标签 canvas-text-dim |
| 文字标注（vtkTextActor） |
canvas-text #E6ECF5，等宽字体 |
| 比例尺/方位 |
canvas-text-dim |
| 拾取高亮 |
accent/primary #5E8DF5 描边 |
| 选中对象包围盒 |
accent/primary 虚线框 |
8.2 数据色阶（Colormap / Lookup Table）
原型剖面图色阶为电阻率经典彩虹色阶（紫蓝→青绿→黄→橙红→深红，对数刻度 5–1000 Ω·m）。规范：
| 色阶用途 |
推荐 colormap |
说明 |
| 电阻率/极化率（默认） |
彩虹/Jet 类（紫→蓝→青→绿→黄→橙→红） |
与原型一致；对数刻度；端点可标注异常 |
| 连续物理量（通用） |
Viridis / Turbo |
感知均匀，科学制图推荐 |
| 发散量（正负、相对基线） |
Coolwarm（蓝-白-红） |
如电位差、变化量 |
| 地层/分类（离散） |
离散调色板（命名色板） |
类别明确，高区分度 |
| 单色强度 |
单色渐变（如蓝系） |
单一属性强度 |
- 色阶须可配置、可命名保存（规约「色阶定义工具」），用户调整后视图实时刷新。
- 色阶条（legend）渲染在 UI 侧或画布侧均可，但刻度数字用等宽字体，单位明确。
- 等值线（contour）：默认
canvas-text-dim 细线；标注牌用 canvas-overlay 底。
8.3 异常标注（三维视图 + 剖面图）
- 异常圈/标注牌颜色 = §1.4 异常分级色（高=Danger、中=Warning、低=Info），与右栏异常列表严格一致。
- 三维视图中的测线：可见用亮色（红/绿区分极性或测线编号），不可见降透明。
9. 图标系统（QtAwesome）
- 统一用 QtAwesome（图标字体），全局禁止混用位图图标，保证矢量、可染色、随主题变色。
- 图标字体集：优先 Material Design Icons (mdi) 或 Font Awesome，全项目统一一套。
- 标准尺寸：行内
14px，按钮内 16px，面板标题 14px，空状态 48px。
- 默认色
text/secondary；激活/选中 accent/primary；禁用 text/disabled。
- 图标语义映射（建议固定，供 Claude Code 一致引用）：
| 语义 |
图标（mdi 名参考） |
| 对象树/层级 |
file-tree / sitemap |
| GS 分组/定位 |
map-marker |
| 数据集 |
database / chart-line |
| 文件 |
file-document |
| 二维地图 |
map |
| 三维视图 |
cube-outline |
| 异常 |
alert-circle |
| 属性 |
information-outline |
| 筛选 |
filter-variant |
| 新增 |
plus |
| 导出/下载 |
download / export |
| 显隐 |
eye / eye-off |
| 全屏 |
fullscreen / fullscreen-exit |
| 设置 |
cog |
| 通知 |
bell |
| 帮助 |
help-circle |
| 设备 |
access-point / chip |
| 色阶配置 |
palette |
| 白化/滤波 |
blur / wave |
| 网格 |
grid |
| 缩放 |
magnify-plus / magnify-minus |
10. 状态与交互反馈
| 交互态 |
表现 |
| hover |
背景 bg/hover 或控件提亮，120ms 过渡 |
| pressed |
加深一档 |
| focus（键盘） |
border/focus + 外发光，键盘可达性必须保留 |
| selected |
bg/selected + 左竖条 |
| disabled |
text/disabled + 降透明 + 禁用光标 |
| loading |
spinner / 骨架 / 进度条 |
| drag（异常合并、图层排序） |
拖拽项半透明跟随 + 目标位置 accent/primary 插入线 |
| 实时刷新（色阶/图例调整） |
视图即时重绘，无整页闪烁 |
动效克制：仅用 120–200ms 的 hover/展开/淡入过渡，专业工具避免花哨动画。
11. 双模式切换规范
- 三种选项：跟随系统 / 浅色 / 深色（首选项 §7.10 + 顶栏快捷切换可选）。
- 切换时：外围 UI（顶栏、面板、树、列表、表单、对话框）整体换肤；视图画布与剖面图保持深色基调不变（仅 UI 边框等微调）。
- 切换应即时、无重启；通过统一主题对象广播刷新所有 widget 的 QSS + QPalette。
- VTK 渲染器背景在两模式下均深色，不参与切换（仅当用户在首选项单独设置画布背景时才改）。
12. 可访问性与适配
- 对比度：正文文字与背景对比度 ≥ 4.5:1，大字 ≥ 3:1（两种模式都须校验，Dark 模式尤其注意状态浅底上的文字）。
- 不以颜色为唯一信息：异常分级除颜色外必须带文字标签（高/中/低）或图标，照顾色觉障碍。
- 高 DPI：所有尺寸用逻辑像素，随系统缩放因子整体放大；图标用矢量字体。
- 键盘导航：Tab 焦点环必须可见；树/列表/表格支持方向键。
- 最小命中区：可点击图标按钮命中区 ≥
24×24px。
13. 实现约定（给 Claude Code）
- 集中定义 token：建一个主题模块（如
src/ui/theme/），包含 Theme 对象，集中持有所有颜色/间距/字号 token 的两套取值（light/dark）。所有 widget 通过 theme.color("bg/panel") 一类接口取值，禁止散落硬编色值。
- QSS 模板化：QSS 写成带占位符的模板，运行时用当前 token 填充生成最终 QSS 字符串并
qApp->setStyleSheet()；切换模式时重新生成并应用。
- QPalette 同步：除 QSS 外必须同步设置 QPalette（Window/Base/Text/Highlight/ButtonText 等角色），否则原生绘制控件（菜单、tooltip、部分原生项）颜色不统一。两者取值来自同一 token。
- Fusion 为底座：
QApplication::setStyle("Fusion")，在其上叠加 QSS + QPalette，不替换为第三方 QStyle。
- VTK 配色独立设置：VTK 渲染器背景、坐标轴、文字、色阶用 VTK API 设置，取值引用 §8 / §1.3，与 UI token 对齐；模式切换时画布保持深色。
- 图标统一走 QtAwesome：封装一个图标工具函数
icon(name, role)，role 决定染色（默认/激活/禁用/状态色），全局复用 §9 映射。
- 主题切换广播：主题切换时通过信号通知所有顶层窗口重应用 QSS/QPalette 并刷新 QtAwesome 图标颜色。
- 可视化校验：实现后用 light/dark 各截图核对本规范（对比度、状态色一致性、视图画布与 UI 的衔接）。
附录 A：核心语义色速查（开发对照）
Light
| 用途 |
色值 |
| 应用背景 |
#F7F8FA |
| 面板背景 |
#FFFFFF |
| hover |
#EFF1F4 |
| 选中 |
#EFF5FF |
| 边框 |
#E3E6EB |
| 主文字 |
#272C35 |
| 次文字 |
#5A626F |
| 主强调 |
#3B73EC |
| 视图画布 |
#0B1320 |
| 高/Danger |
#E5484D |
| 中/Warning |
#E08A1E |
| 低/Info |
#3B73EC |
| 成功 |
#2E9E5B |
Dark
| 用途 |
色值 |
| 应用背景 |
#0E1116 |
| 面板背景 |
#161A20 |
| hover |
#1B2129 |
| 选中 |
#16243F |
| 边框 |
#262C35 |
| 主文字 |
#E6E9EF |
| 次文字 |
#A4ADBB |
| 主强调 |
#5E8DF5 |
| 视图画布 |
#0B1320（同 Light） |
| 高/Danger |
#FF6166 |
| 中/Warning |
#F5A623 |
| 低/Info |
#5E8DF5 |
| 成功 |
#46C07A |
本规范依据客户提供的 Web 原型（浅色）提取并派生深色模式，覆盖项目分析视图工作台及客户端通用组件。色值为初始建议值，落地后应结合实机截图微调对比度与一致性，并随设计迭代维护版本。