# 正式视觉系统与现有 token 映射规格

来源票：[正式视觉系统与现有 token 映射](../issues/03-visual-system-token-mapping.md)

## 目标与边界

本规格只定义蓝湖视觉稿进入驾驶舱视觉系统的映射规则，不直接修改业务代码。保持四个一级模式、16 个二级面板、`mode`、`panelId`、地图图层、状态语义、拾取、定位、聚合和面板联动不变。本次只交付一套深色主题。

蓝湖具体颜色、字号、字体和画板尺寸必须由逐画板盘点记录；本规格不虚构具体设计值。

## Token 映射原则

1. 保留现有 token 名称和消费关系；蓝湖替换优先修改现有 token 的值。
2. 蓝湖引入新视觉概念时，可以新增语义 token，但不得以裸像素/裸色值散落到组件中。
3. 全局 token 冲突时，以蓝湖主画板/首页画板为默认权威值；其他画板只有在能明确绑定组件、状态或模式时才建立局部例外。
4. 未能解释的画板冲突不得猜测实现，回设计确认。
5. 局部 token 使用“视觉语义 + 适用状态”命名，例如 `--panel-warning-glow`、`--overlay-selected-border`；必须记录消费组件和状态，无消费点不提交。

## 现有 token 对接表

| 视觉领域 | 现有入口 | 映射规则 |
| --- | --- | --- |
| 设计基准与缩放 | `.cockpit-shell --u` | 以蓝湖主画板宽度为设计基准；主画板为 1920px 时保持现有基准。 |
| 底色与面板 | `--bg-0`、`--panel-top`、`--panel-bot`、`--panel-line`、`--panel-line-hi`、`--inset` | 以主画板值替换；局部面板差异使用有语义的局部 token。 |
| 主色 | `--cyan`、`--cyan-d` | 仍作为品牌/交互主色，不在组件中另写颜色。 |
| 语义色 | `--lv1`–`--lv4`、`--neutral` | 事件等级与点位状态继续共用调色板。若蓝湖要求拆成两套色，必须另立决策，不在本票内拆分。 |
| 文字 | `--text`、`--text-2`、`--muted` | 按可读性验收；蓝湖低对比不足以支撑运行时阅读时，可提高对比度并记录偏差。 |
| 字体槽位 | `--font`、`--num` | 本票锁定语义槽位和使用关系；Web 授权、字体文件和回退由票 06 决定。 |
| 字号 | `--fs-caption`、`--fs-body`、`--fs-title`、`--fs-heading` | 保留语义命名；按实际消费新增如 `--fs-kpi`、`--fs-metric` 等，不建立大量裸像素档位。 |
| 间距 | `--space-1`–`--space-3` | 保留语义命名；按实际消费新增如 `--space-panel` 等，不在组件中散写尺寸。 |
| 栏宽/层级/阴影 | `--column-w`、`--z-*`、`--shadow` | 结构稳定；蓝湖仅影响视觉值，不改变层级语义和地图生命周期。 |

## 装饰与面板外框

- 可由 CSS、SVG、渐变和几何规则无损复现的网格、扫描线、暗角、辉光、切角和边框，继续由 token 或组件 CSS 实现。
- 复杂位图纹理、不可由 CSS/SVG 无损复现的噪声或光效，才作为运行时资源进入 manifest。
- `CockpitPanel` 面板优先保持 CSS/SVG 的可伸缩实现；切角/边框只有在蓝湖视觉无法无损复现时才切为资源。
- 资源化装饰不得改变面板高度、收放行为、`panelId` 或内容滚动边界。

## 1280px 与面板行为

在最小 1280px 桌面宽度下，优先级为：文字可读、按钮可操作、面板不重叠，其次才是装饰像素比例。

- 左右面板保持宽度并自动换行，不通过无限压缩栏宽适配。
- 面板内容区独立纵向滚动；内容过长时允许上下滚动。
- 面板支持卷轴式展开/折叠；标题、`panelId`、收放控制和数据状态稳定。
- 展开/折叠只改变内容可视高度，不改变数据语义、地图实例生命周期或选择状态。
- 装饰可缩放、隐藏或降级，但业务文字和交互控件不可被装饰牺牲。

## 缺失状态推导

蓝湖仅提供默认态时，允许根据统一规则推导未提供状态，但必须在资产/状态清单中标记为“非蓝湖确认”：

- hover：提高亮度或边框强调；
- active/selected：提升主色、边框和层级；
- disabled：降低对比度但保留文字和状态线索；
- loading/error：沿用现有运行时状态语义色和可读文案。

各组件不得自行发明不同的推导规则。

## 可读性偏差

蓝湖使用低透明度、细线或低对比文字时，运行时允许提高对比度、线宽或不透明度，但必须记录：原设计值、运行时值、调整原因和影响组件。不得改变业务状态的语义色或信息层级。

## 验收证据

实现后需同时提供：

1. token 与引用静态检查，确认没有新增无语义裸色值/裸尺寸和第二套全局视觉定义；
2. 四个一级模式、16 个 `panelId`、面板收放和地图生命周期回归；
3. 蓝湖主画板与真实 `/cockpit` 的对照截图或人工走查记录；
4. 设计基准画板和最小 1280px 宽度检查；
5. 局部 token 消费点、推导状态和可读性偏差清单。