# 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. 设计原则

1. **数据为主，UI 退后**：中间的 2D/3D 视图与剖面图是视觉焦点，外围面板（树、列表、属性）使用克制的中性色，不与数据争夺注意力。
2. **浅色为默认，深色为派生**：原型为浅色界面，Light 为基准模式；Dark 按相同色相、相同层级关系派生，保证两套是「同一语言的明暗版本」。
3. **信息密度优先**：勘探软件信息密集，控件紧凑、间距节制、对齐严谨，而非消费级 App 的宽松留白。
4. **强调色克制**：主强调色（科技蓝）只用于可交互的主操作、选中态、链接、聚焦；状态色只用于状态表达，不作装饰。
5. **视图区永远深色**：无论 Light/Dark 模式，中间的 2D 地图 / 3D 视图 / 剖面图画布**始终是深色衬底**（原型即如此），让色阶数据更突出。这意味着「模式切换」主要影响外围 UI，视图画布的深色基调保持稳定。
6. **双模式同构**：同一组件在两种模式下结构、间距、字号完全一致，仅颜色 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.0 表单布局（编辑态 / 只读态）— 总则

> 本节是「编辑/只读表单」的**单一事实来源**，统一约束四类表单：①弹出编辑/新建对话框、②属性子视图（对象属性 / 数据集属性）、③动态表单（`getDynamicForm` 驱动）、④首选项设置。控件本身的样式仍引用 §7.1–7.3、§6.12–6.13；本节只定义「把这些控件组织成一张表单」的布局、分组、状态、校验与配色规则。
>
> **设计取向**（参考主流优秀客户端）：macOS 系统设置 / Windows 11 设置（分组卡片 + 左标签）、JetBrains IDE 设置（密集左标签）、Figma 右侧属性面板（紧凑内联编辑）、Linear / Stripe（清晰节奏与即时校验）。在「信息密度优先」（§0.3）前提下取其**密集左标签 + 清晰分组 + 即时校验 + 克制留白**。

#### 7.0.1 两种表单形态（先定形态，再排布局）

| 形态 | 用途 | 实现 |
|---|---|---|
| **只读表单**（展示） | 纯查看的属性详情 | 用 §6.4 **属性键值表**（键值两列，数值等宽，不可编辑） |
| **可编辑表单**（编辑/新建） | 编辑、新建、设置 | 用本节「标签 + 控件」行式表单 |

**铁律**：一张表单只要存在**任一可编辑字段**，整张表即用「可编辑表单」形态；其中的只读字段以**禁用态控件**（§7.1 禁用）呈现，**不得**在同一张表单里一半键值表、一半输入框——保证可编辑与只读字段在同一栅格中对齐一致。

#### 7.0.2 表单栅格与行结构

| 元素 | 规范 |
|---|---|
| 标签位置 | **左侧标签列**（默认，密集专业风），标签文字**右对齐**贴近字段；字段名过长或窄单列对话框可改顶部标签 |
| 标签列宽 | 默认 `96–120px`，同一表单内**等宽对齐**（纯只读键值表用 §6.4 的 `72px`） |
| 标签 ↔ 字段间距 | `space/md`(12) |
| 字段控件高 | `28px`（§7.1）；行与行垂直间距 `space/sm`(8) |
| 字段宽度 | 宽面板/对话框中**不要拉满**，单字段最大宽约 `360px`（多行/长文本可更宽）；窄属性面板中填充可用宽度 |
| 表单内边距 | 对话框内 `space/xl`(24)；面板内 `space/lg`(12–16) |
| 列数 | **单列优先**；信息多用分组而非多列。仅「短字段（数值+单位）」可两列并排 |

#### 7.0.3 分组（Section）

- 分组标题：`text/heading`，上方留 `space/lg`，标题下可加 1px `divider` 贯通。
- 组**内**字段紧凑（行距 `space/sm`），组**间**留 `space/lg`–`space/xl`。
- 对话框内多组（对齐原版 `getDynamicForm` 的 基本信息 / 测线布设 / 数据质量 等）：组数多时用**锚点分组**或**分页签**，避免一屏堆叠过长。

#### 7.0.4 字段状态与标记

| 标记/态 | 规范 |
|---|---|
| **必填** | 标签后红色 `*`（`status/danger`），紧贴标签 |
| 可选 | **默认不标记**（保持干净）；确需时标签后加 `text/tertiary` 的「（可选）」 |
| **只读/禁用** | §7.1 禁用态（底 `neutral-50`/Dark `#1A1F26`、文字 `text/disabled`、禁用光标）——明确不可编辑，其值**仍随表单提交** |
| **错误** | §7.1 错误态：描边 `status/danger` + 字段下方 `text/caption` `status/danger` 说明 |
| 帮助/说明 | 字段下方 `text/caption` `text/tertiary` 一行（与错误说明**互斥**位置） |
| 单位/前后缀 | 框内右端 `text/tertiary`（§7.1 前后缀） |

#### 7.0.5 校验与提交反馈

- **即时校验**：失焦/输入时校验单字段，错误就地显示（§7.1 错误态），不打断输入。
- **提交校验**：点「保存/确定」校验全表 → 有错则**滚动并聚焦第一个错误字段** + 就地显示错误；可同时在表单顶部用**行内提示**（§7.7 inline alert）汇总「请完善 N 项」。**不要**只弹一个模糊 toast。
- **脏标记**：表单无用户修改时「保存」按钮**置灰不可点**；任一字段改动后启用（与已落地的对象属性面板一致）。
- **提交中**：主按钮 loading（spinner/禁用）防重复提交；成功后 Toast（§7.7）+ 关闭或刷新。

#### 7.0.6 弹出编辑 / 新建对话框（body）

- 外壳遵 §7.5（容器 `radius/lg` + 标题栏 + 底部操作栏）。body 即本节表单：内距 `space/xl`、单列左标签、分组按 7.0.3。
- 底部操作栏：**取消（次按钮，左）+ 主操作（确定/保存，Primary，右）**；破坏性确认用 Danger（§7.5/§7.6）。
- **新建 vs 编辑**：编辑态预填现值；不可改字段（如类型、按 API 只读的名称）用**禁用控件**而非省略；标题区分「新建 XX / 编辑 XX」。

#### 7.0.7 四类表单的归口（落地映射）

| 表单 | 形态 | 要点 |
|---|---|---|
| 对象属性面板（对象属性 Tab） | 可编辑表单 | 名称**仅顶部显示一处**且按 API 只读；只读字段禁用灰显；脏标记控制保存 |
| 数据集属性面板 | 上半 §6.4 **只读键值表** + 下半**可编辑描述**（单字段可编辑表单） | 两段职责分明 |
| 动态表单（`getDynamicForm`） | 可编辑表单 | 分组 = `formList` 组；控件按 `displayComponentType` 映射（§7.1/7.2/7.3/6.12）；必填/只读由 `requiredType`/`fieldUseType` 决定（7.0.4） |
| 首选项设置（§7.10） | 设置型表单变体 | 主从布局 + 设置行（左：标题+说明，右：控件） |

#### 7.0.8 配色与排版令牌（汇总 · 禁硬编码）

| 角色 | token |
|---|---|
| 标签文字 | `text/secondary`（必填 `*` 用 `status/danger`） |
| 字段值 / 输入文字 | `text/primary`；数值/坐标/编号用等宽 `type::kMonoFamily` |
| 分组标题 | `text/heading` |
| 分隔线 | `divider` |
| 错误（描边+说明） | `status/danger` |
| 只读字段 底/文字 | `neutral-50`（Dark `#1A1F26`）/ `text/disabled` |
| 字段 背景/边框/focus | 见 §7.1（`bg/panel`、`border/default`→`border/strong`→`border/focus`） |

#### 7.0.9 可访问性

- 标签与控件**关联**（点击标签聚焦其控件 / buddy）。
- Tab 焦点顺序自上而下、左到右；焦点环可见（§10、§12）。
- **不以颜色为唯一信息**：必填除 `*` 外，校验失败有文字说明；错误态有文字。
- 可点控件最小命中区 ≥ `24×24px`（§12）。

---

### 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）

1. **集中定义 token**：建一个主题模块（如 `src/ui/theme/`），包含 `Theme` 对象，集中持有所有颜色/间距/字号 token 的两套取值（light/dark）。所有 widget 通过 `theme.color("bg/panel")` 一类接口取值，**禁止散落硬编色值**。
2. **QSS 模板化**：QSS 写成带占位符的模板，运行时用当前 token 填充生成最终 QSS 字符串并 `qApp->setStyleSheet()`；切换模式时重新生成并应用。
3. **QPalette 同步**：除 QSS 外**必须同步设置 QPalette**（Window/Base/Text/Highlight/ButtonText 等角色），否则原生绘制控件（菜单、tooltip、部分原生项）颜色不统一。两者取值来自同一 token。
4. **Fusion 为底座**：`QApplication::setStyle("Fusion")`，在其上叠加 QSS + QPalette，不替换为第三方 QStyle。
5. **VTK 配色独立设置**：VTK 渲染器背景、坐标轴、文字、色阶用 VTK API 设置，取值引用 §8 / §1.3，与 UI token 对齐；模式切换时画布保持深色。
6. **图标统一走 QtAwesome**：封装一个图标工具函数 `icon(name, role)`，role 决定染色（默认/激活/禁用/状态色），全局复用 §9 映射。
7. **主题切换广播**：主题切换时通过信号通知所有顶层窗口重应用 QSS/QPalette 并刷新 QtAwesome 图标颜色。
8. **可视化校验**：实现后用 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 原型（浅色）提取并派生深色模式，覆盖项目分析视图工作台及客户端通用组件。色值为初始建议值，落地后应结合实机截图微调对比度与一致性，并随设计迭代维护版本。*