/moai-domain-svg-infographic

name: moai-domain-svg-infographic
description: >
  Author editable SVG technical infographics — architecture, flow, comparison,
  hierarchy — by computing the layout numerically before writing markup, then
  rendering a 2x PNG via headless Chromium. Carries a CJK-first font stack, a
  deterministic source lint, and mermaid-vs-SVG selection rules.

when_to_use: >
  Use for a static diagram image bound for slides, email, social, or offline
  use, or a freeform architecture infographic needing pixel control or precise
  Korean line wrapping. Markdown-embedded diagrams that change often or stay
  locale-synced remain mermaid.

license: Apache-2.0
compatibility: Designed for Claude Code
allowed-tools: Read, Write, Edit, Grep, Glob, Bash
user-invocable: true
metadata:
  version: "1.0.0"
  category: "domain"
  status: "active"
  updated: "2026-07-24"
  modularized: "true"
  tags: "svg, infographic, diagram, architecture, flow, png, chromium, cjk, layout"
  related-skills: "moai-domain-html-report"

# MoAI Extension: Progressive Disclosure
progressive_disclosure:
  enabled: true
  level1_tokens: 100
  level2_tokens: 5000

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, 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, the target medium (slide, README hero, email, print), the canvas size, and the label language. 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 numeric layout pass

Build one table before authoring. Four 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            = y + h/2
iconCenter    = (x + pad + iconR, y + h/2)
titleBaseline = y + pad + titleSize
lineBaseline(k) = titleBaseline + titleGap + k*lineHeight

If you find yourself moving an icon down three units "because the Korean text sits low", the formula is wrong. Fix the formula, not the instance. Hand-tuned per-language offsets are exactly the render-fix loop this method removes.

**Connectors.** Endpoints are derived too; the arrowhead length is