图表设计
将图表创建为自包含的 HTML 文件，包含内联 SVG 和编辑设计系统。
支持四十五种视觉类型。语义模式描述行为；类型引用描述布局。
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 | 辅助文本、默认箭头、子标签 |
accent, accent-2 | 编辑强调色，焦点节点 |
link | 链接文本 |
positive, negative, warning, info | 语义状态 — 成功/失败/警告/信息 |
chart-1 至 chart-8 | 图表系列颜色 |
border | 边框和分隔线 |
字体大小和角色
| 角色 | 大小 | 字重 | 字体 |
|---|---|---|---|
{title} | 24px | 600 | Inter 或 Geist sans |
{subtitle} | 16px | 500 | Inter 或 Geist sans |
{node-name} | 14px | 600 | Inter 或 Geist sans |
{sublabel} | 12px | 400 | Inter 或 Geist sans |
{callout} | 13px | 500 | Inter 或 Geist sans |
{description} | 12px | 400 | Inter 或 Geist sans |
{arrow-label} | 11px | 500 | Inter 或 Geist sans |
{eyebrow} | 10px | 600 | 大写字母 |
{code} | 12px | 400 | JetBrains Mono 或 Fira Code |
间距和网格
- 基础网格单元：8px
- 节点内边距：12px（紧凑），16px（标准），20px（宽松）
- 节点间间距：16px（紧凑），24px（标准），32px（宽松）
- 子节点缩进：24px
颜色
所有颜色在 style-guide.md 中定义为 CSS 自定义属性。角色按含义引用，而不是具体数值。
6. 连接器规则
- 始终水平或垂直路由。 无对角线或曲线。
- 箭头标签必须有一个白色或
paper色的遮罩矩形，略大于文本。 - 标签不得接触连接线。 标签和线之间至少保留 4px 间隙。
- 路径不得重叠。 如果两条连接线交叉，用一个小弧形或间隙指示。
- 每个端口或节点只能有一个附着点。 无共享的附着点。
- 连接线不得在非端点的方框后面穿行。 连接线必须在可见区域内。
违反这些规则中的任何一项都会自动失败。在渲染之前，请目视检查布局。
7. 复杂度预算
单个图表不得超过以下任意一项：
- 20 个节点
- 40 条连接线
- 3 层分组嵌套
- 4 种不同的形状类型
如果超过这些限制，将图表拆分为概览图和一个或多个详图。在概览中，使用颜色或编号来引用详图。
8. 输出格式
所有图表生成为自包含的 HTML 文件，内联 SVG 在 <svg> 标签内。HTML 文件包含其自己的 CSS（内联 <style>）和 JavaScript（如果需要交互性）。
可选输出格式：
.html（默认，自包含）.svg（仅 SVG，无 HTML 包装器）.png（通过服务器端渲染或用户浏览器捕获的屏幕截图）
默认尺寸：1500x1000px，除非指定了预设。
尺寸预设
| 预设 | 尺寸 | 使用场景 |
|---|---|---|
micro | 800x600 | 嵌入文档的较小图表 |
standard | 1200x800 | 标准演示文稿或文档 |
presentation | 1920x1080 | 全屏演示文稿（16:9） |
wide | 1600x900 | 宽格式文档 |
portrait | 900x1200 | 纵向格式（报告、A4） |
9. 输入格式
此技能可以导入以下格式：
.drawio— Draw.io / diagrams.net 文件.mmd— Mermaid 文件.excalidraw— Excalidraw 文件
导入时，解析内容并转换为编辑布局，遵循设计系统和上面概述的反模式。不使用 Mermaid 的渲染器布局；相反，提取语义内容并重新布局。
10. 生命周期阶段图
对于生命周期阶段图（第 3 节中提到的语义模式），使用状态机类型，但专注于阶段、等待、重试、取消和最终结果。节点代表阶段，过渡代表阶段之间的进展。使用颜色指示状态：
- 绿色：已完成阶段
- 蓝色：当前阶段
- 灰色：未来阶段
- 黄色：等待/重试状态
- 红色：取消/失败状态
11. 块分解树
对于块分解树（第 3 节中提到的语义模式），使用树类型，但添加每个块的 I/O 端口、约束和代码链接。节点是块，具有可选的输入/输出端口和约束标签。连接代表块之间的数据或控制流。
12. 引导指南
首次使用此技能的用户应遵循以下步骤：
- 自定义样式指南：编辑
style-guide.md以匹配您的品牌颜色、字体和令牌。 - 选择一种类型：使用第 3 节的表格根据您的内容选择视觉类型。
- 加载参考：打开所选类型的参考文件（例如
references/type-architecture.md）。 - 绘制：将内容输入到指定格式中。
- 检查：在渲染之前检查反模式和连接器规则。
- 保存配置文件：可选地，将您的样式指南保存为
profiles/目录下的命名配置文件，以便将来使用。
参考文件
下表列出了此技能使用的所有参考文件。在需要时加载它们。
| 文件 | 用途 |
|---|---|
references/style-guide.md | 颜色、字体、令牌和默认调色板 |
references/profiles.md | 命名配置文件和保存行为 |
references/onboarding.md | 首次设置和引导流程 |
references/semantic-patterns.md | 语义模式及其到视觉类型的映射 |
references/animation.md | 动画规则和最佳实践 |
references/type-*.md | 特定视觉类型的布局和语法 |