figure-spec

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. tools/figure_renderer.py is kept as a backwards-compatible os.execv shim so legacy layers continue to resolve. Codex-side install layouts that previously copied the canonical into ~/.codex/skills/figure-spec/figure_renderer.py must now place it at ~/.codex/skills/figure-spec/scripts/figure_renderer.py to match the new layout (re-run install_aris_codex.sh to pick up the new symlink target).

Resolve $FIGURE_RENDERER via the Codex-side hybrid chain (layer 0 preferred for self-contained owner SKILL; layers 1-4 are legacy shared-runtime compatibility):

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):

Workflow (left-to-right chain):

Decision diamond:

Step 3: Render and Validate

If validation fails, inspect the error (missing field, duplicate ID, overlap warning, invalid hex color) and fix the JSON.

Step 4: Visual Review

Open the SVG/PDF and check:

• No overlaps: nodes don't collide with each other or group boundaries
• Readability: font sizes are consistent, labels aren't clipped
• Edge clarity: arrows hit nodes at clean angles, labels near edges are legible
• Group alignment: background rectangles frame their members cleanly
• Color distinction: categories are visually distinct in both color and grayscale

If issues found, edit the JSON spec (never the generated SVG) and re-render.

Step 5: Iterate with Codex Review (Optional, for High-Stakes Figures)

For paper architecture figures, invoke fresh-agent review (same-family provisional in the base mirror):

Iterate until all three axes ≥ 7/10. The ARIS tech report figures went through 5 rounds of this loop to reach C:7/R:7/S:8.

Schema Quick Reference

Run python3 "$FIGURE_RENDERER" schema for the authoritative schema.

Nodes

Edges

Groups

Rectangular background regions framing a set of nodes:

Design Patterns

Pattern 1: Layered Architecture

Stack rows of related nodes, each row is a group, add inter-layer arrows with semantic labels (uses↓, produces↑, checks↓).

Pattern 2: Hub-and-Spoke

Central node (e.g., Executor), peripheral nodes (skills, tools), solid arrows for primary relations, dashed for feedback.

Pattern 3: Pipeline with Feedback

Left-to-right main flow, feedback arrows curve below with curve: true.

Pattern 4: Audit Cascade

Three-stage horizontal cascade with inputs feeding in from top, outputs exiting right, each stage in its own group.

Anti-Patterns

• Don't use groups as hierarchy: groups frame peer nodes, not containment
• Don't nest groups: renderer draws them as background rectangles; nested groups look like Russian dolls
• Don't cross-draw long diagonals: if an arrow crosses 3+ rows, rethink the layout
• Don't mix font sizes for same role: keep one size per node category

Output Contract

• SVG file in figures/ (vector, editable, hand-tweakable)
• Source FigureSpec JSON saved in figures/specs/ for reproducibility
• PDF version via rsvg-convert for LaTeX inclusion

Integration with Other Skills

• /paper-writing (Workflow 3): when illustration: figurespec (default for architecture figures), this skill handles Phase 2b
• /paper-figure: handles data plots; they complement each other (data + architecture = complete figure set)
• /paper-illustration: fallback for figures that need natural/qualitative style (method illustrations with photos, qualitative result grids)
• /mermaid-diagram: lighter alternative for simple flowcharts

Review Tracing

After each reviewer agent call, save the trace following shared-references/review-tracing.md (Policy C — forensic; never silently skip). Use save_trace.sh (resolved per the chain in shared-references/integration-contract.md §2) or write files directly to .aris/traces/<skill>/<date>_run<NN>/. Respect the --- trace: parameter (default: full).