Archify 视觉进化第六轮：基于契约的视觉预设体系与 Blueprint 预设的设计与实践
【免费下载链接】archifyAgent skill for beautiful, verifiable architecture, workflow, sequence,>项目地址: https://gitcode.com/GitHub_Trending/arch/archify
导读
本文是 Archify 项目视觉演化研究系列的第六轮记录，围绕"视觉预设（visual preset）"这一核心机制展开：它回答了一个关键产品问题——如何在不破坏语义 ID、SVG 几何、导出路径与校验契约的前提下，让同一张图呈现出面向不同受众的视觉身份。读完本文，你将理解blueprint预设的设计动机与视觉特征、meta.visual_preset的产品不变量，以及 1400px 宽幅画布在移动端的可读性修复方案，并掌握在仓库中验证这些契约的具体方法与命令。
一、为什么需要"契约化"的样式多样性：研究背景
本轮研究（记录于 docs/research-visual-evolution-round-6.md）从两个外部项目吸收了设计依据：
- fireworks-tech-graph：该项目将视觉样式视为"可执行的 profile"（executable profiles），构建在共享几何与校验契约之上。它的公开展示证明：在不放松路由（route）、间距（spacing）、标签（label）与导出（export）门禁的前提下，同一拓扑可以产生实质不同的视觉感受。
- Understand Anything：印证了一条相关的产品经验——视觉多样性只有在"每个界面都在回答读者的问题"时才有价值，而不是让图看起来更杂乱。
这两条证据共同指向一个结论：样式变化的本质是"读者问题"的变化，而不是装饰层的变化。一个预设必须服务于一类明确的阅读场景，并且不能以牺牲几何一致性与可校验性为代价。
二、核心决策：小集合、受众化身份，而非样式数量竞赛
Archify 的决策是不追求大而全的样式数量，而是提供一小套"面向受众的身份"（audience-specific identities），它们共享同一套语义 ID、SVG 几何、引导视图（guided views）、导出路径与校验器。
预设定位一览
| 预设 | 定位 | 典型场景 |
|---|---|---|
classic | 稳定的中性默认值 | 通用技术图、日常交流 |
signal-flow | 发光、动感的前向身份 | 演示、动效展示（配合animation: "trace"） |
blueprint | 高对比"工程制图"式评审身份 | 部署地图、基础设施交接、架构评审、技术文档 |
editorial | 温暖的出版风格 | 设计评审、发布说明、文档（后续轮次补充） |
这一契约在 schema 层被显式声明：见 archify/schemas/README.md 第 30–33 行——visual_preset接受classic（稳定默认）、signal-flow（发光动效演示）、blueprint（高对比工程评审）、editorial（温暖出版风格），且预设只改变 viewer 样式，不改变语义 ID 或几何。五种渲染器的 schema（architecture.schema.json、workflow.schema.json、sequence.schema.json、dataflow.schema.json、lifecycle.schema.json）都以$ref引用同一份visualPreset定义，保证五种图在字段层面行为完全一致。
每个预设同时要求支持深色与浅色主题，并且必须通过全部五种渲染器（renderers）的验证，外加一个真实画廊成品（live gallery artifact）作为证明。
三、Blueprint 预设：为部署评审而生的"工程制图"身份
blueprint是本轮引入的第三个预设，其视觉语言取材自传统工程制图/蓝图。它应服务于以下场景：
- 部署地图（deployment maps）
- 基础设施交接（infrastructure handoffs）
- 架构评审（architecture review）
- 技术文档（technical documentation）
视觉特征拆解
根据研究文档，blueprint 在保留既有主题、聚焦、引导故事、平移缩放与导出契约的前提下，新增了五项特征：
- 精确的 32px 制图网格（precise 32px drafting grid）；
- 方形评审面（squared review surfaces）——面板、泳道等使用更"方正"的轮廓；
- 角部套准标记（corner registration marks）——类似印刷/制图中的角标定位符号；
- 克制的边界标注（restrained boundary notation）——安全组、区域边界的标注更收敛；
- 非发光的光迹编排（non-glowing trace choreography）——区别于
signal-flow的发光动效，blueprint 的光迹不发光但保持动效可读。
源码级证据
这些特征可以直接在共享模板 archify/assets/template.html 中验证：
- 32px 网格背景（第 373–380 行）：
html[data-preset="blueprint"] body通过两条linear-gradient绘制 1px 网格线，background-size: 32px 32px精确定义网格间距； - 深色主题变量（第 204–237 行）：
[data-preset="blueprint"][data-theme="dark"]定义了--bg: #06131f、--grid: #17425a、--panel-border: #27627f等一整套以深蓝青色为基调的工程蓝配色； - 浅色主题变量（第 239–272 行）：
[data-preset="blueprint"][data-theme="light"]使用--bg: #edf7fa、--grid: #b5d5e1的浅色蓝方案，形成高对比的图纸感； - 预设徽标（第 684–686 行）：头部工具栏通过
content: attr(data-preset-badge-blueprint)展示当前预设身份，方便读者感知所处样式。
从 CSS 变量结构可以看出，预设通过[data-preset=...][data-theme=...]双层选择器隔离，与几何渲染层完全解耦——这是"契约化样式"在实现层面的直接体现。
四、产品不变量：meta.visual_preset只改变量，不改变几何
本轮研究确立了一条必须被持续保证的产品不变量（product invariant）：
修改
meta.visual_preset可以改变 CSS 变量与 viewer 材质（variables and viewer material），但绝不能改变语义 ID 或图几何。同一份 JSON 拓扑必须在每个预设下都保持有效、可探索、可导出、可测试。
实现与测试如何守护这条不变量
- 渲染入口：在 archify/renderers/shared/cli.mjs 中，
writeDiagram()将meta.visual_preset || 'classic'作为预设写入模板，svgRootAttrs()把预设输出为 SVG 根元素的data-preset属性——预设只影响这个属性与 CSS 变量，不参与坐标计算。 - 几何保持：渲染器（如 render-architecture.mjs）只消费 JSON 中的
pos、size、route等几何字段，预设字段在几何层完全不可见。 - 回归测试：archify/test/preset-tryon.test.mjs 专门守护该不变量：它对 architecture、workflow、sequence、dataflow、lifecycle 五种模式分别渲染，遍历
['classic', 'signal-flow', 'blueprint', 'editorial']四种预设（第 49 行），然后把 SVG 中唯一的data-preset属性归一化删除后比对（第 106–107 行normalize函数）——四种预设渲染出的 SVG 必须逐字节一致。这从测试层面证明了"换预设不改几何"。 - 该测试同时验证每个成品都提供读者可控的样式选择器（
#btn-preset、#preset-menu、role="menuitemradio"等，第 42–50 行），说明预设不是渲染期写死的，而是 viewer 内可实时切换的。
五、端到端证明：production-deployment 示例的 Blueprint 实战
研究文档要求"通过全部五种渲染器加一个真实画廊成品"来证明 blueprint 预设。仓库中的 archify/examples/production-deployment.architecture.json 就是这一证明载体——一个deployment-ownership工程画像的生产部署图，完整跑通 blueprint。
{ "schema_version": 1, "diagram_type": "architecture", "meta": { "title": "Production Deployment Ownership", "output": "examples/production-deployment.html", "visual_preset": "blueprint", "animation": "trace", "quality_profile": "showcase", "engineering_profile": "deployment-ownership", "views": [ { "id": "request-boundary", "label": "Request crosses the edge", "focus": ["clients", "edge", "gateway", "api_a", "api_b"], "note": "Follow public traffic into the private application network." } ] } }这份示例体现了哪些 blueprint 适用场景
- 基础设施交接：12 个组件横跨 AWS us-east-1 生产区与 eu-west-1 灾备区，含 CDN/WAF、API Gateway、私有子网、Redis、PostgreSQL、Event Bus 等，正是"部署地图"的典型内容；
- 架构评审：
boundaries声明了区域（region）与安全组（security-group）边界，connections对 HTTPS、mTLS、VPC route、跨区域 WAL 使用emphasis/security/dashed等语义变体，评审者可逐条核对路径； - 引导故事：
views定义了三个具名视图（request-boundary、state-ownership、async-operations），读者可沿作者编排的路径探索，这正是文档强调的"每个界面回答一个读者问题"。
渲染命令
在仓库根目录下，用以下命令即可端到端渲染并校验这份 blueprint 成品（需要本机 Node.js 环境）：
node archify/renderers/architecture/render-architecture.mjs archify/examples/production-deployment.architecture.json /tmp/production-deployment.html命令入口来自共享 CLI 头 archify/renderers/shared/cli.mjs：loadDiagram()会依次执行 schema 校验、引导视图校验、关系 ID 校验与工程画像校验，再读入 archify/assets/template.html 完成确定性编译。只有全部门禁通过才会写出最终 HTML。
六、跨预设移动端修复：1400px 画布的可读性与 720px 滑动面
浏览器实测暴露出一个跨预设（cross-preset）的移动端缺陷：一张 1400px 宽的部署画布虽然"技术上是响应式的"，但标签在小屏幕上变得不可读。本轮对宽幅图给出了统一修复方案：
- 720px 内含滑动面：宽度小于 720px 时，宽幅图（
data-wide-diagram="true"）被收进一个可横向滑动的容器，SVG 保持min-width: 720px，避免标签被压缩； - 引导视图水平揭示路径：引导故事在窄屏下横向滚动揭示作者编排的路径，而非整体缩放；
- 固定控件保持在视口内：导航、雷达、聚焦芯片等 pin 住的控件不随画布滚出视口；
- 页面本身无横向溢出：
body层面始终保持无水平滚动条。
源码证据
这些规则位于 archify/assets/template.html 的@media (max-width: 720px)块（第 3571 行起）：
- 第 3629–3637 行：
html:not([data-embed="true"]) .diagram-container[data-wide-diagram="true"]启用overflow-x: auto与overscroll-behavior-x: contain，同时> svg { min-width: 720px; }——画布宽度 1400px 时，SVG 按 720px 最小宽度保持标签可读，容器负责滑动； - 第 3639–3647 行：
.diagram-nav、.overview-map、.focus-chip、.route-probe、.semantic-lens、.node-finder等控件通过transform: translateX(var(--archify-scroll-x, 0px))与画布滚动同步，保证"pin 在视口内"； - 第 3571 行起的整体规则还处理了工具栏菜单定位（fixed 于视口顶部）、header 换行等细节，确保页面级无横向溢出。
这一修复是"契约化样式"的另一半：预设改变的是视觉材质，而布局容器、滑动语义与控件钉扎属于所有预设共享的 viewer 契约，因此一个修复能覆盖全部四种预设。
七、如何在自己的场景中启用与验证 Blueprint
启用方式
在你的 Typed JSON IR 的meta中声明预设即可：
{ "meta": { "visual_preset": "blueprint", "animation": "trace", "locale": "en" } }visual_preset: "blueprint"启用工程制图身份；不设置该字段时回退为classic（默认值由 cli.mjs 的meta.visual_preset || 'classic'保证）；animation: "trace"开启 blueprint 的"非发光光迹"编排；省略则完全静态；locale可选en或zh-CN，只影响固定 viewer UI、图例与无障碍文案，不翻译作者写的内容。
验证方式
- 预设切换测试：运行
node --test archify/test/preset-tryon.test.mjs，确认五种渲染器 × 四种预设全部通过，且同一 JSON 在不同预设下 SVG 几何逐字节一致（data-preset归一化后比对）； - 端到端校验：使用
validate/deliver工作流（详见 README_ZH.md 的"工作原理"与常用命令小节），--json输出结构化诊断，失败时给出精确的subject与supportedFixes； - 浏览器复核：研究文档明确指出"确定性诊断仍不等于视觉复核"，建议按 archify/test/visual-check.test.mjs 的思路在 720px 以下与桌面宽度各做一次人工/截图复核，重点检查宽幅图标签可读性与页面无横向溢出。
结语
第六轮视觉演化确立的核心理念可以浓缩为一句话：样式的价值在于为不同读者回答不同问题，而契约的价值在于让这些答案在切换时不破坏语义与几何。blueprint预设以工程制图语言服务部署评审场景，meta.visual_preset不变量配合preset-tryon回归测试保证四种预设共享同一拓扑，720px 滑动面修复则让 1400px 宽画布在手机上依然可读。这套"小集合 + 强契约 + 端到端证明"的方法论，既是 Archify 视觉体系持续演化的基石，也是任何"换肤不换骨"类产品可以借鉴的工程范式。后续轮次（如 editorial 预设的引入）也沿用了同一契约框架，详见 docs/research-visual-evolution-round-7.md 及后续研究文档。
【免费下载链接】archifyAgent skill for beautiful, verifiable architecture, workflow, sequence,>项目地址: https://gitcode.com/GitHub_Trending/arch/archify
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
