moai-domain-svg-infographic

# SVG Technical Infographic

Produce a hand-editable SVG diagram whose geometry was decided by arithmetic
rather than by eye, plus a 2x PNG raster of it. The output is one static image:
no animation, no scripting, no external asset at view time.

## Step 0 — Decide whether this is an SVG job

This skill is **additive to the mermaid pipeline, never a replacement for it**.
Nothing here migrates, rewrites, or deprecates an existing mermaid diagram on
its own (the sole exception: a caller-invoked import through the opt-in importer
references in the bundled-references table, where the one-home rule below
governs and the source is replaced outright in the same change), and no diagram
should ever exist in both forms — that is dual maintenance, and it is
the one failure this section exists to prevent.

Route the request before drawing anything:

| Signal | Route to |
|--------|----------|
| The diagram lives inside a markdown document | mermaid |
| It changes often, alongside the prose around it | mermaid |
| It is a standard type: flow, sequence, ER, state, class, gantt | mermaid |
| Its text labels are kept in sync across locales | mermaid |
| The deliverable is an image file for slides, email, social, or offline reading | this skill |
| It is a freeform architecture or concept infographic with no standard shape | this skill |
| Pixel-level control of position, spacing, or layering is required | this skill |
| Korean or other CJK labels must wrap at exact, verified widths | this skill |

When several signals point both ways, mermaid wins: a mermaid block is cheaper
to keep correct than an image. Choose this skill only when the routing table
gives it an unopposed reason.

**One diagram, one home.** If a mermaid version already exists, either replace it
outright (and delete the mermaid block in the same change) or leave it alone.
Never ship both.

## Runtime prerequisites and degradation

Node 18 or later and a headless Chromium-family browser are needed **only to
lint and to render**. Neither is needed to install this skill, to discover it, or
to author the editable SVG — authoring is always available.

| Node 18+ | Headless Chromium | What is delivered |
|----------|-------------------|-------------------|
| present | present | Editable SVG, machine lint report, 2x PNG with the browser executable and version disclosed and PNG header dimensions verified |
| present | absent | Editable SVG plus machine lint report. State plainly that no headless browser was found and no PNG was produced |
| absent | either | Editable SVG plus the manual checklist result from `references/authoring.md`. Do **not** attach a machine-lint label, and do not claim a render |

Never fabricate a PNG, a pixel dimension, or a lint verdict for a tool that did
not run. Say which step was skipped and why.

## The workflow

Six steps, in order. Steps 1 through 3 finish before a single SVG element is
written; that ordering is the whole method.

1. **Frame.** Write down the message the diagram must land, then set the four
   output dials below. They change the deliverable, the canvas, the density, and
   the wording, so they are decided before an archetype is picked, not after.
2. **Pick an archetype.** Architecture stack, left-to-right flow, side-by-side
   comparison, or hierarchy tree. Skeletons are in `references/archetypes.md`.
3. **Run the numeric layout pass.** Produce the box table and pass every
   containment and text-budget check below. Do not proceed on a failing row.
4. **Author the SVG** from the table. Every coordinate is either a table value
   or a formula over table values.
5. **Lint the source** with `scripts/check-svg.mjs`. Clear every error; triage
   every warning.
6. **Render and verify** with `scripts/render.mjs`. Confirm the reported PNG
   dimensions match the requested 2x target, then look at the PNG.

### The four output dials

| Dial | Values | Default |
|------|--------|---------|
| **format** | `svg` · `svg+png` | `svg+png` |
| **size** | `doc-inline` (1200 wide) · `slide-16x9` (1600x900) · `social-og` (1200x630) · `print-a4-landscape` (1754x1240) · `fit` (the archetype's own preset) | `doc-inline` |
| **detail** | `faithful` (<=24 nodes, banded) · `balanced` (<=12) · `simplified` (<=7) | `balanced` |
| **audience** | `engineer` · `mixed` · `executive` | `mixed` |

Every dial has a default, because a dial without one turns a four-part contract
into four questions on every invocation. State the four settled values beside the
deliverable so a later regeneration reproduces the same artifact. `size` sets the
type ramp as well as the `viewBox`, and `audience` governs wording rather than
node count — both are detailed in `references/archetypes.md`.

### Complexity budget

**Every type has a node ceiling, and exceeding it means split or simplify —
never shrink the boxes.** The ceiling is the `detail` dial's: 12 nodes at
`balanced`, 7 at `simplified`, 24 at `faithful` and only inside labelled bands.
In every mode: at most 12 connectors and at most 2 `accent` elements. `faithful`
exempts the node count and nothing else. Per-archetype ceilings are in
`references/archetypes.md`.

## The numeric layout pass

Build one table before authoring. Five owned columns per box — `id`, `x`, `y`,
`w`, `h` — and nothing else is typed by hand. Every other number in the file is
derived from those.

**Grid.** For canvas width `W`, `n` columns, outer margin `M`, gutter `G`:

```
colW    = (W - 2*M - (n-1)*G) / n
colX(i) = M + i * (colW + G)
```

If `colW` falls below the archetype's minimum card width, reduce `n` or widen
`W`. Do not shrink the margin to rescue a column count.

**Containment.** Check every row, and stop if any fails:

```
M <= x            and  x + w <= W - M
M <= y            and  y + h <= H - M
parent.x + pad <= child.x   and  child.x + child.w <= parent.x + parent.w - pad
```

**Derived geometry.** Centers and anchors come from the box, never from a
per-language nudge:

```
cx            = x + w/2
cy