/blueprint-figure

name: blueprint-figure
version: 1.0.0
description: >
  Draws static SVG figures for lessons, READMEs and manuals in the AI Engineering
  from Scratch look: paper panel, blueprint accent, nine figure kinds, fixed hue
  meanings, eight arrow styles, and checks for legibility and markup.
  Trigger phrases: "draw a figure", "blueprint figure", "sequence figure",
  "state machine figure", "figure for this lesson", "add a diagram to the manual".
tags: [svg, figures, diagrams, accessibility, documentation]

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.

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.

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.

Method

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

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`.

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.

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`.

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.

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.

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