figure-spec

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

FigureSpec: Deterministic JSON → SVG Figure Generation

FigureSpec：确定性 JSON → SVG 图表生成

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

通过确定性JSON→SVG渲染器生成出版级的架构图、工作流管线图、审计级联图和系统拓扑图，输出可编辑的SVG矢量图形。

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)

使用
figure-spec
的场景：

系统架构图（分层式、中心辐射式、多平面式）
工作流/管线图表
审计级联/流控图表
任何节点位置、连接关系和分组具有语义重要性的结构化图表
需要后续编辑/调整的图表（SVG为纯文本格式）
对确定性有要求的图表（相同规格→相同SVG输出）

请勿使用的场景：

数据图表（柱状图/折线图/散点图）——使用
```
/paper-figure
```
自然/定性插画——使用
```
/paper-illustration
```
快速状态机/流程图——使用
```
/mermaid-diagram
```
（语法更简洁）

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

确定性：相同的FigureSpec JSON在渲染器版本和字体固定的情况下，始终生成完全相同的SVG输出
可编辑：SVG输出为纯文本，可手动或通过编程进行后期编辑
已验证：渲染器会强制执行schema，对格式错误的规格文件返回清晰的错误信息
形状感知：边缘裁剪功能可正确处理矩形/圆角矩形/圆形/椭圆形/菱形
CJK支持：多行标签可正确估算中文字符宽度
无外部API：完全本地运行，无需网络，无需API密钥

Tool Location

工具位置

tools/figure_renderer.py

(from ARIS root). Invoke via:

bash

python3 tools/figure_renderer.py render <spec.json> --output <out.svg>
python3 tools/figure_renderer.py validate <spec.json>
python3 tools/figure_renderer.py schema

tools/figure_renderer.py

（位于ARIS根目录）。调用方式：

bash

python3 tools/figure_renderer.py render <spec.json> --output <out.svg>
python3 tools/figure_renderer.py validate <spec.json>
python3 tools/figure_renderer.py schema

Workflow

工作流程

Step 1: Understand the Diagram Goal

步骤1：明确图表目标

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?

从

$ARGUMENTS

（描述内容或

PAPER_PLAN.md

NARRATIVE_REPORT.md

的路径）中确定：

用途：架构图、工作流图、管线图、审计级联图还是拓扑图？
核心实体：图中的“框”代表什么？
关系：实体间如何关联？（使用、生成、调用、验证、链式连接）
分组：实体是否需要归为命名区域？
层级 vs 网络：是堆叠分层、从左到右的流，还是中心枢纽结构？

Step 2: Draft the FigureSpec JSON

步骤2：起草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):

json

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

json

{
  "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:

json

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

画布尺寸参考：

单栏图表：约500×350 px
双栏（全宽）：约900×500 px
纵向拓扑图：约700×700 px

根据图表类型从模板开始编写：

架构图（堆叠行）：

json

{
  "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"}
  ]
}

工作流图（从左到右链式）：

json

{
  "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"}
  ]
}

决策菱形：

json

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

Step 3: Render and Validate

步骤3：渲染与验证

bash

undefined

bash

undefined

Validate first

先验证

python3 tools/figure_renderer.py validate /tmp/spec.json

Render to SVG

渲染为SVG

python3 tools/figure_renderer.py render /tmp/spec.json --output figures/fig_arch.svg

Convert to PDF for LaTeX inclusion

转换为PDF用于LaTeX插入

rsvg-convert -f pdf figures/fig_arch.svg -o figures/fig_arch.pdf


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

rsvg-convert -f pdf figures/fig_arch.svg -o figures/fig_arch.pdf


如果验证失败，检查错误信息（缺失字段、重复ID、重叠警告、无效十六进制颜色）并修复JSON。

Step 4: Visual Review

步骤4：视觉审查

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.

打开SVG/PDF检查：

无重叠：节点之间、节点与分组边界无碰撞
可读性：字体大小一致，标签无裁剪
边缘清晰度：箭头以整洁角度指向节点，边缘附近的标签清晰可辨
分组对齐：背景矩形完整包裹所属节点
颜色区分度：分类在彩色和灰度模式下都有明显视觉差异

若发现问题，编辑JSON规格文件（切勿直接修改生成的SVG）并重新渲染。

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

步骤5：与Codex审查迭代（可选，适用于高优先级图表）

For paper architecture figures, invoke cross-model review:

mcp__codex__codex:
  model: gpt-5.4
  config: {"model_reasoning_effort": "xhigh"}
  prompt: |
    Review this SVG figure for a technical paper (architecture / workflow diagram).

    Spec file: /path/to/spec.json
    Rendered: /path/to/fig.svg

    Evaluate:
    1. Clarity (C): can a reader understand the system from this figure alone?
    2. Readability (R): font sizes, label placement, visual hierarchy
    3. Semantic accuracy (S): do relationships match the described system?

    Score each axis 1-10 and list specific issues to fix.

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.

对于论文架构图，调用跨模型审查：

mcp__codex__codex:
  model: gpt-5.4
  config: {"model_reasoning_effort": "xhigh"}
  prompt: |
    Review this SVG figure for a technical paper (architecture / workflow diagram).

    Spec file: /path/to/spec.json
    Rendered: /path/to/fig.svg

    Evaluate:
    1. Clarity (C): can a reader understand the system from this figure alone?
    2. Readability (R): font sizes, label placement, visual hierarchy
    3. Semantic accuracy (S): do relationships match the described system?

    Score each axis 1-10 and list specific issues to fix.

迭代直至三个维度得分均≥7/10。ARIS技术报告图表经过5轮此类循环，最终达到C:7/R:7/S:8。

Schema Quick Reference

Schema快速参考

Run

python3 tools/figure_renderer.py schema

for the authoritative schema.

运行

python3 tools/figure_renderer.py schema

获取权威schema。

Nodes

节点

Field	Required	Default	Notes
`id`	✓	—	Unique
`label`	✓	—	`\n` for multi-line
`x` , `y`	✓	—	Center coordinates
`width` , `height`		120, 50
`shape`		`rounded`	`rect` / `rounded` / `circle` / `ellipse` / `diamond`
`fill` , `stroke`		auto from palette	`#RRGGBB`
`text_color`		`#333333`
`font_size`		14	Override style default

字段	必填	默认值	说明
`id`	✓	—	唯一标识
`label`	✓	—	使用 `\n` 实现多行文本
`x` , `y`	✓	—	中心坐标
`width` , `height`		120, 50
`shape`		`rounded`	可选值： `rect` / `rounded` / `circle` / `ellipse` / `diamond`
`fill` , `stroke`		调色板自动分配	格式为 `#RRGGBB`
`text_color`		`#333333`
`font_size`		14	覆盖样式默认值

Edges

边缘

Field	Default	Notes
`from` , `to`	required	Same = self-loop
`label`	—	Short edge label
`style`	`solid`	`solid` / `dashed` / `dotted`
`color`	`#555555`
`curve`	`false`	Curved path

字段	默认值	说明
`from` , `to`	必填	相同值表示自环
`label`	—	简短的边缘标签
`style`	`solid`	可选值： `solid` / `dashed` / `dotted`
`color`	`#555555`
`curve`	`false`	是否使用曲线路径

Groups

分组

Rectangular background regions framing a set of nodes:

json

{"label": "Layer Name", "node_ids": ["a", "b", "c"], "fill": "#EFF6FF", "stroke": "#BFDBFE"}

用于框选一组节点的矩形背景区域：

json

{"label": "Layer Name", "node_ids": ["a", "b", "c"], "fill": "#EFF6FF", "stroke": "#BFDBFE"}

Design Patterns

设计模式

Pattern 1: Layered Architecture

模式1：分层架构

Stack rows of related nodes, each row is a group, add inter-layer arrows with semantic labels (

uses↓

produces↑

checks↓

将相关节点堆叠成行，每行作为一个分组，添加带有语义标签的层间箭头（如

uses↓

、

produces↑

、

checks↓

）。

Pattern 2: Hub-and-Spoke

模式2：中心辐射式

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

中心节点（如Executor），外围节点（技能、工具），实线箭头表示主关系，虚线箭头表示反馈。

Pattern 3: Pipeline with Feedback

模式3：带反馈的管线

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

curve: true

从左到右为主流程，反馈箭头设置

curve: true

并在下方弯曲。

Pattern 4: Audit Cascade

模式4：审计级联

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

不要将分组用作层级结构：分组用于框选同级节点，而非包含关系
不要嵌套分组：渲染器会将其绘制为背景矩形，嵌套分组会呈现类似套娃的效果
不要绘制长对角线交叉箭头：若箭头跨越3行以上，需重新设计布局
不要为相同角色的节点混用字体大小：同一类节点保持统一字体大小

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

SVG文件保存于
```
figures/
```
（矢量格式，可编辑，可手动微调）
源FigureSpec JSON保存于
```
figures/specs/
```
以保证可复现性
通过
```
rsvg-convert
```
生成PDF版本用于LaTeX插入

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

/paper-writing
（工作流3）：当设置
```
illustration: figurespec
```
（架构图默认选项）时，本技能负责处理第2b阶段
/paper-figure
：处理数据图表；二者互补（数据图+架构图=完整图表集）
/paper-illustration
：需要自然/定性风格图表时的备选方案（含照片的方法插画、定性结果网格）
/mermaid-diagram
：简单流程图的轻量化替代工具

Review Tracing

审查追踪

After each

mcp__codex__codex

mcp__codex__codex-reply

reviewer call, save the trace following

shared-references/review-tracing.md

. Use

tools/save_trace.sh

or write files directly to

.aris/traces/<skill>/<date>_run<NN>/

. Respect the

--- trace:

parameter (default:

full

每次调用

mcp__codex__codex

或

mcp__codex__codex-reply

审查后，按照

shared-references/review-tracing.md

保存追踪记录。使用

tools/save_trace.sh

或直接将文件写入

.aris/traces/<skill>/<date>_run<NN>/

。遵循

--- trace:

参数（默认值：

full

）。