SVG Board Generator

Use this skill to create deterministic, document-ready diagrams as SVG first, then render to PNG when needed. Prefer it for architecture, workflow, risk, and review diagrams that need precise spacing, readable Chinese labels, and stable layout.

The core job is not just drawing. The diagram must explain the same point as the surrounding text, with a layout that survives insertion into a document.

Workflow

1. Clarify the diagram intent in business terms before drawing.
   • Use user-facing layer names such as "入口层", "业务分流层", "处理层", "执行层", "结果层".
   • Avoid concrete class names, method names, and implementation-only details unless the user explicitly asks for them.
   • Write a one-sentence claim for the diagram: what should the reader understand after seeing it?
2. Choose the diagram template and visual style before writing SVG/spec.
   • State the choice explicitly in your working prompt or plan: template=<name>, style=<name>, reason=<one sentence>.
   • layered: architecture responsibilities, service layers, cross-cutting controls.
   • flow / lifecycle: business process movement from start to finish, such as 提交请求 → 入口校验 → 业务处理 → 结果确认.
   • matrix: risk categories, bottleneck evidence, impact/control comparisons, review checklists.
   • hub: one core capability with surrounding dependencies, controls, risks, or actors.
   • swimlane: responsibilities across user, gateway, business service, executor, data service, or audit.
   • Do not reuse the same visual skeleton for several adjacent figures unless the text intentionally compares the same structure.
   • Pick a style that reinforces the topic, not just a color you like.
3. Create or adapt a JSON spec for the board.
   • Keep each column to one clear responsibility.
   • Keep each box short: one label plus optional one-line description.
   • Put shared safeguards, storage, status, permission, and fallback handling in the bottom shared area.
   • For risk documentation, every visual node must map to at least one nearby paragraph. Remove decorative nodes that are not explained by the text.
4. Run the bundled script for any built-in board template:

node <skill_dir>/scripts/generate_svg_board.mjs \
  --spec /path/to/board.json \
  --output-dir /tmp/my-board \
  --name architecture-board \
  --template layered \
  --style classic \
  --strict

If no --spec is provided, the script generates a built-in generic business-system example.

Use --template layered|flow|matrix|hub|swimlane and --style classic|risk|trust|ops|executive to select the intended archetype. Create a project-local render script only when the requested diagram falls outside these built-in templates, and keep the same validation rules below.

5. Review the PNG before inserting it into a document.
   • Check whether labels are readable at the target document width.
   • Increase canvas width or reduce text if the diagram feels crowded.
   • Prefer a wide 2:1 diagram for document sections with architecture flow.
   • Open the generated HTML/PNG preview and inspect at the actual document display width, not only at full resolution.
   • If any text touches, overlaps, clips, or visually competes with another node, revise before delivery.

Quality Gate

Before delivering or inserting a diagram, verify:

• Content fit: title, labels, and captions match the surrounding text; no unsupported claim is introduced by the diagram.
• Visual fit: each figure in the same section uses a suitable archetype; avoid a row of nearly identical boards.
• Layout fit: no node overlap, no text outside its box, no label crossing arrows or section boundaries.
• Reading fit: Chinese text is readable after export to PNG and after insertion into a document.
• Risk accuracy: for risk diagrams, distinguish source, impact, control, and remaining concern; do not invent numeric severity or heat values unless the source text contains them.
• Export fit: .svg, .html, and .png exist; the PNG is not blank and has the expected aspect ratio.

Spec Shape

For layered, use this structure:

{
  "template": "layered",
  "style": "classic",
  "title": "通用业务系统分层处理流程图",
  "subtitle": "请求从入口进入后，先完成校验与分流，再由处理能力执行并统一返回结果",
  "footer": "不同入口可以触发不同处理能力，但状态追踪、权限校验、数据保存和失败原因统一收口。",
  "columns": [
    {
      "title": "访问入口层",
      "note": "用户或系统发起请求",
      "color": "#2563eb",
      "fill": "#f8fbff",
      "items": [
        { "label": "Web / App 请求", "fill": "#eef6ff", "stroke": "#2563eb" }
      ]
    }
  ],
  "shared": [
    {
      "title": "状态统一",
      "lines": ["前端查询同一种任务状态", "成功、失败、处理中都可识别"],
      "fill": "#eef6ff",
      "stroke": "#2563eb"
    }
  ]
}

Other templates use these compact shapes:

{
  "template": "flow",
  "style": "risk",
  "title": "业务请求处理流程风险图",
  "steps": [
    { "label": "提交请求", "desc": "表单、接口、批量导入" },
    { "label": "入口校验", "desc": "身份、权限、参数" },
    { "label": "业务处理", "desc": "规则判断与数据变更" }
  ]
}

{
  "template": "matrix",
  "style": "ops",
  "title": "在线服务瓶颈矩阵图",
  "matrixColumns": ["风险来源", "用户影响", "控制思路", "仍需关注"],
  "rows": [
    { "label": "请求高峰", "cells": ["集中提交", "等待变长", "排队限流", "容量评估"] }
  ]
}

{
  "template": "hub",
  "style": "trust",
  "title": "接口信任边界风险图",
  "center": { "label": "业务接口", "desc": "统一校验身份、状态和额度" },
  "nodes": [
    { "label": "网关鉴权", "desc": "识别真实用户" },
    { "label": "异步回调", "desc": "去重和防旧结果覆盖" }
  ]
}

{
  "template": "swimlane",
  "style": "executive",
  "title": "业务流程跨服务协作图",
  "lanes": [
    { "title": "用户", "items": [{ "label": "提交任务" }, { "label": "查询结果" }] },
    { "title": "业务服务", "items": [{ "label": "创建记录" }, { "label": "更新状态" }] }
  ]
}

Template And Style Selection

Use this table before rendering:

Available script styles:

• classic: general blue/green document board.
• risk: warm risk-review palette for risk source, impact, and control.
• trust: security/trust-boundary palette for auth, callback, and quota consistency.
• ops: operational palette for performance, queueing, stability, and capacity.
• executive: cleaner presentation style with more restraint.

Prompt rule: whenever you ask a model to use this skill, include the selected template and style explicitly, for example:

Use $svg-board-generator. Create a document-ready diagram with template=matrix and style=ops.
Reason: the text compares performance risk sources, user impact, controls, and remaining concerns.

Template caveats:

• swimlane is for responsibility grouping plus each lane's internal steps. For strict cross-lane timing, use Mermaid sequenceDiagram or create a dedicated custom render.
• hub works best for one center concept plus 4-10 surrounding nodes. If the surrounding nodes form a chronological chain, use flow instead.
• matrix works best when every row has the same comparison dimensions. If each row needs a different story, split it into smaller figures.
• flow is for a single main path. If there are many parallel branches, use layered or swimlane.

Rendering Notes

• The script writes three files: .svg, .html, and usually .png.
• PNG export uses local Chrome or Chromium in headless mode. If Chrome is unavailable, keep the SVG/HTML output and render manually.
• The script may print warnings for crowded standard boards. Treat those warnings as blockers for document-ready output unless the preview proves they are harmless.
• Use --strict while iterating for document figures; any warning exits non-zero so layout problems are not missed in command output.
• Use absolute paths when showing local previews in Codex desktop:

![preview](/tmp/my-board/architecture-board.png)

Style Guidance

• Use 4-6 main columns for horizontal process boards.
• For standard layered boards, use at least 2400x1300 for 4 columns and 3000x1500 for 5-6 columns.
• Use one arrow between major columns; avoid arrows between every small box.
• Use soft fills and strong text contrast.
• Keep the bottom shared area for concerns that cross all branches: status, storage, permissions, audit, retry, and failure reason. On narrow canvases, keep shared cards to 3 or fewer.
• For Chinese documents, use the built-in font fallback: PingFang SC, Microsoft YaHei, Noto Sans CJK SC, Arial.
• Keep labels short. Prefer "提交请求 / 入口校验 / 业务处理 / 状态回写" over full implementation names.
• Use 2200-2600 px width for document figures and keep the long edge under the size that makes text unreadably small after insertion.
• Do not use a "heatmap" or "score" visual unless the data has real scores. Use a bottleneck matrix or impact/control table for qualitative risk evidence.
• Avoid placing row/column headers above dense content unless enough vertical space is reserved; headers are common sources of overlap.
• If a generated diagram has a known issue, update the source spec/script and regenerate all outputs instead of editing only the PNG.

Stress Check

When a diagram will be inserted into a formal document, run one pressure pass before finalizing:

1. Temporarily keep realistic long Chinese labels and all planned nodes in the spec.
2. Render with --strict.
3. If warnings mention title-wrap, column-crowded, item-overflow, item-label-long, item-desc-long, shared-overflow, or footer-wrap, shorten labels, split the diagram, widen the canvas, or switch archetype.
4. Reopen the PNG/HTML preview after warnings are gone. Warnings are only a guardrail; they do not replace visual review.