research-figure

Safety Rules

See _shared/core/safety-rules.md — all safety rules are loaded from the shared layer.

Key addition:The generated SVG must have 0 failures to be considered complete. When the validation script reports FAIL, it must never be delivered; you must enter the refinement loop. Warnings (title outside the box, arc label offset) are acceptable but should be eliminated as much as possible.

Research Figure / Sketch-to-SVG

Turn the teacher's sketch into a research-grade SVG flowchart with no overlaps whatsoever. Core pain point: the instruction given to a large model, "draw a flowchart," is too vague; directly generated diagrams have overlapping boxes, overflowing text, and arrows pointing the wrong way. Solution:First have the large model read the sketch to extract the precise layout, then use a grid template to generate the SVG, and finally automatically validate to 0 errors。

The key insight: natural-language instructions are too coarse for precise figure layout. The fix: have a vision LLM read the sketch first and extract a structured layout, then generate SVG on a grid system where overlaps are impossible by construction, then auto-validate.

Quick Commands

Command	Description
/画图 <草图>	Read sketch → convert to JSON → generate SVG → validate → refine (complete workflow chain)
/画图 from-json <layout.json>	Generate SVG from layout.json
/画图 from-text "<描述>"	Generate from a text description (no sketch)
/画图 validate <file.svg>	Validate an existing SVG for overlap/out-of-bounds
/画图 template	Show grid template usage
/fig <sketch>	English alias for the full pipeline
/fig from-json <layout.json>	Build SVG from layout.json
/fig from-text "<description>"	Build from text description
/fig validate <file.svg>	Validate an SVG

Core Philosophy

Distilled from a real experience: a teacher sent a hand-drawn sketch and asked for help drawing a flowchart, and it took over an hour of fiddling. The most core problem is not "can't draw it," butrefinement and fine-tuning—diagrams directly generated by a large model always have overlaps, overflow, and misaligned arrows, and vague instructions like "change it again" can't fix them. In the end, use a large model toread the sketch, converting vague visual information into a precise structured layout description (layout.json), then generate with a grid system, passing on the first try.

Four iron rules:

1. Grid positioning, not eyeballing. Each box is placed in a grid cell, coordinates are computed by the template, and two boxes occupying different cells will not overlap—structurally impossible.
2. Read the image and convert it to a prompt. Sketch → multimodal model → layout.json → grid code. Turn "draw something roughly" into "box A is at (0,0) occupying 1×2 cells, box B is at (0,2) occupying 1×2 cells, arrow A.right→B.left."
3. Text must be inside the box. The template automatically wraps lines and automatically shrinks the font size (minimum 9pt), ensuring text does not overflow the box.
4. Validation is mandatory after generation。validate_svg.py checks 8 items, and it is only complete with 0 failures.

Five-Step Workflow

Step 1  读草图 Read Sketch
   把草图发给多模态大模型（GPT-4o/Claude/Gemini），用结构化提示词
   让它输出 layout.json（框列表+箭头列表+标签）。
   详见 rules/vision-to-prompt.md

Step 2  转网格代码 Map to Grid
   把 layout.json 的 grid_hint 映射到网格行列，生成 svg_template.py 代码。
   映射表见 rules/workflow.md。

Step 3  生成 SVG Generate
   执行代码生成 SVG。

Step 4  校验 Validate
   python scripts/validate_svg.py figure.svg
   检查：越界/文字溢出/框重叠/文字重叠/字号/箭头连接/id重复。
   目标：0 failures。

Step 5  精修循环 Refine Loop
   有 fail/warn 时按修复表调整（增大框/缩短文字/调curve），重新生成+校验。
   典型2-3轮收敛。

Key Implementation Notes

• Grid system：svg_template.py 's Figure class divides the canvas into cols×rows cells,fig.box(name, row, col, rowspan, colspan) places boxes. Different boxes occupy different cells → naturally no overlap.
• Named anchors: each box has 8 compass anchors + n/s/e/w/center.fig.arrow("a", "right", "b", "left") connects arrows, never left floating.
• data-intent exemption: text inside a box and an arrowhead touching a box edge are "intentional overlaps"; declare them with data-intent="label-of-box-X" and the validation script exempts them accordingly.
• Automatic line wrapping and font shrinking: when text exceeds the box width, lines are wrapped by character count (CJK is full-width, Latin is 0.6× font size); when the wrapped text exceeds the box height, the font size is automatically reduced (minimum 9pt).
• Colorblind safe: Wong palette (#0072B2, #E69F00, #009E73, ...) + soft pastel fills.
• Validation of 8 items: Out of bounds (WARN), text outside frame (WARN), text overflow (FAIL), frame overlap (FAIL), text overlap (WARN), font size <9pt (WARN), floating arrow (WARN), duplicate id (WARN).

See scripts/svg_template.py(grid template, ~280 lines) and scripts/validate_svg.py(validator, ~290 lines, pure standard library with no dependencies).

Rules

• rules/workflow.md - Complete five-step workflow, command-line operations, quality gates
• rules/vision-to-prompt.md - Prompts for converting sketches into structured JSON, grid_hint mapping table, refinement and repair table
• rules/layout-spec.md - SVG layout specification, grid system, anchors, color scheme, data-intent markers, validation check items

Applicable Scenarios / Supported Scenarios

• A teacher provides a sketch and asks for help drawing a research flowchart/architecture diagram/system block diagram
• There is a hand-drawn sketch photo/scan that needs to be turned into clean SVG
• There is only a text description and a structured flowchart needs to be generated
• There is an existing PPT draft that needs to be converted into publication-grade SVG
• Strict scenarios that require ensuring frames do not overlap, text does not overflow, and arrows do not float
• Research diagrams that require bilingual Chinese-English labels
• Publication diagrams that require colorblind-safe color schemes

Verification / Verification

python tests/test_skill.py       # 16项自验证
pytest tests/test_skill.py -v

Coverage: template generates valid SVG, validation passes a good composition, validation catches frame overlap, validation catches text overflow, JSON generation, multi-line text, CJK text, arrow connections, complete viewBox, feedback loop, 6-frame 6-arrow end-to-end complex diagram.

Dependencies / Dependencies

• Required: Python standard library (xml.dom.minidom, math, re) — both the validation script and the template script are pure standard library, with zero external dependencies
• Read sketch: multimodal large model (GPT-4o / Claude / Gemini) — provided by the caller; this skill only provides the prompts
• Optional：PySide6(GUI, future plan)
• Depends on _shared/core/safety-rules.md

File Structure

skills/research-figure/
├── README.md
├── SKILL.md
├── rules/
│   ├── workflow.md              # 五步工作流与命令行操作
│   ├── vision-to-prompt.md      # 读图转提示词、grid_hint映射、精修修复表
│   └── layout-spec.md           # SVG布局规范、网格系统、校验检查项
├── scripts/
│   ├── svg_template.py          # 网格SVG模板（~280行，纯标准库）
│   ├── validate_svg.py          # SVG校验器（~290行，纯标准库）
│   └── generate_from_json.py     # 从layout.json生成SVG
└── tests/
    └── test_skill.py            # 16项自验证测试

Version History / Version History

Version	Date	Change
1.0.0	2026-08-16	Initial version: sketch-reading workflow chain, grid SVG template, automatic validator, 16 self-verification items

See Also / Related Skills

• /论文 from academic-writer — when writing academic papers, illustrations are needed; this skill generates the diagrams, academic-writer writes the text
• /paper figures from academic-writer — general chart quality standards (this skill focuses on the structured generation of flowcharts/architecture diagrams)