diagram-design 布局语法扩展实录：解读 ADR 0007 中 28 → 38 的十种新图形类型

diagram-design 布局语法扩展实录解读 ADR 0007 中 28 → 38 的十种新图形类型【免费下载链接】diagram-design38 editorial diagram types for Claude Code, Codex, and Pi. Self-contained HTML SVG. No shadows. No Mermaid slop.项目地址: https://gitcode.com/GitHub_Trending/di/diagram-design本仓库diagram-design是一个为 Claude Code、Codex、Pi 等 Agent 设计的图形设计技能skill它把 39 种可视化类型visual type以自包含的 HTML SVG 形式输出遵循一套无阴影、无 Mermaid 渲染器风格的编辑型设计系统。本文围绕 docs/adr/0007-new-layout-grammars.md 展开解释这套仓库如何以 ADR 为机制、以布局语法layout grammar为标尺一次性把可视化类型从 28 种扩到 38 种并逐一说明每种新类型的语法定义、与既有类型的边界、被拒收的候选以及由此带来的工程约束。读完本文你将掌握这套仓库判断何时该新增一种图形类型、何时只该新增一个语义模式的完整决策框架并能在实际画图时准确路由到 38 种类型中的正确那一种。一、背景为什么这次扩张不是加十个图例那么简单ADR 0007 的Status: accepted (v2.5.10)标题本身就是它的论点Ten new layout grammars (28 → 38 visual types)。要理解这次扩张必须先回到 docs/adr/0002-semantic-patterns-do-not-expand-the-taxonomy.md 定下的规则Behavior is a separate axis.The visual-type count only moves when a genuinely newlayoutgrammar appears.换句话说在这套体系里存在两条正交的轴行为轴behavior系统做什么——队列、瓶颈、策略追踪、信任边界等由 references/semantic-patterns.md 中的语义模式负责每个模式只路由到最接近的既有可视化类型做布局绝不新增类型布局轴layout信息如何排列——只有当出现一种既有任何类型都无法表达的、真正全新的布局语法时才允许新增一个类型。ADR 0007 记录的就是后者的第一次大规模兑现经过三次覆盖率审计有十个图形用任何既有语法都画不出来于是以十个新类型补齐。这也是为什么这次扩张被称为28 → 38而不是27 → 37——在此之前的 v2.6 时代Treemap 已按 ADR 0002 的逃逸条款escape clause把计数从 27 推到 28。三次审计的具体内容在 ADR 中有明确交代第一次把本技能与 Mermaid 2026 分类法29 种图加当时实践者的写作对照第二次过了一遍 20 项的请求清单覆盖架构、流程、API/集成、数据库、过程类图形第三次覆盖 UML、story mapping 和物理数据库图。三次审计共同得出结论有十个图形在既有 28 种语法下无法绘制。ADR 把每一个都配上了当时不存在的语法和最接近的既有类型、以及它为何失败的双列论证——这是 ADR 0002 定义的准入门槛bar的逐条举证。二、十种新类型的核心决策表ADR 0007 的决策部分是全文的信息核心这里完整继承并展开解释类型当时不存在的语法最接近的既有类型以及它为何失败Sankey带宽编码一个会分裂和合并的量Pyramid 只展示漏斗递减、不展示分裂/合并process 展示步骤、不展示数量Fishbone倾斜的分类骨线汇聚到一个结果Tree 是父→子而不是以固定角度、带子因刻度的因果→结果Wardley map两个有序轴价值链 × 演化带依赖链接和移动Quadrant 能定位条目但没有依赖链也没有演化带Kanban按列统计状态、带 WIP 限制且无任何连接线Swimlane 是泳道加一条横穿的流看板刻意没有流User journey阶段网格加上一条作为承重元素的情绪曲线Timeline 把事件放在轴上折线图画的是数据二者都不承载逐阶段的行Deployment物理放置区域→主机→带版本号的制品含副本数和 protocol:port 路径Architecture 是逻辑组件与关系high-level 是单一固定堆栈形状不是任意环境拓扑Dependency graph一个节点有多个父节点、且能表达环的排秩 DAGTree 在结构上同时禁止两者——每节点单父、无回边UML class三格盒子带操作列表加上箭头头部承载语义的类型化关系词汇三角、实心菱形、空心菱形ER 没有操作格也没有继承或归属语义Story map按叙事排序的主干被发布切片横切带发布切线Kanban 的列是状态而非叙事顺序且它不切片journey 承载情绪而非范围Database schema外键锚定列行到列行带 SQL 类型、约束 chip 和索引区ER 只连接盒子、止步于基数——它无法指向某一列这张表的每一行都是新语法的独特性证明。它同时也是 skills/diagram-design/SKILL.md §3 可视化类型指南中对应行项的来源——SKILL.md 里 38 种类型各有一行 If youre showing… Use… 的指引并链接到各自的类型参考文档。三、各类型的语法实质从 ADR 到类型参考的落地ADR 给的是为什么而每个类型参考文档skills/diagram-design/references/type-*.md给出怎么画。这里按 ADR 表的顺序把每个新类型的语法骨架与典型场景对照说明——这些文档也是实际绘制时必须加载的规范。3.1 Sankey流量-数量图语法核心是带宽携带数据。在 type-sankey.md 中严格3 个阶段列从左到右节点是实心ink填充、无描边的竖条高度正比于通过它的数量并圆整到 4px 网格流是填充的 ribbon不是描边线每条流是一个闭合path顶边从源节点顶偏移到目标节点顶偏移做三次贝塞尔两个控制点都放在两列之间的水平中点C midX,y0 midX,y1 targetX,y1这是 ribbon 能水平插进竖条的关键永不画箭头——方向由列序隐含这是对 SKILL.md §6 正交肘线规则的显式豁免配色上普通流用muted 0.18唯一的编辑焦点路径用accent 0.28一条焦点路径跨多段 ribbon 仍只算 1 个 accent 元素严禁按流涂彩虹色。它还给出了完整的比例尺规则全图用同一个kpx/单位每列节点高度之和必须相等总进总出Sankey 一望即知的可信度来源圆整误差不得超过一个 4px 步长且任何会圆整到 4px 以下的流并入 other 带而不是画成隐形细线。文档里的算例k 0.02预算 12,000 分钟 CI 时间直接对应 example-sankey.html 的内容。3.2 Fishbone鱼骨图 / Ishikawa语法核心是以固定角度收敛的斜骨线。type-fishbone.md 给出水平脊线spineink1.2px从左侧贯穿到右侧的效果盒分类骨线以固定 60°交替上下排列每条骨线的远端挂一个rx4的分类标签盒子因是沿骨线固定分位点m/6m 2, 4伸出的 32px 水平短刻度线60° 斜线豁免§6 的正交肘线规则但豁免仅限骨线和子因刻度图中的任何其他连接线如标注引出线仍必须用圆角正交肘线焦点规则确认的根因骨线及其标签、加上效果盒正好用完 2 个 accent 预算。文档甚至给出了精确的几何公式attach_x(k) HEAD - 160 - k*160far端点dx-96, dy∓168和一张 5 骨线预计算表并论证了为什么在默认画布HEAD1200上第 6 根骨线必然裁切——要画 6 根必须同时加宽HEAD和 viewBox 宽度各至少 160。这类几何证明式的预算论证是本仓库类型参考的一大特征。3.3 Wardley Map沃德利地图语法核心是两轴定位 依赖线 移动箭头。type-wardley.md 规定Y 轴是价值链顶部对用户可见到底部不可见X 轴是演化四带Genesis | Custom-built | Product | Commodity轴标签以水平堆叠的text行书写永远禁止writing-mode竖排文字组件是r6圆点 12px 上方的 Geist sans 标签依赖链接是细muted直线这是文档化的第二个 §6 豁免——点在图上的位置本身就是数据强行套正交肘线会错位移动箭头只允许指向右方向左是矛盾而非设计选择accent虚线箭头上的文字标签只有在箭头无法自述的信息如BY Q3、VENDOR LOCK-IN时才允许出现文档还用具体坐标移动组件在(420,156)、依赖线在x441.7–482.5区间交叉演示了为什么移动箭头旁通常放不下标签是典型的编辑判断与几何约束的交叉验证。3.4 Kanban看板语法核心是无连接线的状态普查。type-kanban.md 反复强调看板图里一个箭头都不能有——只要有箭头它就不是看板而是泳道或流程。规范包括最多 5 列等宽240px列底ink 0.02每列头部右侧一个rx2矩形WIP chip写n/limit入队列和终列无限制、只写裸n卡片是 §6 节点盒模式rx6宽列宽减 32px高 56px间距 12px标题 Geist sans TICKET-ID · owner副标签四种卡片状态是本类型的语义词汇表default白底 ink 描边、blockedaccent 0.05 底 accent 虚线 左侧 4px accent 竖条、waiting/externalink 0.02 底 淡虚线、doneink 0.05 底 muted 描边——这四态直接复用 SKILL.md §5 的节点处理表而非另造一套配色超限列n limit的 WIP chip 描边和文字转 accent加一张阻塞卡正好用完 2 个 accent 预算。3.5 User Journey用户体验旅程图语法核心是情绪曲线作为承重元素。type-journey.md 的结构是自上而下的纵向堆叠阶段头最多 6 列、160px 高的情绪带、最多 3 条内容行ACTIONS/TOUCHPOINTS/ 可选指标或负责人行。情绪带里有 3 条参考参考线HIGH / NEUTRAL / LOW平滑的muted1.5px 折线穿过每阶段一个r5圆点值只能吸附到 5 个有序档位之一HIGH / MED-HIGH / NEUTRAL / MED-LOW / LOW绝不允许数值化情绪轴也禁止 emoji情绪折线是数据曲线而非节点间的连接线这是第三个 §6 豁免仅限该曲线本身痛点标记pain marker在情绪跌落的阶段下方放一个虚线标签盒最多 2 个且只在谷底焦点规则谷底圆点 入线段算 1 个 accent其痛点标记算第 2 个如果每个阶段的情绪都差不多、叫不出感受那就去画 Process 或 Timeline——文档把没有情绪曲线直接列为头号反模式。3.6 Deployment部署拓扑图语法核心是物理放置区域→主机→制品。它回答软件在哪里运行与回答逻辑上如何连接的 Architecture、回答单一固定堆栈的 High-Level 是三条不同的路。预算最多 3 个区域 / 6 个节点 / 8 条路径 / 9 个制品制品携带版本号路径携带protocol:port副本数以可见的形式出现。3.7 Dependency Graph依赖图语法核心是树结构无法表达的两件事多父节点与环。type-dependency.md 把布局定义为按依赖深度排秩ranked layers秩 0 在最上无人依赖它的入口点前向边跨秩向下秩行间距 120px。每个节点右上角带一个 Geist Mono 8pxfan-in 徽章如4 in展示有几个节点依赖它——最高 fan-in 的节点就是本图的结构主角最多一条回边向上指它是整张图的编辑焦点accent描边、虚线5,4、accent箭头必须绕节点堆外侧走、绝不允许穿过中间并带一个CYCLE标签被环触及的两个节点本身保持常规处理不染 accent2 个 accent 预算只给回边 其标签反模式清单里第一条就是数据其实是树处处单父、无环却硬画依赖图——那种情况应明确改用 type-tree.md。3.8 UML ClassUML 类图语法核心是三格盒 箭头头部语义。type-uml-class.md 规定每个类是单个盒子rx6由全宽细线分成至多三格名称接口带«interface»stereotype、抽象类斜体、属性 name: Type/-/#可见性标记、操作 method(arg): Return某格为空则该格省略绝不补齐等高。类型化关系词汇是它的招牌实线 大空心三角 继承虚线5,4 空心三角 实现实线 实心菱形在拥有者端 组合实线 空心菱形 聚合实线 普通箭头 关联两端都写多重性虚线4,3 箭头 依赖。六个标记全部要放进defs并在图例中展示——图例就是该类型完整的语法参考书。它还内置了一张UML 家族路由表序列图、状态机、组件、部署、活动图、概念 ER 分别路由到本仓库的哪个类型避免一个 UML 衍生出六个类型。3.9 Story Map用户故事地图语法核心是叙事主干 × 发布切片 切线。它的列是叙事顺序而非 Kanban 的状态行是发布切片中间有一条**发布切线release cut line**切出本次发布范围。预算最多 5 个活动 / 3 个切片 / 12 张卡。3.10 Database Schema数据库 schema 图语法核心是列到列的外键 物理类型。type-db-schema.md 是 ER 的对立面表盒分头部带schema.table名称 TABLE类型标签、固定 24px 行高的列行列名 Geist sans 左对齐、SQL 类型 Geist Mono 9px 右对齐、PK/FK/UQ/NN约束 chip 居中、可选的INDEXES索引区以及超预算时的 N more columns溢出行绝不静默截断外键边锚定到列行的垂直中心用正交圆角肘线路由每条边都带ON DELETE CASCADE / RESTRICT / SET NULL标签同一行上多条 FK 要围绕行中心做 ±8px 对称错位满足 §6 规则 4 的≥12px 附着点间隔焦点规则唯一破坏性 FKON DELETE CASCADE的边标签算 1 个 accent它级联进入的那张表的头部带仅头部用accent-tint算第 2 个schema 里没有破坏性 FK 就不设焦点元素反模式第一条就是把每张表的每一列都画出来——schema 图是对子系统的论证不是\d转储。同时ER 的类型参考在本次 ADR 中被收窄而非复制type-er.md 现在明确声明自己只做实体级连接盒子、带基数并指向 type-db-schema.md 承接物理 schema。ADR 明确记录没有这个编辑两个类型的 Best for 声明会重叠、路由表会变得含糊。四、被拒收的候选为什么这些请求没有变成类型ADR 0007 专门用一节记录被拒收及理由Rejected, with reason目的是让下一次审计不必重吵一遍。第一类已被既有类型覆盖——请求命名的是用例不是语法。被请求的图被谁覆盖系统上下文 / 组件 / API 交互Architecture边界或缩放级别不是新语法UML 序列 / 请求生命周期 / 序列状态组合SequenceUML 状态机StateUML 活动图Swimlaneflowchartfork/join 条本身不足以换取一个类型UML 组件 / UML 部署Architecture、deployment数据流图DFDData flow事件流生产者→代理→消费者Data flow经由 fan-in queue / bottleneck 语义模式见 ADR 0002集成图DP integration数据模型 / 概念 ERER决策树Flowchart第二类在 ADR 0002 准入门槛或编辑适配性上被拒。C4context / container / component——只是架构语法上的缩放级别约定不是新语法属于语义模式范畴AI-agent / RAG 架构——同样是盒子加箭头加决策环是架构上的模式而非布局思维导图Mindmap——树的一种径向改述同样的信息、同样的语法、不同的投影UML use case——真实语法但椭圆不承载结构、且成品很少能通过编辑裁剪饼图 / 甜甜圈图——仓库自己的规则任何清单→表格已将其否决Git 图与数据包 / 位域图——真实语法但受众窄、编辑适配弱只在有需求时再议Treemap——曾被本 ADR 拒收后来在 #87 按 ADR 0002 的逃逸条款落地28 → 38 的计数把它包含在内。这一节的启示是有人要这张图不等于需要新类型。绝大多数需求在现有 38 种类型加 7 个语义模式的路由下都有落点。五、后果与工程约束计数、豁免、字节上限与文档同步ADR 的 Consequences 部分是本次扩张的工程账本每一条都能在仓库里找到对应实现。5.1 可验证的计数38 被硬编码进测试加类型必须是有意识的一次编辑ADR 明确可验证的计数移动到 38。verify-docs-sync.py和verify-semantic-motion.py都硬编码它——这是有意的加一个类型必须是刻意的编辑而不是静默漂移。仓库实现印证了这一点scripts/verify-docs-sync.py 中VISUAL_TYPE_COUNT 39截至 v2.6 已包含后补的 Polar即 38 1并且check_type_counts()会扫描所有路由表面routing surface——SKILL.md 描述与类型指南——禁止任何文件以数字形式硬编码类型计数违者报错。这形成了一个闭环类型计数只能存在于verify-docs-sync.py/verify-semantic-motion.py两个权威计数器里任何 PR 改动它而不修改 ADR 0002/0007 的修订记录就是在静默地让自己成为权威。ADR 0002 的修订段把话说得很直白如果某 PR 改了这两个计数器却没有修订本 ADR那么测试里的数字就只是最后一位贡献者随手敲进去的。5.2 四个有记录的 §6 豁免每个都被圈定在单一元素上十种类型中有四种携带对 SKILL.md §6 规则 1强制正交肘线的有记录、窄范围豁免类型豁免元素Sankeyribbon 本身区域编码非连接线且永不画箭头Fishbone60° 骨线仅骨线和子因刻度Wardley map依赖链接直线点在图上位置即数据User journey情绪折线数据曲线非节点间连接线其余六种完全遵守 §6Kanban 和 story map 干脆没有任何连接线天然无涉。每个豁免都写在自己的类型参考里、只覆盖那一类元素——例如 fishbone 的标注引出线、wardley 的移动箭头标签遮挡检查仍然要遵守通用连接线规则。5.3 ADR 0004 字节上限变成硬约束SKILL.md 被压到 ~39.2 KBSKILL.md 每次技能调用都会载入 Agent 上下文所以 docs/adr/0004-skill-md-byte-cap-and-trigger-rich-description.md 把上限MAX_SKILL_BYTES定为 40,000 字节由verify-semantic-motion.py强制。新增十种类型意味着 SKILL.md 必须瘦身ADR 记录了具体裁剪手法§11 的导入后果段落被压缩terminal 变体与排版段落被收紧§4 的六行连接线反模式表格折叠成一行、指向 §6 全文——因为那张表是对 §6 规则的第三处重复陈述而 §9 已逐条核对过 §6。结果是 SKILL.md 落在 ~39.2 KB距离上限不足 800 字节。ADR 立下规矩下一个类型必须用同样的方式买单永远不许裁剪 frontmatter 的 description 来凑字节——因为 description 是 Agent 在决定加载技能之前唯一能看到的文本删掉类型名等于删掉触发技能的词汇钩子。5.4 预算行保留在 SKILL.md §7而不是搬进类型参考每个类型的复杂度预算行如 sankey 的3 / 8 / 12、fishbone 的6 bones, 3 sub-causes each、deployment 的3 / 6 / 8, 9 artifacts、dependency 的9 / 14, 4 ranks, 1 cycle、UML class 的7 / 8, 5 members per compartment、story map 的5 / 3 / 12、db schema 的5 / 8 shown / 6仍保留在 SKILL.md §7 的预算表中。ADR 解释了原因venn、pyramid、layers、ER、swimlane、timeline 等旧类型参考没有自述限制把预算行搬走会丢失这些数字。5.5 收尾从无 PNG到规范截图已发布ADR 记录验收时docs/screenshots/还没有新类型的 PNGREADME 只在文本表格里列出它们。文末的Amendment — canonical screenshots shipped补上了这一课十种类型现已拥有规范 PNG、README 中的图片网格条目以及docs/screenshots/manifest.json中的源文件/截图摘要。Polar 后来单独准入把仓库总数从 38 推到 39对应 scripts/verify-docs-sync.py 中的VISUAL_TYPE_COUNT 39与 SKILL.md 描述中的 39 种但本 ADR 记录的就是这次十类型的 28 → 38 决策本身。六、实践应用如何把这套决策框架用到你的下一次画图把 ADR 0007 与仓库现状结合起来实际的使用流程是先判断行为是否承重如果你的图讲的是队列积压、策略追踪、信任边界这类行为先读 references/semantic-patterns.md选一个主模式由路由表决定最接近的可视化类型再从 38 种里选布局对照 SKILL.md §3 的可视化类型指南If youre showing… Use…表选类型并加载链接的类型参考再动笔对照本节的反模式与预算每个新类型参考都自带反模式清单与复杂度预算如 sankey 超过 3 列就拆成两张连环图、fishbone 在默认画布上最多 5 根骨线、journey 超过 6 阶段就拆成获取/留存两段旅程把想表达的内容与语法的独特性对起来如果你要画的东西恰好命中某张表当时不存在的语法那一列——例如一条分裂又合并的数量Sankey、一个多父且有环的依赖结构Dependency graph、一份列级外键的物理表结构Database schema——那就是这十种类型的主场如果只是某个既有类型换个说法路由表会把你拉回原处。最后回到 ADR 0002 的判定准则作为本文的收束如果某个模式需要一种既有类型都没有的布局那就是新增类型的信号并且要以完整的 §10 交付集类型参考 明暗/完整三套示例 画廊标签页 路由行 预算行来交付。ADR 0007 是这句话最完整的执行样本——它既是决策记录也是这套仓库如何让类型扩张有纪律的活文档。延伸阅读ADR 0007 原文十类型决策表、拒收清单与全部后果ADR 0002语义模式与类型计数的分离原则、逃逸条款、后续 Polar 修订ADR 0004SKILL.md 40 KB 字节上限与 description 触发词规则语义模式参考行为轴的路由表与七个模式的完整规范SKILL.md§3 类型指南、§6 连接线六规则、§7 复杂度预算表新类型示例example-sankey.html、example-fishbone.html、example-wardley.html、example-kanban.html、example-journey.html、example-dependency.html、example-db-schema.html以及各自的-dark/-full变体规范截图清单docs/screenshots/manifest.json计数与同步校验scripts/verify-docs-sync.pyVISUAL_TYPE_COUNT权威值所在【免费下载链接】diagram-design38 editorial diagram types for Claude Code, Codex, and Pi. Self-contained HTML SVG. No shadows. No Mermaid slop.项目地址: https://gitcode.com/GitHub_Trending/di/diagram-design创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考