蓝图风格图表

每张静态 SVG 解释真实系统的一个机制，使用系统中的真实 ID、字段、方法、状态码与序号。图表使用浅色纸张面板和少量含义固定的色相，在屏幕和打印的 640 单位宽度下保持清晰。Claude、Cursor、Codex、OpenClaw、Hermes 及所有读取 SKILL.md 的 agent 都可使用。course-style 保存完整课程 token，本技能复制所需值，可独立使用。

适用情况

• 课程、README 或手册需要解释系统部件如何通信、存储数据或改变状态。
• 已有运行记录、日志、规范或源代码，可取得真实名称。
• 断言适合下方九种图形之一。

使用其他方式的情况

• 图表要动或响应滑块：使用 motion-figure。
• 有深度和控件的实体机器讲解：使用 isometric-explainer。
• 多个数据点的数值图：使用绘图工具。
• 没有部件的真实名称：先取得运行记录或源代码。

方法

1. 先写图表要证明的一句断言，英文最多 28 词。
2. 选一种图形；两种图形都适合时，拆为两张图。
3. 从来源收集真实参与方、字段、方法、状态码和序号。
4. 绘图前为整组图写好语义色表，见下方颜色规则。
5. 在 640 单位网格上安排布局，内容位于 x 20 至 x 620。
6. 从 templates/figure.mjs 开始，用脚本绘制，不手改 SVG。
7. 运行脚本，标签过小、过宽或越界时必须停止。
8. 运行 references/checks.md 的检查，修复所有发现。
9. 渲染为 PNG，分别按原尺寸和 50% 宽度查看。
10. 写图注：粗体断言、读图顺序、来源。

九种图形

各类型的布局尺寸见 references/kinds.md。

图表表达什么

• 使用真实系统和真实名称，不用“组件 A”等泛化方框。
• 不画统计卡、进度条或装饰图标。
• 每图一个断言。
• 对比主题的两种行为，不对比自己项目的旧版本。
• 时序图按运行记录中的发生顺序给交互编号。

颜色

十种色相为 grey、blue、teal、violet、green、amber、plum、olive、indigo、rose。每种都有 ink 和 fill token，同一组图含义一致。

固定四种语义：

其他六种每组只定义一次，记录在页面或手册前言中。

每种颜色写作 var(--m-<token>, <light hex>)，例如 var(--m-rose-ink, #b0344d)。宿主提供深色值，README 使用浅色默认值。完整值见 references/grammar.md。

箭头

• 线宽 1.2。虚线 5 4，点线 1.5 3.5，点线使用圆端点。
• 每种色相一个箭头标记，ID 为 <figure-id>-head-<hue>。
• 箭头在目标边框前 1 单位结束。
• 每组第一张图 0.1 展示该组使用的每种箭头样式。

边框

• 色相 ink 实线：普通部件或状态。
• 虚线：中断、可选或不存在。
• 双边框：第二个矩形内缩 3 单位，表示终止状态。
• 斜线填充：时间线上的等待时间，不能覆盖文字。

可读性

• 640 单位宽时文字至少 11 单位，屏幕约 11px，打印约 8pt。
• 方框标题 12.5、粗体等宽，副行 11、衬线，箭头标签 11.5，注释 11、衬线。
• 每行衬线字都声明 class="m-serif" 和 font-family="Source Serif 4, Georgia, serif"，使内联、README 图片和手册一致。
• 小标题为 11，英文大写，字距 1.2，颜色 ink-mute。
• 标签不省略，不重叠，不置于斜线填充上，不被连线穿过。
• 放不下时移到外部并加引线，或放进编号索引，不缩字号。
• 箭头标签下垫面板色补底，类为 m-knock，绘制顺序是线、补底、标签。
• 补底只遮线，不作为标签必须装入的方框。
• 布局前估算文本宽度：等宽 字符数 × 字号 × 0.6，衬线 字符数 × 字号 × 0.54。中文全宽字需按实际字体测量，不套用拉丁字宽估算。

技术规则

• 根为 viewBox="0 0 640 H"，H 最大 760，带 role="img" 和 aria-labelledby="<id>-title <id>-desc"。
• 根字体 font-family="JetBrains Mono, ui-monospace, monospace"，墨色 fill="var(--m-ink, #1a1a1a)"。衬线行独立声明字体。
• 根直接包含 <title> 和至少 40 字符的 <desc>。
• desc 按阅读顺序列出全部部件和交互。
• 每个 id 以图 ID 开头，例如 fig-4-1-head-amber。
• 图 ID 用小写词和数字，以连字符连接，例如 fig-4-1。
• 只用 references/checks.md 列出的元素与属性。
• 没有 style、脚本、事件处理器、链接或图片。
• transform 只能是 <g> 上的 translate()。
• 每行一个 <text>。
• 文件不超过 40 KB，绘制元素不超过 450 个。

图注

图注放在页面中 SVG 外部。

1. 先用粗体写一句断言，英文最多 28 词，以句号结束。
2. 说明读图顺序，例如“从上向下阅读”。
3. 说明来源，例如运行记录文件。

手册中使用围栏声明图表。字段与类型保持不变，面向读者的文字译为中文：

```figure
id: fig-4-1
kind: state
title: 任务生命周期
claim: 任务进入四种终止状态之一后，不再离开。
caption: 从左到右阅读。虚线边框表示中断状态。来源为 capture/out/task-states.txt。
```

课程或 README 以内联或图片标签插入 SVG，再在下方添加图注段落。

源与产物一起保存

• 脚本与 SVG 放在邻近目录，例如 figures/src/fig-4-1.js 和 figures/fig-4-1.svg。
• 每次从脚本生成 SVG，构建后不手改产物。
• 提交前重建，确认提交的 SVG 与脚本输出一致。

完成前检查

• 断言为一句，英文最多 28 词。
• 标签都是真实来源中的名称，不用“组件 A”。
• 使用九种图形之一。
• 玫红表示失败，灰色表示范围外，琥珀表示生命周期，青色表示持久状态。
• 箭头使用八种样式之一，并符合语义。
• viewBox 宽 640，高不超过 760。
• 包含 role="img"、aria-labelledby、<title>、至少 40 字符的 <desc>。
• 所有 ID 以图 ID 开头。
• 颜色均为 var(--m-<token>, <light hex>)，默认值正确。
• 字号至少 11，无越界、文字重叠或连线穿字。
• 标签无省略号。
• 衬线行有字体属性，根有墨色 fill，不依赖宿主样式表。
• 无 style、脚本、链接、图片，仅允许 g 上的 translate 变换。
• 文件最多 40 KB。
• PNG 在 50% 宽度下清晰。
• 图注包含粗体断言、读图顺序、来源。
• 提交的 SVG 等于脚本输出。

文件

• references/kinds.md：九种图形布局与图 0.1。
• references/grammar.md：明暗 token、语义色、箭头、标记、字号、度量、形状、可选节拍。
• references/checks.md：检查项、允许元素属性、图注规则。
• templates/figure.mjs：自包含 Node 脚本，含小型图表工具和 sequence 示例。运行 node templates/figure.mjs out.svg 写文件，不传路径则打印。

仓库中另见 manuals/_shared/figkit.js 完整工具、manuals/_shared/templates/ 各类型模板、scripts/audit_manuals.js 图表检查器。