next-tjwater-drainage-frontend/ACRYLIC_DESIGN_INVENTORY.md

亚克力设计类别与组件使用清单

本文档记录当前前端的亚克力材质体系及实际使用位置。样式定义以 src/styles.css 为准，组件映射以 src/features/ 下的现有代码为准。

总览

当前材质体系分为 3 组，共 13 个语义类：

分组	数量	类别	是否使用背景模糊
外层亚克力与临时玻璃	4	导航、面板、独立控件、临时任务浮层	是
内部实体表面	4	Dock、控件面、内容凹槽、阅读面	否
语义状态表面	5	信息、正常、警告、危险、Agent 推理	否

只有第一组属于真正的亚克力或玻璃外壳。第二组用于亚克力壳层内部，保证文字、表单和密集数据不受底图干扰。第三组只表达业务状态，不承担界面层级。

1. 外层亚克力与临时玻璃

这组样式包含冷色半透明底色、饱和度、明度混合、细噪点、边框和阴影，并使用 backdrop-filter。同一区域只应保留一个带模糊的外层壳体，内部子元素应改用实体表面。

acrylic-navigation

• 用途：全局导航栏。
• 模糊：使用面板级模糊，默认 22px，浅色底图 24px，卫星底图 20px。
• 特征：保留底部分隔和下投影，不使用顶部高光。
• 当前组件：
  • WorkbenchTopBar，工作台顶部 Header。
• 文件：src/features/workbench/components/workbench-top-bar.tsx。

acrylic-panel

• 用途：承载持续显示或需要集中阅读的主要浮动面板。
• 模糊：使用面板级模糊，20px 至 24px。
• 当前组件：
  • AgentCommandPanel，Agent 命令面板外壳。
  • AgentCollapsedRail，Agent 收起状态侧栏。
  • ScheduledConditionFeed，预约任务与工况面板，通过 MAP_TOOL_PANEL_SURFACE_CLASS_NAME 间接使用。
  • LayerControl、ControlPanel、Legend、BaseLayersControl，地图工具面板，通过共享材质常量间接使用。
  • FeaturePopover，要素详情浮层，通过 MAP_FOCUS_SURFACE_CLASS_NAME 间接使用。
  • FeatureInsightPanel，要素洞察面板。
  • MapDevPanel，地图开发调试面板。
  • AlertMenu、ScenarioMenu、UserMenu，顶部导航下拉菜单。
  • MapNotice，地图通知。
• 直接或间接涉及文件：
  • src/features/agent/components/agent-command-panel.tsx
  • src/features/agent/components/agent-collapsed-rail.tsx
  • src/features/map/core/components/map-control-styles.ts
  • src/features/map/core/components/notice.tsx
  • src/features/workbench/components/scheduled-condition-feed.tsx
  • src/features/workbench/components/feature-popover.tsx
  • src/features/workbench/components/feature-insight-panel.tsx
  • src/features/workbench/components/map-dev-panel.tsx
  • src/features/workbench/components/workbench-top-bar-menus.tsx

acrylic-control

• 用途：始终悬浮在地图上的紧凑型独立控件。
• 模糊：使用控件级模糊，默认 18px，浅色底图 20px，卫星底图 16px。
• 当前组件：
  • Toolbar，地图主工具栏。
  • DrawToolbar，绘制工具栏。
  • ZoomControl，缩放控件。
  • ScaleLine，比例尺。
  • BaseLayersControl，底图切换入口与预览控件。
  • map-workbench-page.tsx 中的浮动地图控制入口。
• 使用方式：上述组件主要通过 MAP_CONTROL_SURFACE_CLASS_NAME 间接引用。
• 共享定义：src/features/map/core/components/map-control-styles.ts。

glass-transient

• 用途：短时出现、需要突出当前任务状态的玻璃浮层。
• 模糊：沿用控件级模糊，16px 至 20px。
• 当前组件：
  • AgentTaskTicker 的活动任务卡片。
• 文件：src/features/workbench/components/agent-task-ticker.tsx。
• 约束：仅用于活动任务浮条，非活动堆叠卡改用 surface-control。

2. 内部实体表面

这组样式不使用 backdrop-filter。它们用于亚克力外壳内部，通过不透明度和背景层级提高可读性，避免出现嵌套模糊。

surface-dock

• 用途：预留给固定 Dock 或侧边停靠区域。
• 当前状态：已在 src/styles.css 中定义，暂无组件直接使用。
• 适用组件：
  • 桌面端固定展开的 Agent 侧栏，前提是它从地图浮层改为占据稳定布局宽度的 Dock。
  • 固定展开的预约工况详情侧栏或图层管理侧栏，前提是侧栏长期贴边并参与工作区布局。
  • 后续可能增加的对象目录、调度队列等常驻侧栏。
• 不适用：临时弹层、悬浮工具面板、下拉菜单和可覆盖地图的短时侧栏。这些组件仍应使用 acrylic-panel。

surface-control

• 用途：面板内部的 Header、输入区域、筛选器、按钮、紧凑控制区和任务堆叠卡。
• 当前组件范围：
  • Agent 收起侧栏条目、Agent 操作摘要按钮、命令面板快捷入口。
  • 图层、量测和通用控制面板中的交互控件。
  • 预约任务面板与工况详情中的筛选器、元信息块和次级操作。
  • 任务浮条的非活动卡片。
  • 要素洞察面板的内部按钮。
  • Header 下拉菜单的内部控制区。
  • 通用 IconButton。
• 主要文件：
  • src/features/agent/components/agent-collapsed-rail.tsx
  • src/features/agent/components/agent-command-panel.tsx
  • src/features/agent/components/agent-operational-brief.tsx
  • src/features/map/core/components/control-panel.tsx
  • src/features/map/core/components/layer-control.tsx
  • src/features/map/core/components/measure-panel.tsx
  • src/features/workbench/components/agent-task-ticker.tsx
  • src/features/workbench/components/scheduled-condition-feed.tsx
  • src/features/workbench/components/scheduled-condition-detail-panel.tsx
  • src/features/workbench/components/feature-insight-panel.tsx
  • src/features/workbench/components/workbench-top-bar-menus.tsx

surface-well

• 用途：低密度内容区、空白支撑区、未选中的面板条目和内部凹槽。
• 当前组件：
  • LayerPanel、LayerControl 的未激活条目。
  • MeasurePanel、DrawToolbar、AnnotationPanel 的内部区域。
  • ControlPanel、Legend、BaseLayersControl 的分组与空白区域。
  • Header 下拉菜单的普通菜单项。
• 使用方式：部分组件直接引用，部分通过 MAP_READABLE_SURFACE_CLASS_NAME 间接引用。

surface-reading

• 用途：消息、报告、表单、属性列表、时间线内容和其他密集阅读区域。
• 当前组件范围：
  • Agent 消息详情、操作摘要、UI Envelope 内容和命令面板空状态。
  • 预约任务列表、工况详情、KPI、报告内容与下拉列表。
  • 要素洞察、属性列表和底图名称标签。
  • Header 下拉菜单中的详情块与空状态。
• 主要文件：
  • src/features/agent/components/agent-command-panel.tsx
  • src/features/agent/components/agent-message-details.tsx
  • src/features/agent/components/agent-operational-brief.tsx
  • src/features/agent/components/agent-ui-envelope-renderer.tsx
  • src/features/workbench/components/scheduled-condition-feed.tsx
  • src/features/workbench/components/scheduled-condition-detail-panel.tsx
  • src/features/workbench/components/feature-insight-panel.tsx
  • src/features/workbench/components/feature-property-list.tsx
  • src/features/workbench/components/workbench-top-bar-menus.tsx
  • src/features/map/core/components/base-layers-control.tsx

3. 语义状态表面

语义状态表面不使用模糊，只表达业务含义。它们不能替代 acrylic-panel、surface-control 或 surface-reading 来建立界面层级。

类名	含义	当前使用位置
material-tone-info	信息、液位等蓝色状态	FeatureInsightPanel 的雷达液位区块
material-tone-normal	正常、健康、流量或水质状态	FeatureInsightPanel 的水质、综合监测等区块
material-tone-warning	风险、告警、超声流量等橙色状态	FeatureInsightPanel 的告警与超声流量区块
material-tone-danger	严重故障或事故状态	已定义，建议用于严重事故、关键设备故障和高风险工况内容块
material-tone-agent	Agent 推理或模型建议	已定义，建议用于 Agent 解释、推理结论和建议动作内容块

未使用样式的建议落点

surface-dock

建议用于参与页面布局的常驻停靠区，而不是覆盖在地图上的浮层。现有组件中，以下场景适合在布局调整后使用：

• AgentCommandPanel 的桌面常驻模式。只有当面板固定贴左、占据稳定宽度并推动地图安全区时才使用。
• ScheduledConditionFeed 或 ConditionDetailPanel 的常驻右侧模式。适用于调度员持续对照地图与工况详情的工作流。
• LayerPanel 的常驻图层目录模式。适用于图层较多、需要持续管理的专业工作台。

如果组件仍然悬浮在地图上、可以随时关闭或与其他浮层替换，应继续使用 acrylic-panel。

material-tone-danger

建议用于已经确认的严重业务状态，不用于普通校验失败或短暂接口错误。现有组件中适合的落点包括：

• FeatureInsightPanel：要素状态为 critical、严重故障、爆管或关键设备失效时的状态说明区块。
• ScheduledConditionDetailPanel：工况风险等级为 critical，或任务状态为 error 且代表真实运行事故时的风险摘要和影响范围区块。
• MapNotice：仅在需要持续强调严重运行事故时用于通知内容区，不替换通知最外层的 acrylic-panel。
• Agent 权限或确认卡片：仅当待执行动作具有明确的高风险业务后果时使用，不能仅因提交失败就使用。

不应使用在网络请求失败、加载失败、表单校验错误等通用技术错误上。这类错误继续使用局部红色图标、边框或文字即可，避免把技术故障误读为管网事故。

material-tone-agent

建议用于明确由 Agent 或模型生成的内容，帮助用户区分事实数据、业务状态与机器推理。现有组件中适合的落点包括：

• FeatureInsightPanel 的“Agent 解释”区块。该区块目前使用 material-tone-warning，如果内容只是解释或推理而非风险告警，更适合改用 material-tone-agent。
• AgentOperationalBrief：Agent 生成的任务判断、建议动作或需要人工确认的结论区块。
• AgentMessageDetails：推理摘要、模型结论、建议方案等非原始证据内容。
• AgentUiEnvelopeRenderer：由 Agent 返回的建议面板或注册组件中的结论区块。
• ScheduledConditionDetailPanel：Agent 针对工况生成的处置建议区块。

原始监测值、设备属性、人工录入内容和系统事实不应使用该样式。即使这些内容出现在 Agent 面板内，也应继续使用 surface-reading 或对应的业务状态色。

共享类映射

地图核心组件通过 src/features/map/core/components/map-control-styles.ts 复用材质类，避免在各组件中重复写样式值。

共享常量	实际材质类	典型用途
MAP_CONTROL_SURFACE_CLASS_NAME	acrylic-control border	工具栏、缩放、比例尺、底图入口
MAP_TOOL_PANEL_SURFACE_CLASS_NAME	acrylic-panel border	图层、图例、控制和预约任务面板
MAP_FOCUS_SURFACE_CLASS_NAME	acrylic-panel border	要素详情等焦点浮层
MAP_READABLE_SURFACE_CLASS_NAME	surface-well border	面板内部低密度区域
MAP_READABLE_SURFACE_STRONG_CLASS_NAME	surface-control border	面板内部高可读控制区

自适应与无障碍规则

• data-basemap-tone="light" 会提高部分面板模糊强度，并降低导航、控件和任务浮条的背景不透明度。
• data-basemap-tone="satellite" 会提高背景不透明度、轮廓和阴影强度，压制卫星底图纹理。
• prefers-reduced-transparency: reduce 下，亚克力和玻璃表面会切换到接近不透明的背景并关闭模糊。
• 不支持 backdrop-filter 的浏览器使用同样的高不透明度回退。
• forced-colors: active 下，材质背景和边框改用系统颜色，并关闭背景图与阴影。

使用约束

1. 一个浮动区域只允许最外层使用 acrylic-* 或 glass-transient。
2. 外层亚克力内部使用 surface-control、surface-well 或 surface-reading，不要叠加第二层模糊。
3. 密集文字、表格、属性和值必须落在 surface-reading 等高可读表面上。
4. material-tone-* 只表达状态，不表达层级，也不添加模糊。
5. 新增地图控件时优先复用 map-control-styles.ts 中的共享常量。
6. 组件只负责布局、圆角和交互状态，材质颜色、边框和阴影由全局语义类统一维护。

当前待清理项

• surface-dock 可在固定 Dock 落地时启用。如果产品不计划引入参与布局的常驻侧栏，可以移除该样式。
• material-tone-danger 应等待明确的严重业务状态落点，不要为了消除未使用状态而套用到通用错误提示。
• material-tone-agent 可优先用于 FeatureInsightPanel 的“Agent 解释”和 Agent 建议内容，替代不准确的警告语义。
• Agent 面板仍有少量局部类直接使用 --surface-control、--surface-reading 或自定义透明背景。后续统一材质语义时，应评估是否迁移到对应的 surface-* 类。