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该项目将视觉样式视为可执行的 profileexecutable profiles构建在共享几何与校验契约之上。它的公开展示证明在不放松路由route、间距spacing、标签label与导出export门禁的前提下同一拓扑可以产生实质不同的视觉感受。Understand Anything印证了一条相关的产品经验——视觉多样性只有在每个界面都在回答读者的问题时才有价值而不是让图看起来更杂乱。这两条证据共同指向一个结论样式变化的本质是读者问题的变化而不是装饰层的变化。一个预设必须服务于一类明确的阅读场景并且不能以牺牲几何一致性与可校验性为代价。二、核心决策小集合、受众化身份而非样式数量竞赛Archify 的决策是不追求大而全的样式数量而是提供一小套面向受众的身份audience-specific identities它们共享同一套语义 ID、SVG 几何、引导视图guided views、导出路径与校验器。预设定位一览预设定位典型场景classic稳定的中性默认值通用技术图、日常交流signal-flow发光、动感的前向身份演示、动效展示配合animation: traceblueprint高对比工程制图式评审身份部署地图、基础设施交接、架构评审、技术文档editorial温暖的出版风格设计评审、发布说明、文档后续轮次补充这一契约在 schema 层被显式声明见 archify/schemas/README.md 第 30–33 行——visual_preset接受classic稳定默认、signal-flow发光动效演示、blueprint高对比工程评审、editorial温暖出版风格且预设只改变 viewer 样式不改变语义 ID 或几何。五种渲染器的 schemaarchitecture.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-presetblueprint] body通过两条linear-gradient绘制 1px 网格线background-size: 32px 32px精确定义网格间距深色主题变量第 204–237 行[data-presetblueprint][data-themedark]定义了--bg: #06131f、--grid: #17425a、--panel-border: #27627f等一整套以深蓝青色为基调的工程蓝配色浅色主题变量第 239–272 行[data-presetblueprint][data-themelight]使用--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、rolemenuitemradio等第 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.mjsloadDiagram()会依次执行 schema 校验、引导视图校验、关系 ID 校验与工程画像校验再读入 archify/assets/template.html 完成确定性编译。只有全部门禁通过才会写出最终 HTML。六、跨预设移动端修复1400px 画布的可读性与 720px 滑动面浏览器实测暴露出一个跨预设cross-preset的移动端缺陷一张 1400px 宽的部署画布虽然技术上是响应式的但标签在小屏幕上变得不可读。本轮对宽幅图给出了统一修复方案720px 内含滑动面宽度小于 720px 时宽幅图data-wide-diagramtrue被收进一个可横向滑动的容器SVG 保持min-width: 720px避免标签被压缩引导视图水平揭示路径引导故事在窄屏下横向滚动揭示作者编排的路径而非整体缩放固定控件保持在视口内导航、雷达、聚焦芯片等 pin 住的控件不随画布滚出视口页面本身无横向溢出body层面始终保持无水平滚动条。源码证据这些规则位于 archify/assets/template.html 的media (max-width: 720px)块第 3571 行起第 3629–3637 行html:not([data-embedtrue]) .diagram-container[data-wide-diagramtrue]启用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），仅供参考