blueprint-figure

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Blueprint Figure

蓝图图示

This skill draws one static SVG figure that explains one mechanism of a real system. The figure uses the real names from the system: ids, field names, method names, status codes and sequence numbers. It sits on a light paper panel and uses a small set of hues with fixed meanings. It stays readable at 640 units wide on screen and in print. Claude, Cursor, Codex, OpenClaw, Hermes, or any agent that reads SKILL.md can use it. The sibling skill

course-style

holds the full course tokens. This skill copies the tokens it needs, so it works alone.

此 skill 会绘制一张静态 SVG 图，用于解释真实系统中的一个机制。图示使用系统中的真实名称：ID、字段名、方法名、状态码和序号。它位于浅色纸张面板上，并使用一组具有固定含义的色相。在屏幕和印刷中，以 640 单位宽度显示时仍能保持可读。Claude、Cursor、Codex、OpenClaw、Hermes，或任何能够读取 SKILL.md 的 Agent 均可使用。兄弟 skill

course-style

保存完整的课程 token。本 skill 会复制所需的 token，因此可以独立工作。

When to use

何时使用

A lesson, README or manual needs a picture of how parts of a system talk, store data, or change state.
You have a capture, a log, a spec or source code that gives the real names.
The claim fits one of the nine kinds below.

课程、README 或手册需要一张图来说明系统各部分如何通信、存储数据或改变状态。
你有 capture、日志、规范或源代码，其中包含真实名称。
核心结论符合下述九种类型之一。

When not to use

何时不要使用

The figure must move or respond to a slider. Use the sibling skill
```
motion-figure
```
.
The subject is a physical machine explainer with depth and controls. Use the sibling skill
```
isometric-explainer
```
.
The data is a chart of numbers over many points. Use a chart tool.
You do not have real names for the parts. Get a capture or a source first.

图示需要动态效果或响应滑块。请使用兄弟 skill
```
motion-figure
```
。
主题是带深度和控件的实体机器讲解。请使用兄弟 skill
```
isometric-explainer
```
。
数据是包含大量数据点的数值图表。请使用图表工具。
你没有各部分的真实名称。请先获取 capture 或源文件。

Method

方法

Write the claim first. One sentence, at most 28 words, that the figure proves.
Pick one kind from the table below. If two kinds fit, draw two figures.
Collect the real names from the source: parties, fields, methods, codes, sequence numbers.
Write the hue table for the figure set before you draw (see "Colour").
Sketch the layout on the 640-unit grid. Keep content between x 20 and x 620.
Draw the figure with a script. Start from
```
templates/figure.mjs
```
. Do not edit the SVG by hand.
Run the script. It stops on a label that is too small, too wide, or outside the figure.
Run the checks in
```
references/checks.md
```
. Fix every finding.
Render the SVG to PNG and look at it at 100% and at 50% width.
Write the caption: the bold claim, how to read the figure, then the source.

先写出核心结论。用一句话表述图示要证明的内容，最多 28 个单词。
从下表中选择一种类型。如果两种类型都适用，就绘制两张图。
从源文件中收集真实名称：参与方、字段、方法、代码和序号。
绘制前写出该组图示的色相表（见“色彩”）。
在 640 单位网格上规划布局。将内容保持在 x 20 和 x 620 之间。
使用脚本绘制图示。以
```
templates/figure.mjs
```
为起点。不要手动编辑 SVG。
运行脚本。如果标签太小、太宽或位于图示之外，脚本会停止。
运行
```
references/checks.md
```
中的检查。修复每一项发现的问题。
将 SVG 渲染为 PNG，并以 100% 和 50% 宽度查看。
编写图注：先写加粗的核心结论，再说明如何阅读图示，最后注明来源。

The nine kinds

九种类型

Kind	Use it for
`sequence`	parties on lifelines, time running down, numbered exchanges
`structure`	the anatomy of one record, object, or schema
`flow`	stages that data passes through, with who writes and who reads
`comparison`	two answers to one question, side by side
`timeline`	tracks over a numbered axis such as commit sequence or time
`tree`	ownership, containment, or delegation
`state`	a state machine with its transitions
`decision`	where something fails and what each outcome means
`layers`	a stack of layers with the parts each one owns

Layout numbers for each kind are in

references/kinds.md

类型	适用场景
`sequence`	参与方位于生命线上，时间向下延伸，交互带有编号
`structure`	展示一条记录、一个对象或一种 schema 的内部结构
`flow`	展示数据依次经过的阶段，以及由谁写入和读取
`comparison`	并排展示针对同一问题的两个答案
`timeline`	在带编号的轴线上展示多条轨迹，例如 commit 顺序或时间
`tree`	展示所有权、包含关系或委派关系
`state`	展示状态机及其状态转换
`decision`	展示失败发生的位置以及每种结果意味着什么
`layers`	展示分层结构以及每层负责的部分

每种类型的布局编号见

references/kinds.md

。

What a figure shows

图示应展示的内容

Show the real system with real names. Never draw generic boxes such as "Component A".
Never draw stat cards, progress bars, or decorative icons.
Make one claim per figure.
Compare two behaviours of the subject. Never compare with an earlier build of your own project.
Number the exchanges in a sequence in the order they happen in the capture.

使用真实系统及其真实名称。绝不绘制“Component A”之类的通用方框。
绝不绘制统计卡片、进度条或装饰性图标。
每张图只表达一个核心结论。
比较主题的两种行为。绝不与你自己项目的早期构建版本进行比较。
按 capture 中实际发生的顺序为 sequence 中的交互编号。

Colour

色彩

Ten hues:

grey

blue

teal

violet

green

amber

plum

olive

indigo

rose

. Each hue has an ink and a fill token. A hue means the same thing in every figure of one set.

Four meanings are fixed:

Hue	Fixed meaning
`rose`	failure: errors, crashes, aborts, lost work
`grey`	outside the subject: the host, the operator, out of scope
`amber`	lifecycle: tasks, phases, state machines
`teal`	durable state: storage and committed records

Assign the other six hues once per set and write the table in the page or the manual front matter.

Write every colour as

var(--m-<token>, <light hex>)

, for example

var(--m-rose-ink, #b0344d)

. The host page supplies dark values. A README shows the light hex. All light and dark values are in

references/grammar.md

十种色相：

grey

、

blue

、

teal

、

violet

、

green

、

amber

、

plum

、

olive

、

indigo

、

rose

。每种色相都有一个 ink token 和一个 fill token。在同一组图示中，某种色相始终表示相同含义。

四种含义固定不变：

色相	固定含义
`rose`	失败：错误、崩溃、中止、工作丢失
`grey`	主题之外：宿主、操作者或范围外内容
`amber`	生命周期：任务、阶段、状态机
`teal`	持久化状态：存储和已提交的记录

为每组一次性分配其余六种色相的含义，并将色相表写在页面或手册的前言中。

每种颜色都应写成

var(--m-<token>, <light hex>)

，例如

var(--m-rose-ink, #b0344d)

。宿主页面会提供深色值。README 使用浅色 hex。所有浅色和深色值均见

references/grammar.md

。

Arrows

箭头

Style	Means
solid ink	a call or request
dashed ink	a reply
solid teal	a durable write
dashed amber	a state change
solid plum	a model call or compute
dashed olive	an effect outside the system
dotted indigo	a stream or an event
dashed rose	a failure

Line width is 1.2. Dashed is
```
5 4
```
. Dotted is
```
1.5 3.5
```
with round caps.
Use one arrowhead marker per hue, with the id
```
<figure-id>-head-<hue>
```
.
End each arrow 1 unit before the target border.
Figure 0.1, the first figure of a set, shows each arrow style that the set uses.

样式	含义
ink 实线	调用或请求
ink 虚线	响应
teal 实线	持久化写入
amber 虚线	状态变更
plum 实线	模型调用或计算
olive 虚线	系统外部的副作用
indigo 点线	数据流或事件
rose 虚线	失败

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

Borders

边框

Solid border in the hue ink: a normal part or state.
Dashed border: interrupted, optional, or not present.
Double border (a second rect inset 3 units): a terminal state.
Hatched fill: waiting time on a timeline bar. Never put text on it.

使用色相 ink 的实线边框：表示普通组成部分或状态。
虚线边框：表示中断、可选或不存在的内容。
双线边框（第二个 rect 向内缩进 3 个单位）：表示终止状态。
斜线填充：表示时间线条上的等待时间。绝不在其上放置文字。

Legibility rules

可读性规则

Text is at least 11 units at the 640-unit width. That is 11 pixels on screen and about 8 points in print.
Box titles are 12.5 bold mono. Sub lines are 11 serif. Arrow labels are 11.5. Notes are 11 serif.
Every serif line carries its own font:
```
class="m-serif"
```
and
```
font-family="Source Serif 4, Georgia, serif"
```
. Then the figure looks the same inline on any page, in a README image, and in a manual.
Kickers are 11, upper case, letter spacing 1.2, in ink-mute.
No ellipsis in labels. No text over text. No text on a hatched fill. No line through text.
A label that does not fit goes outside with a leader line or into a numbered key. Never reduce the font size.
Put each arrow label on a knock patch in the panel colour, with
```
class="m-knock"
```
.
Draw the knock patch after the line and before the label.
A knock patch hides a line. It never counts as the box that a label must fit inside.
Measure text before you place it: mono width is
```
characters × size × 0.6
```
, serif width is
```
characters × size × 0.54
```
.

在 640 单位宽度下，文本至少为 11 单位，即屏幕上的 11 像素、印刷时约 8 点。
方框标题使用 12.5 的粗体等宽字体。子行使用 11 的衬线字体。箭头标签使用 11.5。注释使用 11 的衬线字体。
每一行衬线文本都必须在自身设置字体：
```
class="m-serif"
```
和
```
font-family="Source Serif 4, Georgia, serif"
```
。这样，图示无论嵌入页面、README 图片还是手册，外观都保持一致。
引导标签（kicker）使用 11 的字号、大写字母、1.2 的字距，并采用
```
ink-mute
```
颜色。
标签中不得使用省略号。文字不得相互重叠。斜线填充上不得放置文字。线条不得穿过文字。
无法容纳的标签应移到外部并使用引导线，或放入编号索引。绝不能缩小字号。
每个箭头标签下方都应放置一个与面板颜色相同的遮罩块（knock patch），并使用
```
class="m-knock"
```
。
遮罩块应绘制在线条之后、标签之前。
遮罩块用于遮住线条，但不应算作标签必须容纳其内的方框。
放置文字前先测量文字宽度：等宽字体宽度为
```
字符数 × 字号 × 0.6
```
，衬线字体宽度为
```
字符数 × 字号 × 0.54
```
。

Technical rules

技术规则

Root:

viewBox="0 0 640 H"

with H at most 760,

role="img"

aria-labelledby="<id>-title <id>-desc"

Root font and ink:

font-family="JetBrains Mono, ui-monospace, monospace"

and

fill="var(--m-ink, #1a1a1a)"

. Serif lines set their own

font-family

as above.

A
```
<title>
```
and a
```
<desc>
```
of at least 40 characters, as direct children of the root.
The
```
desc
```
names every part and every exchange in reading order.
Every
```
id
```
starts with the figure id, such as
```
fig-4-1-head-amber
```
.
Figure ids are lowercase words and digits joined by hyphens, such as
```
fig-4-1
```
.
Use only the elements and attributes listed in
```
references/checks.md
```
.
No
```
style
```
, no scripts, no event handlers, no links, no images.
```
transform
```
only as
```
translate()
```
on
```
<g>
```
.
One
```
<text>
```
element per line of text.
The file is at most 40 KB and has at most 450 drawn elements.

根元素使用

viewBox="0 0 640 H"

，其中 H 最大为 760，并设置

role="img"

和

aria-labelledby="<id>-title <id>-desc"

。

根字体和 ink 使用

font-family="JetBrains Mono, ui-monospace, monospace"

和

fill="var(--m-ink, #1a1a1a)"

。衬线文本行需按上述方式单独设置

font-family

。

根元素直接包含一个
```
<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 个。

The caption

图注

Put the caption in the page around the SVG. Do not put it inside the SVG.

Start with the claim in bold: one sentence, at most 28 words, ending with a period.
Say how to read the figure, such as "Read top to bottom."
Name the source, such as the capture file.

In a manual, declare the figure in a fenced block:

text

```figure
id: fig-4-1
kind: state
title: the task lifecycle
claim: A task ends in one of four terminal states and never leaves one.
caption: Read left to right. Dashed borders are interrupted states. From capture/out/task-states.txt.
```

In a lesson or README, put the SVG in an image tag or inline, then the caption as a paragraph under it.

将图注放在页面中 SVG 的周围，不要放在 SVG 内部。

以加粗的核心结论开头：最多 28 个单词的一句话，并以句号结尾。
说明如何阅读图示，例如“从上到下阅读”。
注明来源，例如 capture 文件。

在手册中，使用围栏代码块声明图示：

text

```figure
id: fig-4-1
kind: state
title: the task lifecycle
claim: A task ends in one of four terminal states and never leaves one.
caption: Read left to right. Dashed borders are interrupted states. From capture/out/task-states.txt.
```

在课程或 README 中，将 SVG 放在图片标签中或直接内嵌，然后在图片下方以段落形式编写图注。

Keep source and output together

保持源文件与输出放在一起

Save the figure script beside the SVG, such as
```
figures/src/fig-4-1.js
```
and
```
figures/fig-4-1.svg
```
.
Build the SVG from the script every time. Never edit the SVG by hand after a build.
Before you commit, build again and confirm that the committed SVG equals the script output.

将图示脚本保存在 SVG 旁边，例如
```
figures/src/fig-4-1.js
```
和
```
figures/fig-4-1.svg
```
。
每次都通过脚本生成 SVG。构建完成后，绝不手动编辑 SVG。
提交前再次构建，并确认已提交的 SVG 与脚本输出完全一致。

Check before you finish

完成前检查

The claim is one sentence of at most 28 words.
Every label is a real name from the source. No "Component A".
The figure uses one of the nine kinds.
Rose means failure, grey means outside, amber means lifecycle, teal means durable state.
Every arrow uses one of the eight styles and means what the table says.
```
viewBox
```
width is 640 and height is at most 760.
```
role="img"
```
,
```
aria-labelledby
```
,
```
<title>
```
and a
```
<desc>
```
of 40 or more characters are present.
Every
```
id
```
starts with the figure id.
Every colour is
```
var(--m-<token>, <light hex>)
```
with the correct hex.
No text is below 11 units, outside the viewBox, over other text, or crossed by a line.
No ellipsis in any label.
Every serif line has a
```
font-family
```
attribute and the root has the ink
```
fill
```
, so the figure needs no host stylesheet.
No
```
style
```
, script, link, image, or transform other than
```
translate()
```
on
```
<g>
```
.
The file is at most 40 KB.
The PNG render is readable at 50% width.
The caption has the bold claim, the reading order, and the source.
The committed SVG equals the script output.

核心结论只有一句话，且不超过 28 个单词。
每个标签都是源文件中的真实名称，不出现“Component A”。
图示采用九种类型之一。
rose 表示失败，grey 表示外部，amber 表示生命周期，teal 表示持久化状态。
每条箭头都采用八种样式之一，且含义与表格一致。
```
viewBox
```
宽度为 640，高度不超过 760。
已设置
```
role="img"
```
和
```
aria-labelledby
```
，并包含
```
<title>
```
和至少 40 个字符的
```
<desc>
```
。
每个 id 都以图示 id 开头。
每种颜色均使用
```
var(--m-<token>, <light hex>)
```
格式，并带有正确的 hex。
不存在字号低于 11 单位、超出 viewBox、相互重叠或被线条穿过的文字。
任何标签中都没有省略号。
每行衬线文本都有
```
font-family
```
属性，根元素也有 ink
```
fill
```
，因此图示不需要宿主样式表。
不含
```
style
```
、脚本、链接、图片，也不含
```
<g>
```
上
```
translate()
```
以外的 transform。
文件不超过 40 KB。
PNG 渲染结果在 50% 宽度下仍然清晰可读。
图注包含加粗的核心结论、阅读顺序和来源。
已提交的 SVG 与脚本输出完全一致。

Files

文件

```
references/kinds.md
```
: layout numbers for each of the nine kinds, and figure 0.1.
```
references/grammar.md
```
: light and dark tokens, hue meanings, arrow strokes, markers, text sizes and metrics, shapes, optional beats.
```
references/checks.md
```
: every check with its test, the allowed elements and attributes, and the caption rules.
```
templates/figure.mjs
```
: a self-contained Node script with a small figure kit and one
```
sequence
```
figure. Run
```
node templates/figure.mjs out.svg
```
to write the SVG, or omit the path to print it.

Inside the AI Engineering from Scratch repo, also see

manuals/_shared/figkit.js

(the full kit),

manuals/_shared/templates/

(one script per kind), and

scripts/audit_manuals.js

(the figure lint).

```
references/kinds.md
```
：九种类型各自的布局编号，以及图 0.1。
```
references/grammar.md
```
：浅色和深色 token、色相含义、箭头描边与标记、字号和度量、形状及可选节拍。
```
references/checks.md
```
：每项检查及其测试、允许使用的元素和属性，以及图注规则。
```
templates/figure.mjs
```
：一个自包含的 Node 脚本，包含精简的图示工具包和一个
```
sequence
```
图示。运行
```
node templates/figure.mjs out.svg
```
可写入 SVG，省略路径则打印 SVG。

在 AI Engineering from Scratch 仓库中，还可参阅

manuals/_shared/figkit.js

（完整工具包）、

manuals/_shared/templates/

（每种类型对应一个脚本）以及

scripts/audit_manuals.js

（图示 lint 检查）。