SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsblueprint-figure

blueprint-figure

Design & creation

View repository

Updated 10-20 21:15

About this skill

Blueprint-style diagrams

Each static SVG explains one mechanism of a real system, using real IDs, fields, methods, status codes, and sequence numbers from the system. Diagrams use light paper panels and a small set of fixed-meaning hues, staying legible at 640-unit width on screen and in print. Usable by Claude, Cursor, Codex, OpenClaw, Hermes, and all agents that read SKILL.md.course-style Saves the full course token; this skill copies the needed values and can be used independently.

When to use

  • A course, README, or handbook needs to explain how system parts communicate, store data, or change state.
  • Run records, logs, specs, or source code exist from which real names can be obtained.
  • The assertion fits one of the nine diagram types below.

When to use other approaches

  • The diagram must animate or respond to sliders: use motion-figure。
  • Hands-on machine explanation with depth and controls: use isometric-explainer。
  • Numeric charts with multiple data points: use a plotting tool.
  • No real names for the parts: first obtain a run record or source code.

Method

  1. First write the one assertion the diagram is meant to prove, at most 28 words in English.
  2. Choose one diagram type; if two types fit, split into two diagrams.
  3. Collect real participants, fields, methods, status codes, and sequence numbers from the sources.
  4. Write the semantic color table for the whole diagram set before drawing; see the color rules below.
  5. Lay out on a 640-unit grid, with content between x 20 and x 620.
  6. Start from templates/figure.mjs and draw with a script; do not hand-edit the SVG.
  7. Run the script; stop if any label is too small, too wide, or out of bounds.
  8. Run the checks in references/checks.md and fix everything found.
  9. Render to PNG and inspect at original size and at 50% width.
  10. Write the caption: bold assertion, reading order, sources.

Nine diagram types

Type Purpose
sequence Participant lifelines, time downward, numbered interactions
structure Structure of a record, object, or schema
flow Stages data flows through, and who writes and who reads
comparison Two answers to the same question shown side by side
timeline Multiple tracks along a numeric axis such as commit number or time
tree Ownership, containment, delegation
state State machines and transitions
decision Where failure occurs and what each outcome means
layers Layered structure and the parts each layer is responsible for

Layout dimensions for each type are in references/kinds.md。

What diagrams express

  • Use real systems and real names, not generic boxes like "Component A".
  • Do not draw stat cards, progress bars, or decorative icons.
  • One assertion per diagram.
  • Compare two behaviors of the topic, not old versions of your own project.
  • Number sequence-diagram interactions in the order they occur in the run record.

Colors

The ten hues are grey、blue、teal、violet、green、amber、plum、olive、indigo、rose. Each has ink and fill tokens, with consistent meaning across a diagram set.

Four fixed semantics:

Hue Meaning
rose Failure: error, crash, abort, work loss
grey Out of theme: host, operator, out of scope
amber Lifecycle: task, phase, state machine
teal Persistent state: storage, committed records

The other six are each defined only once, recorded on the page or in the manual's preface.

Each color is written as var(--m-<token>, <light hex>), for example var(--m-rose-ink, #b0344d). The host provides dark values; the README uses light defaults. Full values in references/grammar.md。

Arrows

Style Meaning
Ink solid Call or request
Ink dashed Response
Cyan solid Persistent write
Amber dashed State change
Plum solid Model call or computation
Olive dashed External system effect
Indigo dotted Flow or event
Rose dashed Failure
  • Stroke width 1.2. Dashed 5 4, dotted 1.5 3.5; dotted lines use round caps.
  • One arrow marker per hue, ID is <figure-id>-head-<hue>。
  • Arrows end 1 unit before the target border.
  • The first figure of each group shows at 0.1 each arrow style used by that group.

Borders

  • Hue ink solid: normal component or state.
  • Dashed: interrupted, optional, or nonexistent.
  • Double border: a second rectangle inset 3 units, indicating a terminal state.
  • Hatch fill: waiting time on a timeline; must not cover text.

Readability

  • At 640 units wide, text is at least 11 units, about 11px on screen and about 8pt in print.
  • Box titles 12.5, bold monospace; sublines 11, serif; arrow labels 11.5; annotations 11, serif.
  • Every serif line declares class="m-serif" and font-family="Source Serif 4, Georgia, serif", so inline, README images, and the manual are consistent.
  • Subheadings are 11, uppercase English, letter spacing 1.2, color ink-mute.
  • Labels are not elided, not overlapped, not placed on hatch fill, and not crossed by connector lines.
  • If they do not fit, move them outside with a leader line, or put them in a numbered index; do not shrink the font size.
  • Arrow labels have a panel-colored backing underneath, class m-knock; draw order is line, backing, label.
  • The backing only masks lines; it is not a box the label must fit inside.
  • Estimate text width before layout: monospace 字符数 × 字号 × 0.6, serif 字符数 × 字号 × 0.54. Full-width Chinese characters must be measured with the actual font; do not apply Latin character width estimates.

Technical rules

  • Root is viewBox="0 0 640 H", H max 760, with role="img" and aria-labelledby="<id>-title <id>-desc"。
  • Root font font-family="JetBrains Mono, ui-monospace, monospace", ink fill="var(--m-ink, #1a1a1a)". Serif lines declare their font independently.
  • The root directly contains <title> and a <desc>。
  • desc of at least 40 characters listing all components and interactions in reading order.
  • Each id starts with the figure ID, for example fig-4-1-head-amber。
  • Figure IDs use lowercase words and digits joined by hyphens, for example fig-4-1。
  • Use only the elements and attributes listed in references/checks.md .
  • No style, scripts, event handlers, links, or images.
  • transform may only be <g> on translate()。
  • One per line: <text>。
  • Files must not exceed 40 KB, and drawing elements must not exceed 450.

Figure caption

Place the figure caption outside the SVG on the page.

  1. First write an assertion in bold, at most 28 words in English, ending with a period.
  2. State the reading order, for example “read from top to bottom”.
  3. State the source, for example a run log file.

Use fenced blocks to declare diagrams in the manual. Field and type names stay unchanged; reader-facing text is translated into Chinese:

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

Insert the SVG in the course or README inline or via an image tag, then add a caption paragraph below it.

Save source and artifact together

  • Keep the script and SVG in adjacent directories, for example figures/src/fig-4-1.js and figures/fig-4-1.svg。
  • Generate the SVG from the script every time; do not hand-edit the artifact after building.
  • Rebuild before committing, and confirm the committed SVG matches the script output.

Checks before finishing

  • The assertion is one sentence, at most 28 words in English.
  • All labels are names from real sources; do not use “Component A”.
  • Use one of the nine shapes.
  • Magenta means failure, gray means out of range, amber means lifecycle, cyan means persistent state.
  • Arrows use one of the eight styles and match the semantics.
  • viewBox is 640 wide and no more than 760 high.
  • Includes role="img"、aria-labelledby、<title>, a <desc>。
  • All IDs start with the diagram ID.
  • All colors are var(--m-<token>, <light hex>), and defaults are correct.
  • Font size is at least 11, with no out-of-bounds, text overlap, or lines crossing text.
  • No labels contain ellipses.
  • Serif lines have font attributes, the root has an ink fill, and nothing depends on the host stylesheet.
  • No style, scripts, links, or images; only translate transforms on g are allowed.
  • The file is at most 40 KB.
  • The PNG is clear at 50% width.
  • The caption includes a bold assertion, reading order, and source.
  • The committed SVG equals the script output.

Files

  • references/kinds.md: nine shape layouts and Figure 0.1.
  • references/grammar.md: light/dark tokens, semantic colors, arrows, markers, font sizes, metrics, shapes, optional beats.
  • references/checks.md: checks, allowed element attributes, caption rules.
  • templates/figure.mjs: a self-contained Node script with a small chart toolkit and a sequence example. Run node templates/figure.mjs out.svg to write files; if no path is passed, it prints.

See also in the repository: manuals/_shared/figkit.js the full toolkit,manuals/_shared/templates/ templates for each type,scripts/audit_manuals.js the diagram checker.