The main deliverable isan editable .drawio, with PNG/PDF as accompanying exports. Templates, hand-writing, replication, validation, preview, and export are all within this directory.
First determine which path to take
| Situation | Path | Entry point |
|---|---|---|
| Overall structure, research framework, execution flow, or task breakdown of a project | A Apply template | Template index below |
| Other diagrams: algorithm flow, model architecture, experimental design, mechanism illustration… | B Hand-write XML from scratch | references/authoring.md |
| A reference image is provided, and it needs to be redrawn as an editable vector diagram | C High-fidelity replication | references/replication.md |
The XML writing for the three paths is consistent, and the deliverables can be further edited interchangeably; the only difference isthe strictness of process discipline。
A. Apply template
| Template id | Layout | Suitable for expressing | Description |
|---|---|---|---|
roadmap-5band |
954×1296 portrait, five dotted bands + left flag labels + right vertical labels | Raise the problem → data and metrics → methods and mechanisms → result comparison → evaluation and promotion | references/roadmap-5band.md |
framework-3col |
1026 wide, three columns, left stage chain / middle content blocks / right method list, height adaptive | Researchcontentpanorama: which research content each stage corresponds to and what methods are used | references/framework-3col.md |
stageflow-3col |
1000 wide, three columns, each block in the middle column has a solid-color title bar + independent color scheme, height adaptive | Research/systemexecution flow: stage progression, decision branches, deliverable distribution | references/stageflow-3col.md |
taskflow-land |
Landscape 1360 wide, several task blocks, pipeline within each block + method details attached to each step | Break the project into "Task 1…Task 4"; each step must clearly state the method and conclusion; suitable for 16:9 | references/taskflow-land.md |
- Read the two sections of the template description:semantic conventions(which slots are parallel, which converge, and which two groups must be comparable) andword-count budget. Putting semantics in the wrong place is more serious than exceeding the word count.
- Extract content from user materials,do not make it up; when source files are available (
.tex/.md/code), verify each value one by one, and use the original terminology. - Copy
assets/<template_id>/example.jsonand rewrite,"\n"manually break lines. - Render (validate the word count slot by slot before writing the file; report the specific budget when exceeding the frame):
python3 scripts/roadmap_5band.py content.json -o out.drawio # 模板 roadmap-5band
python3 scripts/framework_3col.py content.json -o out.drawio # 模板 framework-3col
python3 scripts/stageflow_3col.py content.json -o out.drawio # 模板 stageflow-3col
python3 scripts/taskflow_land.py content.json -o out.drawio # 模板 taskflow-land（横版）
For adding new templates, see references/adding-templates.md。
B. Hand-write XML from scratch
Read references/authoring.md: skeleton, style quick reference, Chinese character width budget, connector writing, and four pitfalls you will definitely encounter. For icons and special primitives, see references/icons.md。
The three most likely to go wrong:
- Lay out the grid before writing primitives: fix the canvas, column baselines, and step spacing; same family, same width, same spacing; use an equal-division formula for groups with variable counts.
- Manual line breaking for Chinese: Full-width ≈ font size, half-width ≈ font size/2, line height ≈ font size+3; at 16px font size, a 160px-wide box fits at most 9 Chinese characters per line. For vertical text, stack character by character
<br>,do not usehorizontal=0(Chinese characters will lie sideways). - Connector endpoints are 1px from the box edge; one-to-many/many-to-one should be drawn as a "vertical line + horizontal bus + branches", not as N independent diagonal lines.
Before drawing, think clearly about the semantics of each arrow (who goes to whom, one-way or two-way, fan-in or fan-out); do not draw arrows whose meaning you cannot state.
C. High-fidelity reproduction of the reference image
One more evidence chain than B; follow references/replication.md to execute. Key points:
- Calibrate before drawing: extract box coordinates and fill colors via connected components, find frame lines by row/column scanning, obtain the color scheme by color census, and infer font size by measuring character width.Do not eyeball it, and do not assume "the title must be larger than the body text".
- Four intermediate artifacts：
visual-spec.md(what was seen),layout-grid.md(coordinate plan),asset-ledger.md(which parts are approximate, to prevent silently dropping elements),defect-log.md(after the first screenshot, only add, never modify). - ≥3 roundsof "screenshot → nine-zone inventory → fix all P0/P1 → re-render → verify item by item"; the screenshot must be the canvas itself.
- Red-team review + self-scoring rubric(see
references/self-check.md): if the total score is <40 or any dimension is ≤4, do not deliver. - Use pixel diffing to locate residual differences, and write them item by item into
defect-log.md; do not write "perfectly restored".
General: validation, preview, export
python3 scripts/check_layout.py fig.drawio # 溢出/越界/重复 id/重叠/穿盒/位图（--strict 作门禁）
python3 scripts/export_figure.py fig.drawio # 1:1 PNG + 矢量 PDF（需 drawio 命令行）
python3 scripts/preview_html.py fig.drawio # 浏览器预览，无需 drawio 命令行
check_layout uses a Chinese character-width model and has low noise; a normal diagram should FAIL 0 / WARN 0; if it alarms, it is worth looking at carefully. It deliberately does not check row/column spacing of tightly stacked items or same-family size alignment (the former is intentional layout, and the latter will inevitably produce false positives when a machine judges families)—leave these two to the eyes. For detailed rules and four avoidance techniques, see references/preflight-rules.md。
If you have not looked at the rendered image, it is not finished: text overflow, arrows pressing on text, and squashed boxes cannot be seen in XML. Open the PNG and go through at least two rounds: ① text overflow/line collision; ② arrow direction and semantics; ③ same-family elements aligned and equal width; ④ whether any values were copied incorrectly. For the complete nine-zone inventory and delivery checklist, see references/self-check.md。
Deliver .drawio + PNG/PDF; when using the template path, keep the content JSON as a reproducible source. Size reminder: a 954px-wide diagram with 16px font size, when compressed into A4 body text 0.97\textwidth is about 6.5pt; it is recommended to use landscape full-page or for presentations, and make a simplified version separately for small inline figures.
Reference index
| File | When to read |
|---|---|
authoring.md |
Hand-drawn schematic: skeleton, style strings, character-width budget, connectors |
icons.md |
When you need special graphic primitives such as icons, flags, block arrows, curved arrows, etc. |
roadmap-5band.md |
Use the five-band roadmap template |
framework-3col.md |
Use the three-column research framework template (content panorama) |
stageflow-3col.md |
Use the three-column stage process template (execution process) |
taskflow-land.md |
Use the horizontal task pipeline template |
adding-templates.md |
Add a new template |
replication.md |
Reproduce the reference image: calibration method, four artifacts, iterative loop |
self-check.md |
Nine-zone inventory, red-team review, self-scoring rubric, delivery checklist |
preflight-rules.md |
What static checks are checking, and how to avoid false positives |
Not applicable
- Line charts, heatmaps, statistical charts, etc.Data charts → use
scibox-figureSkills; - Formula derivation chains that require LaTeX typesetting → use TikZ or write them into the main text.