图表设计
创建自包含的 HTML 文件，其中包含内联 SVG 和编辑风格系统。
45 种视觉类型。语义模式描述行为；类型引用描述布局。
0. 首次设置 —— 风格指南关卡
在新项目中生成第一个图表之前，请验证风格指南是否已定制。
不要在品牌项目中悄悄输出默认皮肤样式的图表。
首先，根据 references/profiles.md 解析任何项目中的 .diagram-design 标记；成功解析的标记会选择其配置文件并绕过此关卡。该引用负责处理失败、受保护的默认配置以及保存行为。
打开 references/style-guide.md 并检查默认令牌。如果它们仍是默认发货值（背景纸色 #f5f5f5，墨色 #2d3142，强调色 #bf4520），请暂停并向用户询问：
“这是您在此项目中的第一个图表，而风格指南仍是默认值。要立即自定义吗？选项：(a) 网站 URL，(b) 已安装的技能，(c) 本地文件夹/设计系统，(d) 粘贴令牌，(e) 保留默认值，(f) 加载保存的配置文件。”
然后根据 references/onboarding.md 的相应部分进行分支；对于 (f) 选项，请遵循 references/profiles.md。
一旦风格指南被自定义（或用户明确选择了默认值），后续运行中将跳过此关卡。一个头部配置文件名称表示已复制并激活的配置文件。如果没有头部，任何与发货默认值不同的语义角色值或排版字体系列意味着已自定义但未保存：跳过关卡并提供保存为配置文件的选项。所有默认令牌且没有标记或头部的情况会触发关卡。完成入门流程后，提供将当前设置保存为命名客户端配置文件的选项，具体参考 references/profiles.md。
1. 设计理念
最高质量的操作通常是删除。
应用于示意图：
- 每个节点代表一个独特概念。两个总是同时出现的节点应合并为一个节点。
- 每个连接都应承载信息。如果布局已清晰表达关系，则移除连线。
- 珊瑚色是编辑强调色，而非信号标志。 每个图表中 1–2 个焦点节点。在 5 个节点上使用它会抹杀信号的区分度。
- 示意图不是在所有内容都添加后完成，而是在无法再移除任何内容后完成。
目标密度：4/10。 足够技术上完整，但又不至于密集到需要指南。超过 9 个节点，很可能应拆分为两个图表。
2. 何时使用
适用于 45 种视觉类型中的任何一种（见第 3 节），当读者通过视觉而非散文、表格或项目符号列表能学到更多时使用。
不适用于：
- 快速的 Unicode 图表 → 使用独立的纯文本工具，如 wiretext。本技能不提供此类工具。
- 事物列表 → 表格或项目符号。
- 仅属性对比的“前后” → 表格；拓扑变化 → 架构差异图。
- 单一形状的“图表” → 直接写一句话。
在绘制之前，请思考：读者能从此图表中学到比一段写得很好的段落更多的东西吗？ 如果否，则不要绘制。
3. 选择：先语义模式，后视觉类型
当行为、状态、强制措施或风险传递含义时，首先加载 references/semantic-patterns.md 并选择一个主要模式。然后选择最接近的视觉类型来布局。如果没有匹配的模式，直接选择类型。
| 行为触发条件 | 语义模式 → 最接近的类型 |
|---|---|
| 扇入、队列深度、有限容量、瓶颈 | 扇入队列 / 瓶颈 → 数据流图 |
| 跨阶段重复出现的问题/输入/治理/输出槽位 | 具有语义槽的阶段框架 → 流程图 |
| 对话或松散输入变为结构化的持久化工件 | 非结构化输入 → 结构化工件 → 数据流图 |
| 两条规则痕迹需要显示通过/失败/跳过/未达及首次分歧点 | 成对策略评估痕迹 → 流程图 |
| 信任边界及被允许/禁止的入口或部署路径 | 安全铺就路径 → 架构图 |
| 按实施位置分组的控制措施 | 治理/控制目录 → 层级堆叠图 |
| 防御措施弥补先前漏洞，残余风险传播 | 补偿性安全层 → 层级堆叠图 |
| 层级化、ID 可寻址的分解，每个模块需 I/O、约束条件和代码链接 | 可追溯模块分解 → 树图 |
| 一个主体经历阶段、等待、重试、取消和最终结果 | 生命周期阶段图 → 状态机图 |
模式拥有语义原语和更严格的预算；类型拥有布局语法。仅当请求运动效果或实质上阐明有序变化时才使用 references/animation.md；默认情况下静态图表为首选。
视觉类型指南 (45 种)
| 如果你要展示… | 使用 | 参考 |
|---|---|---|
| 组件及其连接在一个快照中；嵌套的管理与流量范围 | 架构图 | type-architecture.md |
| 同步的“之前”/“之后”拓扑之间的结构变化，附带变更账本 | 架构差异图 | type-architecture-delta.md |
| 按阶段或部门划分的遗留 IT 现状；显示之前状态 | IT 现状图 | type-it-state.md |
| 带有分支的决策逻辑 | 流程图 | type-flowchart.md |
| 参与者之间按时间顺序的消息传递 | 时序图 | type-sequence.md |
| 状态 + 转换 + 守卫 | 状态机图 | type-state.md |
| 实体 + 字段 + 关系 | ER / 数据模型图 | type-er.md |
| 按时间定位的事件 | 时间线图 | type-timeline.md |
| 跨职能流程及交接 | 泳道图 | type-swimlane.md |
| 双轴定位/优先级排序 | 象限图 | type-quadrant.md |
| 多个实体在 3–5 个定量标准上的评分 | 雷达 / 蜘蛛图 | type-radar.md |
| 跨循环类别的一个定量序列；角度=类别，半径=幅度 | 极坐标图 | type-polar.md |
| 增强循环；最后一步反馈给第一步，且一个枢纽累积状态 | 循环图 | type-loop.md |
| 通过包含关系/范围展示的层级结构 | 嵌套图 | type-nested.md |
| 父 → 子关系 | 树图 | type-tree.md |
| 人/代理人/团队的所有权、汇报关系、路由、升级 | 组织架构图 | type-org-chart.md |
| 堆叠的抽象层级 | 层级堆叠图 | type-layers.md |
| 将一个物体的各部分沿一个轴拆开：拆解、开箱、组装顺序 | 分解轴测图 | type-exploded.md |
| 从上方角度看到的某一层或场地：带家具的房间，按阶段划分的建筑物 | 轴测平面图 | type-axonometric-plan.md |
| 集合之间的重叠 | 韦恩图 | type-venn.md |
| 排序层次或转化漏斗衰减 | 金字塔 / 漏斗图 | type-pyramid.md |
| 跨类别的定量比较 | 条形图 | type-bar.md |
| 从一个起始总数通过有符号贡献（预算桥梁、人员变动增量）桥接到结束总数 | 瀑布图 | type-waterfall.md |
| 整体的一部分，其中相对大小是叙事重点 | 树地图 | type-treemap.md |
| 交叉制表数据；填充颜色编码每个单元格的值 | 热力图 | type-heatmap.md |
| 随时间变化的连续趋势，两个状态之间的变化（斜率图），每个系列的一个分布（山脊图），或跨多个快照的排名变化（凹凸图） | 折线图 | type-line.md |
| 时间线上的任务和阶段 | 甘特图 | type-gantt.md |
| 两个变量的相关性或分布；气泡图（三个变量）、蜂群图（一个变量，每项一个点）、箱线图（每组五个数值摘要）变体 | 散点图 | type-scatter.md |
| 容器集群上的端到端数据栈 | 高层级图 | type-high-level.md |
| 多参与者顺序流程及数据交接 | 流程图 | type-process.md |
| 具有质量级别和访问策略的多层数据存储 | 奖章图 | type-medallion.md |
| 角色限定的数据流：谁在每个管道步骤做什么 | 数据流图 | type-data-flow.md |
| 数据平台的集成拓扑 —— 数据源 → 核心 → 消费者 | DP 集成图 | type-dp-integration.md |
| 按角色/组件的访问权限矩阵 | DP 安全矩阵图 | type-dp-security-matrix.md |
| 跨阶段分合的数量，带宽 = 数量 | 桑基图 | type-sankey.md |
| 一个观察到的结果的原因，按类别分组（根因分析） | 鱼骨图 | type-fishbone.md |
| 价值链条对抗演变 —— 要构建什么、购买什么、什么在变化 | Wardley 地图 | type-wardley.md |
| 按状态划分的进行中工作，附有 WIP 限制和阻塞项 | 看板图 | type-kanban.md |
| 一个人在体验的不同阶段做什么，以及感受如何 | 用户旅程图 | type-journey.md |
| 客户做什么与后台隐藏什么，跨阶段，附有可见性分界线 | 服务蓝图 | type-service-blueprint.md |
| 软件运行的位置 —— 区域、主机、制品、副本、端口 | 部署图 | type-deployment.md |
| 什么依赖什么，包含树无法表达的扇入关系和循环 | 依赖关系图 | type-dependency.md |
| 带有操作、继承、组合的类（其他 UML 路径请参见别处） | UML 类图 | type-uml-class.md |
| 按发布切割的叙事骨架，附有切割线 | 故事地图 | type-story-map.md |
| 物理表：SQL 类型、约束、索引、列级外键 | 数据库模式图 | type-db-schema.md |
经验法则：
- 如果三列表格能传达相同信息，选择表格。
- 如果两种类型似乎都可用，选择主导轴；语义模式可能添加特定行为原语，而非第二套布局语法。
- 如果你超出了复杂度预算（第 7 节），拆分为一个概览加一个细节。
在绘制之前，务必加载指南中链接的所选类型参考。 当通过模式路由时，还需加载 semantic-patterns.md；当选择了动画，加载 animation.md。
绘制前确认
在渲染之前，用一条简短消息陈述计划：选定的视觉类型（如果通过模式路由，也需包含语义模式）、尺寸预设，以及复杂度预算（第 7 节）将强制移除的任何内容。如果用户可以联系到，让他们在绘制前重定向；否则继续，并在交付物旁边注明假设。仅当请求已明确指定类型、尺寸和内容时才跳过暂停。
4. 通用不良实践模式
以下标记为任何类型的“AI 杂乱”示意图：
| 不良实践模式 | 失败原因 |
|---|---|
| 深色模式 + 青色/紫色发光 | 看起来“技术化”但缺乏设计决策 |
| JetBrains Mono 作为通用的“开发者”字体 | 等宽字体适用于技术性内容 —— 端口、命令、URL。名称应使用 Geist 无衬线字体。 |
| 每个节点使用完全相同的矩形框 | 抹杀了层级关系 |
| 浮在图表区域内部的图例 | 与节点冲突 |
| 没有遮罩矩形的箭头标签 | 文字穿过线条显示 |
箭头上的垂直 writing-mode 文本 | 无法阅读 |
| 3 个等宽摘要卡片作为默认布局 | 通用网格 —— 变化宽度 |
| 任何元素上的阴影 | 阴影已过时。边框更流行。 |
矩形框上的 rounded-2xl | 最大圆角 6–10px 或不用 |
| 在每个“重要”节点上使用珊瑚色 | 珊瑚色是 1–2 个编辑强调色，而非信号系统 |
| 复现 Mermaid 渲染器的布局 | 导入自动间距和路由，而非进行编辑性布局 |
| 任何违反第 6 节六条连接器规则的行为 | 自动失败：对角线倾斜、标签接触线条、遮罩被后续节点裁剪、路径重叠、共享附着点、穿梭于非端点框后方 |
类型特定的不良实践模式位于指南链接的每个类型参考文件中。
5. 设计系统
设计系统是可换肤的。 references/style-guide.md 是颜色、排版、代币和默认调色板的唯一真相来源；此文件命名了语义角色（paper、ink、muted、accent、link……）。要应用品牌，编辑 style-guide.md 或运行 references/onboarding.md 中基于 URL 的流程。
当下方规范或类型参考中提到“ink”、“accent”、“muted”等时，请在
style-guide.md中查找当前的十六进制值。
类型参考片段将角色写为占位符：{ink}、{ink @ 0.40} 表示某角色以某不透明度使用，以及 {node-name}、{sublabel}、{eyebrow}、{arrow-label}、{title}、{callout} 表示字体。在输出之前，请针对 style-guide.md 解析所有占位符。
语义角色（一览）
| 角色 | 用途 |
|---|---|
paper，paper-2 | 页面背景和容器背景 |
ink | 主要文本/描边 |
muted，soft | 次要 |
…
[已截断以翻译]