UI 设计及图标素材使用共识

来源：执行-批次1：品牌/图标替换四轮执行与维护者反馈的沉淀。生效范围：城市生命线驾驶舱 /cockpit 的全部 2D UI 图标与切图素材。 性质：本项目图标素材的单一事实来源（single source of truth）。后续任何图标/切图的引入、替换、改名，按本文执行，不再逐轮口头约定。

1. 目录边界（谁放哪儿）

目录	内容	是否进产物
`public/cockpit/assets/icons/`	运行时图标（扁平，全部英文名）	✅
`public/cockpit/assets/icons/panel/`	面板小标题图标（已统一染主蓝）	✅
`public/cockpit/assets/icons/status/`	状态标识图标（已按语义色染色）	✅
`.scratch/lanhu-cockpit-asset-replacement/design-archive-v2/`	蓝湖切图设计归档（原文件名+hash 索引）	❌ 不部署
`E:\&项目模型文件等\UI图片\`	维护者的设计源目录（Texture/Icon、PSD 等）	❌ 本机外部

规则：

运行时目录只进「已确认消费」的素材——下载/导入后先在归档区观察，登记语义并找到落点后才入 public/cockpit/assets/icons/。没有消费点的图不进运行时（无死资源是验收项）。
设计归档永不删除、永不改名——它是追溯来源的锚点（manifest source.archive 指向它）。
禁止把素材放进 public/plugins/**（TvT 插件体系），驾驶舱不依赖它。

2. 命名规范（英文 + 语义）

运行时文件一律英文 kebab-case，语义自明。 中文命名只在设计源/归档区存在。

<语义>[-<变体>].png          扁平图标        例：pipeline.png / alert.png / brand-title.png
panel-<语义>.png             面板小标题      例：panel-monitoring.png
status-<状态>.png            状态标识        例：status-alarm.png / status-workOrder.png
industry-<行业>.png          行业图标        例：industry-gas.png / industry-drainage.png
<对象>点.png → <对象>-point.png              位置符号类（批次 3 用） 例：water-point.png

禁止纯序号名（1.png、未命名-3.png）——批次 1 两次语义错配的根源就是无语义命名。
多词用 - 不用 _；同一图不同变体加数字后缀（brand-glow-1/2/3.png）。
改名必须同步 manifest：manifest 记录 path + 内容 hash，单改文件名 = 运行时 404。同步方式：改 research/build-manifest.mjs 的 ICON_MAP → 重跑 → check-manifest.mjs 验证。

3. Manifest（唯一权威入口）

组件只消费语义 key（<CockpitIcon name="layers" />），禁止在组件里拼物理路径。全仓只允许 domain/runtimeAssets.js 一处引用 assets/ 路径。
一个文件一个 key；多消费方共享同一 key（如 icon.panel.monitoring 同时服务运行监测/运行信息/监测概览三面板）。
条目字段：key / path / source(来源) / format / dimensions / pixelRatio / renderMode / version / hash / status / appliesTo / fallbackKey / core。
status 四值：formal（正式）/ temporary（临时，必须同时在票 06 缺口清单登记）/ derived / fallback。验收不得把 temporary 当 formal 通过。
renderMode 二值：image（彩色位图，<img>）/ mask（单色 SVG，CSS mask + currentColor）。新增 SVG 单色图标走 mask，彩色 PNG 走 image。
新增/替换图标的固定流程：
1. 素材放入 icons/（英文名）；
2. 在 research/build-manifest.mjs 的 ICON_MAP 加一行；
3. node research/build-manifest.mjs（重算 hash、保留 fonts 块）；
4. domain/icons.js 注册表加语义名映射；
5. node research/check-manifest.mjs（文件可达 + 拒绝 HTML 兜底 + hash 一致）；
6. node research/cross-check-icons.mjs（四处交叉引用一致）。
fonts 块共存纪律：manifest.json 顶层 fonts（授权门禁）归批次 4 所有；build-manifest.mjs 通过 PRESERVED_TOP_LEVEL 保留非 icon 顶层键，任何脚本不得整体重写 manifest 而不带该保留逻辑。

4. 风格统一（面板/状态类图标的视觉规范）

4.1 源图选用

统一从 E:\&项目模型文件等\UI图片\Texture\Icon 取图，按维护者规定的优先级：
- Pipe* = 主要（实心体，语义强）；
- I* = 次要（线稿渐变，风格轻）；
- Q* = 补充（I 系列缺语义时的补充）。
面板小标题、状态标识等「小尺寸高频」位置用 I/Q 线稿系（小尺寸下实心体糊成一团）。

4.2 染色（去色 + 语义色）

总原则（2026-10-12 维护者修订）：给予的图标素材一律去色后再使用。 颜色语义只由承载状态的层表达——两层都用颜色会同色融合导致不可辨（场景点位设备图标为例：标记点已用颜色表达状态，内层行业图标再彩色就什么都看不清）。

按落点分三档：

落点	去色后染什么
面板小标题	整体染主蓝 `#01abea`（--cyan）
状态标识	按状态染语义色（下表）
位置符号内层（点位/设备里的行业图标）	蓝白渐变重染（亮部白、暗部主蓝），禁止行业彩色原稿

状态标识语义色（色值唯一来自 tokens.css）：

用途	色值	token
状态·报警	`#ff3b52`	`--lv1`
状态·预警	`#ffb020`	`--lv2`
状态·工单/进行中	`#01abea`	`--lv3`
状态·正常	`#27d17a`	`--lv4`
状态·离线/中性系	`#5680b0`	`--neutral`

禁止在组件里散写图标颜色；新语义色先加 token 再用。
染色管线：面板/状态用 research/tint-panel-icons.mjs、tint-status-icons.mjs；位置符号内层用 services/markerAssets.js 的 recolorInner（运行时逐像素）。改色板/换图重跑即可。
直接可用的彩色切图（如品牌主标题、行业筛选按钮图标）不经染色——它们是设计定稿色，但仍须走 manifest。
位置符号附加项（批次 3 走查定稿）：整枚符号加 2px 白描边（深色底图更立体）；合成输出裁剪到母版 bbox（512² 方图两侧全透明，不裁剪塞非方 billboard 会拉伸变形）。

5. 接缝与可访问性（代码侧纪律）

接缝不变：domain/icons.js 注册表（语义名 → manifest key）是唯一的消费映射；CockpitIcon 组件按 renderMode 二选一渲染。新落点 = 加注册表映射 + 组件用 <CockpitIcon name="...">，不新发明引用方式。
图标一律 aria-hidden（CockpitIcon 模板已内置）：图标不参与按钮/标题的可访问命名，读屏读到的仍是纯文字。走查断言 textContent 不受图标影响。
视觉信息不进领域契约：图标映射表（PANEL_ICONS / INDUSTRY_ICONS / legendVisuals().icon）单独成表或作为附加字段，不改动 INDUSTRIES 数组结构、panelId、data-panel-id、data-industry、aria-pressed/expanded 等既有断言面。
未知名不抛错：注册表查不到 → 渲染为空。缺失图标不打断骨架渲染（既有不变量）。

6. 已锁定的语义映射（不得随意变更）

语义	图标	备注
管线图层	`pipeline.png`（Pipe管网设施）	维护者指派
监测点	`monitoring.png`（Pipe预警处置）	维护者指派
事件定位	`emergency-event.png`（Pipe应急指挥）	维护者指派
应急资源	`resource-asset.png`（Q图标规模种类）	维护者指派
窨井/井盖	`manhole.png`（紫色网格球）	此图形专指井盖，不得移作他用
燃气/供水/排水	火焰/水滴/水波	行业筛选
状态八桶	`status-*.png`	见 §4.2 色表

变更语义映射须维护者确认并更新本表。

7. 尺寸基准

落点	图标	说明
面板小标题	17u	配 15.5u 标题字
行业筛选按钮	14u	配 11.5u chip 字
地图状态行	14u	与 StatusTag 同行
无地图位置浮块	14u	—
地图摘要 chip	14u	inline-flex 保证图文同行
品牌位	高随顶栏（52u）等比	`主标题.png` 自带文字，HTML 标题 sr-only
地图位置符号	宽 27（点）/ 21（设备），高按母版比例 1.257	批次 3；走查反馈放大 50%（原 18/14）；billboard 尖端锚定，标签在图标上方（间距 2px）、限宽 = 图标宽 × 1.1

字号统一走 token（--fs-caption/body/title/heading），新组件禁用裸像素字号（存量已清理到 ≤12u 一档）。

7.1 位置符号标签规范（批次 3 走查定稿）

贴近：标签 pixelOffset = -(图标高 + 2px)——BOTTOM 锚定下从尖端向上画，标签贴着图标上沿（旧中心锚定的 -13 已废）。
限宽：最宽 = 图标宽 × 1.1（左右各超 5%）；超宽按估算字宽截断加 …（mapTextLabel 的 maxWidthPx）。
偏移与限宽都由合成计划层（markerPlan.js）产出（labelOffsetY / labelMaxWidth），消费方不自己算。

8. 已知边界与后续

icon.blank（空面板占位）仍是 temporary——设计稿无对应物，缺口在票 06 清单。
批次 3（位置符号）素材已备齐：water-point/drainage-point/gas-point/manhole-point.png（246×114）+ 备用目录的 T_MarkPoint_White/WhiteFull 白母版。接入按规格 10 的合成计划层，不适用本文的「直接引用」流程（需先过 token 着色批次 2）。
装饰类素材（brand-glow-*、面板四角、选择框背景）归批次 5，暂未消费。
Texture/Icon 中约 90 张 I/Q 系列未启用（水质/气体/能耗/气象等），批次 2 KPI 配图可直接复用 §4.2 染色管线。

icon-usage-consensus.md 9.8 KB Historia Czysty