/figure-spec

name: figure-spec
description: "Generate deterministic publication-quality architecture, workflow, and pipeline diagrams from structured JSON (FigureSpec) into editable SVG. Use when user says \"架构图\", \"workflow 图\", \"pipeline 图\", \"确定性矢量图\", \"figure spec\", \"draw architecture\", or needs precise, editable, publication-ready vector diagrams. Preferred over AI illustration for formal architecture/workflow figures."
argument-hint: "[description-of-diagram]"
allowed-tools: Bash(*), Read, Write, Edit, mcp__codex__codex

FigureSpec: Deterministic JSON → SVG Figure Generation

Generate publication-quality **architecture diagrams**, **workflow pipelines**, **audit cascades**, and **system topology** figures as editable SVG vector graphics using a deterministic JSON → SVG renderer.

When to Use This Skill

**Use `figure-spec`** for:

• System architecture diagrams (layered, hub-and-spoke, multi-plane)
• Workflow / pipeline figures
• Audit cascade / flow-control diagrams
• Any structured diagram where node positions, connections, and groupings are semantically important
• Figures that need to be edited/tweaked later (SVG is plain text)
• Figures where determinism matters (same spec → same SVG)

**Do NOT use for:**

• Data plots (bar/line/scatter) — use `/paper-figure`
• Natural/qualitative illustrations — use `/paper-illustration`
• Quick state-machine / flowchart — use `/mermaid-diagram` (lighter syntax)

Core Properties

• **Deterministic**: identical FigureSpec JSON always produces identical SVG output (for a fixed renderer version + fonts)
• **Editable**: SVG output is plain-text, can be post-edited by hand or programmatically
• **Validated**: renderer enforces schema, rejects malformed specs with clear error messages
• **Shape-aware**: edge clipping works correctly for rect/rounded/circle/ellipse/diamond
• **CJK support**: multi-line labels with proper Chinese character width estimation
• **No external API**: runs fully local, no network, no API keys

Tool Location

Phase 3.1 (Arch C) move: the canonical implementation now lives at `skills/figure-spec/scripts/figure_renderer.py` (this SKILL's own `scripts/` subdirectory). A backwards-compatible shim at `tools/figure_renderer.py` forwards to the canonical file via `os.execv`, so existing users with `.aris/tools/figure_renderer.py` or a manually copied `tools/figure_renderer.py` keep working unchanged.

Resolve `$FIGURE_RENDERER` with the hybrid chain (layer 0 prefers the self-contained location for the owning SKILL; layers 1-4 are the shared-runtime chain documented in [`shared-references/integration-contract.md`](../shared-references/integration-contract.md) §2, Policy A — skill-local gate):

# Layer 0: self-contained (CC 1.0+ exposes $CLAUDE_SKILL_DIR).
FIGURE_RENDERER=""
if [ -n "${CLAUDE_SKILL_DIR:-}" ] && [ -f "$CLAUDE_SKILL_DIR/scripts/figure_renderer.py" ]; then
  FIGURE_RENDERER="$CLAUDE_SKILL_DIR/scripts/figure_renderer.py"
fi
# Layers 1-4: shared-runtime chain (legacy compatibility + non-CC hosts).
if [ -z "$FIGURE_RENDERER" ]; then
  cd "$(git rev-parse --show-toplevel 2>/dev/null || pwd)" || exit 1
  if [ -z "${ARIS_REPO:-}" ] && [ -f .aris/installed-skills.txt ]; then
      ARIS_REPO=$(awk -F'\t' '$1=="repo_root"{print $2; exit}' .aris/installed-skills.txt 2>/dev/null) || true
  fi
  if [ -z "${ARIS_REPO:-}" ] && [ -f "$HOME/.aris/repo" ]; then
      ARIS_REPO=$(cat "$HOME/.aris/repo" 2>/dev/null) || true
  fi
  FIGURE_RENDERER=".aris/tools/figure_renderer.py"
  [ -f "$FIGURE_RENDERER" ] || FIGURE_RENDERER="tools/figure_renderer.py"
  [ -f "$FIGURE_RENDERER" ] || { [ -n "${ARIS_REPO:-}" ] && FIGURE_RENDERER="$ARIS_REPO/tools/figure_renderer.py"; }
  [ -f "$FIGURE_RENDERER" ] || FIGURE_RENDERER=""
fi
[ -z "$FIGURE_RENDERER" ] && {
  echo "ERROR: figure_renderer.py not resolved (layer 0: \$CLAUDE_SKILL_DIR/scripts/; layers 1-4: .aris/tools/, tools/, \$ARIS_REPO/tools/, \$ARIS_REPO/tools/ via ~/.aris/repo)." >&2
  echo "       /figure-spec cannot produce SVG output. Fix: rerun bash tools/install_aris.sh or smart_update.sh (refreshes ~/.aris/repo), or copy the helper from \$ARIS_REPO/skills/figure-spec/scripts/." >&2
  exit 1
}

Invoke:

python3 "$FIGURE_RENDERER" render <spec.json> --output <out.svg>
python3 "$FIGURE_RENDERER" validate <spec.json>
python3 "$FIGURE_RENDERER" schema

Workflow

Step 1: Understand the Diagram Goal

From `$ARGUMENTS` (description or path to `PAPER_PLAN.md` / `NARRATIVE_REPORT.md`), identify:

• **Purpose**: architecture, workflow, pipeline, audit cascade, topology?
• **Main entities**: what are the boxes?
• **Relationships**: how do they connect? (uses, produces, calls, verifies, chains)
• **Grouping**: do entities cluster into named regions?
• **Hierarchy vs network**: stacked layers, left-to-right flow, or central hub?

Step 2: Draft the FigureSpec JSON

Canvas sizing guide:

• Single-column figure: ~500×350 px
• Two-column (full-width): ~900×500 px
• Tall topology: ~700×700 px

Start from a template based on the diagram type:

**Architecture (stacked rows)**:

{
  "canvas": {"width": 900, "height": 520},
  "nodes": [
    {"id": "layer1_label", "label": "Layer 1", "x": 450, "y": 60, ...},
    {"id": "node_a", "label": "A", "x": 180, "y": 120, ...},
    {"id": "node_b", "label": "B", "x": 350, "y": 120, ...}
  ],
  "edges": [...],
  "groups": [
    {"label": "Layer 1", "node_ids": ["node_a", "node_b"], "fill": "#F0F9FF", "stroke": "#BAE6FD"}
  ]
}

**Workflow (left-to-right chain)**:

{
  "canvas": {"width": 900, "height": 300},
  "nodes": [
    {"id": "step1", "label": "Step 1", "x": 100, "y": 150, "shape": "rounded"},
    {"id": "step2", "label": "Step 2", "x": 280, "y": 150, "shape": "rounded"}
  ],
  "edges": [
    {"from": "step1", "to": "step2", "label": "produces"}
  ]
}

**Decision diamond**:

{"id": "check", "label": "Passes?", "shape": "diamond", "x": 450, "y": 200}

Step 3: Render and Validate