/architecture-drawer

name: architecture-drawer
description: Use when asked to draw system architecture diagrams, generate technical architecture SVGs, or export architecture diagrams to editable PowerPoint presentations. Supports multi-layer diagrams with automatic layout validation and scoring (16-dimension evaluator catches collisions, overlaps, dangles, crossings, palette issues incl. colorless and gray-dominant diagrams, low-contrast labels, misaligned peers, and a Step-1 design-brief contract: the declared palette/layout/flow is asserted against the rendered SVG).

SVG Architecture Drawer (Smart Version)

This Skill converts complex technical descriptions into structured SVG architecture diagrams. It integrates layout constraints, collision detection, **connection/arrow connectivity validation**, and quality evaluation, automatically identifying and guiding the correction of layout errors. The script directory (referred to as `$SKILL` below) is this skill's own `scripts/` folder. From a generator script that lives next to its artifacts, resolve it relative to the script's own location (never hard-code an absolute path, which breaks on other machines):

import os, sys
_HERE = os.path.dirname(os.path.abspath(__file__))
# From evals/<name>/gen.py -> ../../scripts ; adjust depth for your layout.
_SKILL = os.path.normpath(os.path.join(_HERE, "..", "..", "scripts"))
if _SKILL not in sys.path:
    sys.path.insert(0, _SKILL)

Fast Path (read this first; details below are on-demand reference)

Ordinary generation follows this bounded loop. Do not read the full specification sections before the first candidate runs — the checks below tell you what to fix, and each section explains its own vocabulary when a report line names it.

**Strategy — the evaluator is the oracle, not your own verification.** Do not read `scripts/evaluator.py` to internalize every threshold, and do not mentally verify the layout against all 16 checks before writing: that duplicates work the evaluator does in under a second. Sketch an approximate layout with sane coordinates, run `gen.py`, read the report lines, and fix exactly what they name (thresholds + repairs are tabulated in `references/checks_cheatsheet.md` — read that table instead of the evaluator source).

**Do the arithmetic in code, not in your head.** `references/api_quickref.md` tabulates every DSL signature + the known traps (which default draws an arrow, text-y semantics, container `node_kind`), and the layout helpers (`layout_grid` / `layout_row` / `layout_band` / `layout_radial`) compute positions from the array spec — state "6 chips, 3 per row, 24px gutters", not forty hand-derived coordinates. Start from the skeleton in `references/gen_template.md` (constants block for bands/nodes/flow, fixed evaluate-export tail) instead of re-deriving the boilerplate.

1. **Write the candidate** — resolve `$SKILL` (snippet above), pick ONE palette preset from `references/design_specs.md` (do not invent hex values), land the Step-1 design-brief tokens as a constants block atop `gen.py`, draw with `drawer.rect/circle/connect` (register `node_id`s so connections validate), then immediately run the script. One clear main flow beats a dense map; ≤12 primary nodes before the first evaluation. 2. **Evaluate** — `evaluate_svg(drawer)` prints the score; every `[FAIL]` line names the defect class (dangle / route-through / crossing / text overlap / contrast / palette). Fix exactly what the lines name; the Auto-Correction section maps each tag to its repair. 3. **Bounded repair** — at most **2 focused correction rounds** on the highest-penalty FAILs (call `auto_refine(drawer)` first: gutter and spacing fix themselves). If the score reaches ≥80 with no `[FAIL]` remaining, ship. If two rounds do not converge, stop and report the unresolved `[FAIL]` lines truthfully — never claim success with defects outstanding, and never widen the canvas or shrink text to hide them.

digraph fastpath {
    "write candidate" -> "evaluate_svg()" -> "auto_refine + fix FAILs";
    "auto_refine + fix FAILs" -> "evaluate_svg()" [label="round ≤2"];
    "auto_refine + fix FAILs" -> "ship (score≥80, 0 FAIL)" [label="clean"];
    "auto_refine + fix FAILs" -> "report unresolved FAILs truthfully"
        [label="2 rounds spent"];
}

Step 0 — Intent Judgment (fidelity vs. completion)

Before writing any code, classify the requirement — the two failure modes are mirror images: transcribing a vague spec literally produces a broken diagram, and "improving" a precise spec produces one the user did not ask for.

**Faithful mode** — the description is clear and detailed (explicit components, relations, flow direction, canvas): transcribe it exactly. Do **not** invent components, layers, edges, or legend entries the user did not state, and do not "upgrade" the palette or topology on your own taste. Adding unrequested boxes is a defect, not a feature (画蛇添足).

**Completion mode** — the description is vague (the user may not have a fixed picture in mind yet): infer a reasonable design, then state what you inferred. Ambiguity signals and the corresponding conservative defaults:

| Missing in the spec | Conservative default | |---|---| | Relations between named components | connect adjacent tiers only, in the domain's natural flow (client → API → compute → storage) | | Canvas / size | 1200×800 (or the diagram-type preset in `references/diagram_types.md`) | | Diagram type | pick from `references/diagram_types.md` by content keywords | | Layer grouping | group only when the spec's own vocabulary implies it ("… layer", "… module") | | A composite-sounding component ("gateway", "engine") | stays ONE node — never split into sub-nodes the user did not mention |

Completion rule: an addition is legitimate only when the diagram is structurally incoherent without it — never decorative. List every assumption in the final reply ("assumed top-to-bottom flow; inferred gatewa