视觉质量合同

将本合同应用于每个多分组 MapSpec 及每次视觉修改。它定义复杂图谱的可读性生产基线，不替代 mapspec-v1.schema.json 中的证据与隐私规则。

视觉语义

• 分组： 有边界的业务范围。每组使用可区分色系；标题是分组框内顶部居中的紧凑页签。
• 节点： 可执行或有业务意义的系统步骤。节点保持本组色系；证据状态同时通过节点边框处理和卡片左上角与图例一致的紧凑状态圆点表达。
• 条件： 分支或前置条件。使用菱形条件标记和条件标签样式，不得伪装成节点。
• 动作关系： 跨组传递或影响。使用方向标记和动作关系标签样式。
• 组内关系： 同组节点之间的关系。文字使用紧凑圆角框，不得与节点文字或跨组动作混淆。

布局与路由

• 按真实业务分流、汇合和跨组关系建模。不得为了凑版式加入空分组、无业务语义的阶段容器。
• 保留 Mermaid 原本的节点到节点避障走廊作为路由来源。压缩密集采样点并圆角化连续路径；不得把整条路径重算成全局网格路由。
• 跨组路径必须连接真实源、目标节点，目标端带箭头；同一节点多入、多出时分散端口。
• 只有穿入无关节点时才在节点附近做局部绕行。不得产生长距离噪声绕行或无意义折角。
• 分组框收紧到本组节点并集；关系路径不得撑大分组框。

标题与关系标签

• 分组页签必须居中、包含在分组框内，并与首节点保留清晰间距。长标题在页签内换行；仅该分组因实测高度不足时扩框。
• 条件或动作标签优先放在自身路径可读、独占的线段上。
• 碰撞依次按“自身路径空段、最小局部位移、短虚线回指原路径”处理。引线只表示标签已离线避让；自然贴线且可读的标签不得画装饰性引线。
• 标签不得遮挡节点、分组标题、分组框、其他标签或无关路径，也不得让读者无法判断所属关系。

交互反馈

• 悬浮路径、标签或短引线必须高亮同一条关系。条件、动作和组内关系的线与标签都应显示流动高亮。
• 详情面板按节点记忆滚动位置；详情内容滚动时关闭按钮固定。
• 拖动画布不得选中图中文字；选择节点后应将节点聚焦到可见工作区。
• 初始适配和 Fit 必须避让固定图例。图例固定为三个带标题的纵向分组：阅读说明、证据状态与操作。每个分组内部保持单行；窄视口时保留三个分组并使用横向滚动，不得折行、隐藏任一分组。

语言与固定文案

• 每个新生产 MapSpec 都显式设置 meta.uiLocale 为 en 或 zh-CN。维护中的中英文 Demo 共享相同图谱结构与证据数据，仅本地化读者可见文案；中文交付在用户未要求英文时默认 zh-CN。
• 文档语言、图谱区域名称、依赖加载失败页、阅读说明、关系图例、证据状态、操作说明、详情控制和空状态等固定 UI 必须整体本地化；业务文字保持输入语言。
• 条件使用菱形图标。图例相邻文字提供本地化语义；不得在每个条件胶囊里重复语言相关前缀。

必要视觉验收

在宣称视觉验收通过前，必须查看实际生成的复杂图谱，至少检查：

1. 多入多出端口、交叉和路径连续性；
2. 标签归属、碰撞避让和引线长度；
3. 分组框大小、标题包含与首节点间距；
4. 条件、动作、组内关系的悬浮反馈，以及任意关系线的点击钉住（同时仅一条，悬停行为不变，再次点击该线、按 Esc 或非拖动画布的空白单击可取消）；
5. 阅读说明、证据状态、操作说明与详情面板中的本地化文案，以及每个节点左上角与图例一致、清晰可见的状态点；以及
6. 初始适配与 Fit 下三个图例分组的可见性。

发现视觉缺陷时，先建立聚焦的浏览器回归再修改 renderer。以同一 renderer 重新生成代表性 Demo 与用户业务产物，随后运行完整测试套件。