City-Lifeline-Cockpit/.scratch/lanhu-cockpit-asset-replacement/specs/03-visual-token-mapping.md

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

来源票：正式视觉系统与现有 token 映射

目标与边界

本规格只定义蓝湖视觉稿进入驾驶舱视觉系统的映射规则，不直接修改业务代码。保持四个一级模式、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 消费点、推导状态和可读性偏差清单。