svg-book-illustrator

SVG Book Illustrator

Generate concise and professional SVG technical illustrations for book chapters and formal articles.

This Skill generatesstatic SVG, directly embedded into Markdown files (<svg> tags), with a style that is concise and professional, transparent background + coloring categorized by template semantics (v1.7.0: hierarchy types layer/tree/pyramid use G1-G4 grayscale gradient; diversity types flow/matrix/hub/cycle use the P1-P8 multi-hue palette), suitable for print publication.

Quick Start

/svg-book-illustrator @path/to/chapter.md

Core Workflow

Phase 1: Analyze the chapter, plan illustrations

1. Read the chapter Markdown file
2. If references/diagram-catalog.md has predefined illustrations for the current chapter, match them
3. Scan the chapter content and identify locations suitable for illustrations:
   • Architecture description locations ("X layer", "system", "architecture", etc.)
   • Process description locations ("step", "process", "phase", etc.)
   • Comparison description locations ("vs", "comparison", "before and after", etc.)
   • Hierarchy description locations ("hierarchy", "classification", "pyramid", etc.)
   • Cycle description locations ("cycle", "iteration", "closed loop", etc.)
   • Ecosystem/relationship description locations ("ecosystem", "elements", "relationships", etc.)
   • Multi-dimensional numerical comparison description locations ("dimensions", "capability assessment", "theory vs practice", "domestic vs international comparison", "model fit", etc.) → radar
   • Skill introduction/structure description locations ("Skill", "SKILL.md", "three-piece set", "references/scripts", "input→output", etc.) → skill-card
   • Multi-role/multi-subject time progression description locations ("timeline", "multi-role", "progression", "nodes", "statute of limitations", "case process", etc.) → timeline-lane
   • Two-dimensional cross-reference description locations ("risk × clause", "feature matrix", "coverage", "cross-reference", "assessment table", etc.) → matrix-grid
   • Three-category/three-version parallel description locations ("three types", "three categories", "three columns", "three options", "three approaches", etc.) → three-col
4. Insert a placeholder at the appropriate location [[FIG:N:简要描述]](N starts numbering from 1)
5. List all planned illustrations (type, location, description); unless the user explicitly requests confirmation first, continue generating the SVG

Illustration density: use "one illustration per section" per chapter as the baseline, 6-8 illustrations for chapters of tens of thousands of words, prefer quality over quantity; pure walkthrough / summary sections may omit illustrations to avoid redundancy. Density metrics:illustrations/section ≥ 0.7, illustrations/10,000 words ≥ 0.8, if below this it is judged "too few" and prompts for locations to add illustrations (see Phase 4 + references/review-checklist.md）。

Phase 2: Generate SVG

After completing illustration planning, generate them one by one:

1. Select a layout template based on the illustration description (flow / layer / matrix / hub / tree / cycle / radar / skill-card / timeline-lane / matrix-grid / three-col, or a combined template)
2. Read references/layout-templates.md to obtain the template specifications
3. According to references/style-guide.md design specifications, generate the SVG code
4. In <svg> root, write the unique identifier for the current project data-figure-id="fig-chNN-sN-NN"; in the template, fig-template-* is only an example and must be replaced before finalizing
5. Embed the <svg> tag into Markdown, replacing the corresponding placeholder
6. Add a caption below the SVG:**图 N-X：图标题**

Phase 3: Archiving

After generation is complete, extract all SVGs to standalone files:

python scripts/extract_svgs.py path/to/chapter.md --output output/figures/

Phase 4: Review and Acceptance (must pass four gates)

After generation + embedding, review each chapter against the review gates, see references/review-checklist.md：

① Illustration density review: figures/section ≥ 0.7, figures/10k words ≥ 0.8; below that is judged "too few", and sections that can be supplemented are listed. Cross-chapter balance—density should not change abruptly between adjacent chapters (the density of cognition/introductory chapters should not be far lower than that of methods/practical chapters).

② Figure-body argument consistency review: trace each figure back to its section, and check that node count / hierarchy names / flow direction / comparison dimensions are consistent with the body text; when replacing mermaid / ASCII figures, the original information (nodes, relationships, labels) is not lost; captions accurately summarize the figure content, without exaggeration or omission.

③ Character width/coordinate hard-calculation self-check (v1.8.5+, before visual inspection): after the generator produces output, according to CJK≈Fpx/char, Latin≈0.55Fpx/char estimate text width ≤ container width, adjacent element y difference ≥ 20px, viewBox H sufficient—calculation gate, to prevent visual inspection from missing "slight overflow/too close" (the two cases of v1.8.5 radar legend overlap and three-col sub-card overflow were both caught by this). See references/review-checklist.md §③。

④ Visual inspection (eye check after multimodal rendering): render SVG to PNG with a controlled font (run for quick preview python3 scripts/render_svg.py input.svg output.png; run at high DPI node scripts/svg2png.js input.svg output.png 300), then use a multimodal model to check each one—text does not overflow the container, boxes do not overlap (spacing ≥24px), arrows are placed in the correct direction, semantic lines are not accidentally deleted, branches are continuous, label cards and numbering are clear, font size is readable (nodes ≥16px, secondary ≥12px), distinguishable in black and white, overall aesthetics with reasonable whitespace. If problems are found, revise the SVG coordinates and recheck until visual inspection passes.

Multimodal production tip: if the environment supports image understanding, ④ must actually "look" at the rendered image, and cannot rely only on xmllint / rsvg passing without warnings as indirect verification—syntax passing ≠ layout aesthetics; overflow/overlap/arrow misalignment can only be found by the naked eye (or a multimodal model). But visual inspection easily judges "slight overflow/too close" as OK, so ③ character width hard-calculation self-check must be passed first.

Shape containment narrow semantics (v1.8.10+): by default, shape/shape containment or overlap is treated as a pending layout issue to fix; change coordinates first, and do not use data-overlap-role="decoration"、data-allow-overlap or any self-invented role to conceal it. Only when the outer area shape genuinely carries container semantics such as "panel hosting inner information cards" may the outer layer be written with the single-figure unique safe native id、data-overlap-role="container", a data-overlap-note that explicitly indicates the containment relationship, and a hex/rgb/hsl fillthat can be statically proven non-transparent; namespaced fake attributes, transparent/inherited/paint server/zero-opacity containers, and isolated notes are all invalid. This declaration only makes the intent auditable, not proving the geometry is correct; ultimately it must be reviewed by writing-reviewer v0.16+ render gate with real browser geometry, and the actual hit outer / inner / reason recorded in evidence. See references/style-guide.md §6 and references/review-checklist.md §⓪/④。

Generator contract regression (v1.8.9+): after modifying scripts/gen-*.py or references/layout-templates.md , you must run:

python3 -m unittest discover -s scripts/tests -p 'test_*.py' -v

Only an exit code of 0 allows entry into the merge candidates. This test actually runs all generators and checks all SVG code blocks in the template document; the viewBox must be strictly 0 0 720 H, and the root width must be 720,height must equal H;data-figure-id must exist, be format-safe, and not be duplicated within the same batch of artifacts; XML,<style>, element style=, any element's font-family, and any non-compliance in class/CSS variables or background rectangles will fail. Any data-overlap-role must also strictly satisfy the above container + 单图唯一原生 id + 明示承载关系的 note + 外层 area shape + 非透明 hex/rgb/hsl fill narrow contract; namespaced attributes, orphan notes, inherited/transparent/paint server fill,decoration and self-invented roles fail directly.

Production identity contract (v1.8.9+): downstream review / render inventory binds cross-round findings and rendering evidence to the SVG root's data-figure-id , and can no longer rely on "which image" or file traversal order. The 5 generators by default take a stable ID from the output file stem, and also support explicit specification:

python3 scripts/gen-radar.py figures/fig-ch03-s2-01.svg --figure-id fig-ch03-s2-01

Safe values only allow 1–128 characters of letters, digits, dots, underscores, or hyphens. Before writing into the manuscript, a project-unique fig-chNN-sN-NNmust be used; the default stem is only a convenience value and cannot replace a project-level uniqueness check.fig-template-* is only for the template itself and must not enter the manuscript as-is. This contract only constrains SVGs newly generated or newly committed in v1.8.9+, and does not require retroactively modifying historical manuscripts; whether historical assets are migrated is decided separately by the project.

In-repo .github/workflows/svg-book-producer-contract.yml will automatically run the same command when this Skill or the workflow itself has PR changes, and when related changes are pushed to main . Without an explicitly passed Source producer contract check, generator changes should not be regarded as mergeable. This CI only proves the source SVG production contract, and does not replace controlled font rendering, pixel-equivalence verification, or multimodal visual inspection.

Controlled font rendering (v1.8.9+): to ensure Markdown/Obsidian compatibility, source SVGs do not embed <style> or font stacks; export tools uniformly read a single authoritative source assets/render-fonts.css：

# 快速预览（librsvg；固定外部 CSS + 宽 720，不指定高度）
python3 scripts/render_svg.py input.svg output.png

# 高 DPI（Puppeteer/Chrome；注入同一外部 CSS）
node scripts/svg2png.js input.svg output.png 300

# 修改字体接线、身份元数据或 SVG 生成器后：逐像素比对两类基线
python3 scripts/verify_render_font_equivalence.py

It is forbidden to use bare rsvg-convert results as acceptance evidence: it renders with the environment default font, and has been measured to produce serif degradation and pixel drift. Browser previews may inherit host fonts, but formal export/acceptance must go through the above controlled entry point. The pixel-equivalence script simultaneously compares two baseline sets: "old embedded fonts vs external fonts" and "no ID vs with ID"; it is local rendering regression evidence, requires rsvg-convert and ImageMagick to already be available on the machine, is not part of the GitHub Actions check that only validates the source contract, and does not replace per-image visual inspection.

---

Layout templates

13 layout templates (11 basic + 2 combined), see references/layout-templates.md。

Template	Applicable scenarios	Typical element count
flow	Flowcharts, step diagrams, pipeline diagrams	3-5 nodes (horizontal ≤4)
layer	Hierarchical architecture, layered stacking	3-4 layers
matrix	Before-and-after comparison, side-by-side comparison	2 columns
hub	Hub-and-spoke, ecosystem relationships	1 core + 4-8 peripheral
tree	Hierarchical structure, organization chart, pyramid	3 layers
cycle	Cyclic process, iterative closed loop	4-6 nodes
radar（v1.8.0）	Multi-dimensional numerical comparison (theory vs actual / capability assessment / domestic vs international / model fit)	6-12 dimensions, 1-2 series
skill-card（v1.8.1）	Structure of a single Skill (input → Skill trio + process → output)	1 Skill + 3-5 steps
timeline-lane（v1.8.2）	Multi-role/multi-subject time progression (litigation multi-role timeline/case process nodes)	3-5 swimlanes, 2-5 events per lane
matrix-grid（v1.8.3）	Two-dimensional cross-comparison (risk × clause / feature × product / capability × model)	N×M grid (3-6 × 3-7)
three-col（v1.8.4）	Three-category/three-version parallel juxtaposition (each column with sub-cards)	3 columns × 3-4 sub-cards
flow+matrix	Progressive process with stage comparison	3-4 stages + comparison area
flow+hub	Node expansion within an orchestration process	Main process + expanded nodes

---

Design specification

See references/style-guide.md. Core points:

• Canvas：720px fixed width (16mo 115mm full-measure physical size), height cropped to content(v1.7.1) — viewBox="0 0 720 H", H = maximum y of the content bottom edge + 40px;no longer fixed at 400(a fixed 400 would leave excessive blank space at the bottom of diagrams with little content, and the spacing between the SVG lower edge and the figure caption would vary unpredictably).Transparent background (hard constraint)— do not draw a background rectangle or set a base color; left, right + top safe margin 40px, bottom = H − content bottom (i.e., 40px). The base color is provided by the book page/layout.
• Canvas reclamation after element deletion (v1.9.2, design-evolution debt discipline): when deleting any visible element within a diagram — historically designed top "marker title", explanatory bar, abandoned node/group — you mustsynchronously tighten the viewBox and explicit height, so that blank space returns to the standard (first content about 24-40px from the top edge, 40px safe margin on all sides). "Deleting elements without deleting space" is the technical debt of multiple rounds of revision: real project evidence — after the early top marker title design was wholly removed without reclaiming the canvas, 4 diagrams left large areas of information-free blank space above the book page, ultimately requiring a book-wide unified review and correction (Figures 7-2/8-4/11-7/13-1). Accompanying check standard: final-manuscript scan --padding only blocks "insufficient margin"; "excessive blank space" cannot be mechanically distinguished from intentional grouping blank space, and is covered by visual re-review — therefore this discipline constrainsthe moment of the deletion action, not after-the-fact cleanup.
• Style: concise, professional, static (no animation, no gradient, no filter, no emoji)
• Color (v1.5.0 transparent background + internal module multi-color version): newly generated diagramstransparent base, color is used for multi-color soft differentiation among different modules / branches / directions / levels within the SVG— colors as diverse as possible (4-6 or even more soft module colors per diagram). Select 1 group from 8 predefined palettes (P1 mist blue series / P2 light cyan series / P3 tender green series / P4 warm beige series / P5 light purple series / P6 light pink series / P7 warm gray series / P8 mixed soft series), and within the group assign 5-6 soft module colors in order as "module 1 takes color 1, module 2 takes color 2…", with adjacent modules in different colors. Text color is uniformly dark gray #2D3436/#636E72 to ensure readability. Print-friendly constraints (contrast between text and the fill color of the module it is in ≥4.5:1 WCAG AA, differentiation between adjacent modules ≥10%, module color lightness L*≥80, no high-saturation fluorescent colors, no CMYK color shift, grayscale difference ≥10%).Only newly generated diagrams use the new color scheme; the existing 34 white-background single-color SVGs on main remain stable and are not changed back。
• Color syntax hard constraints: colors only use fill/stroke inline attribute—no <style> block defining colors, no <svg> open tag writing font-family, no CSS variables/classes, no drawing background rectangles(verified Obsidian rendering + transparent background hard constraint, see references/style-guide.md §5.4）。
• Visually friendly coloring and rendering taboos (v1.8.7 hard constraints, see references/style-guide.md §5.5）：① Dark background with light text—dark fill (L* ≤ 50, e.g. #2C5282/#1A202C/G4 dark tier/project canonical accent color) within the module <text> must use #FFFFFF/#EDF2F7，no dark background with dark text；② Text color contrast—text fill vs. its module fill contrast ≥ 4.5:1 (AA, large text ≥ 3:1); ③ Arrow endpoint—marker single id="arrow" + markerUnits=userSpaceOnUse + orient=auto, endpoint x2 = 目标框边 − 4px, direction pointing to target node; ④ Text integrity—every node box with title semantics has non-empty <text>, text coordinates inside the box, fill different color from the module. Source T134 review measured: Figure 7-6 arrow misalignment / Figure 11-8 unreadable text color / Figure 11-9 dark blue background with dark text / Figures 7-13/8-3/6-7 missing text inside boxes.
• Blue focus + two-tier text (v1.8.8 general rule, DEC-020, see references/style-guide.md §5.0/§5.1）：① Unified two-tier dark gray text color—all text in the figure allows only #2D3436(primary)/#636E72(secondary), on dark backgrounds use #FFFFFF/#EDF2F7；no longer use #1A202C/#4A5568(converge to two tiers to eliminate four-tier mixing). ② Project canonical primary color (e.g. #2C5282/#1A365D blue) only used for focus node fill/stroke, forbidden as text fill—use color blocks to carry emphasis, switch text emphasis to font weight/size; this is general discipline, not a project pointer (applies whenever any project locks a primary color as visual identity). ③ Every structural/flow diagram ≥1 focus node—layer/tree/flow/hub/cycle/matrix should have at least 1 focus node (canonical primary color or one tier darker fill/stroke) carrying hierarchy, opposed to pure gray flat layout; when a pure parallel list has no natural focus, use grayscale progression + border thickness distinction. Source Law AI Skill real-world DEC-114 Plan A tone-setting (Figures 1-6 grayscale + unique blue focus = hierarchy benchmark, zero blue text).
• Relationship and label card syntax (v1.8.11, see references/style-guide.md §6): lines with flow/feedback/review/status meaning are not deleted due to simplification; the same fork's trunk and branches are continuous; adjacent-level arrows prioritize 16–32px visible line body, over 48px compress layout first. When dark label + light body is one card, the title bar only keeps the top rounded corners; step numbers occupy an independent upper band; the legend only explains relationships the reader needs to understand.
• Text: inherit the rendering environment's default sans-serif font (PingFang SC / Microsoft YaHei fall in the system layer), node labels start at 18px (physical 2.88mm = 8.2pt under 16-open 115mm full-width)
• Shape: rounded rectangle (rx="6"), concise arrows, minimum 24px spacing
• Shape containment: by default fix accidental overlap; only outer area shapes that truly carry child shapes declare data-overlap-role="container", and simultaneously write the single figure's unique native id, explicitly state the data-overlap-note carrying the relationship, and non-transparent hex/rgb/hsl fill. Static contracts only review declarations; actual geometry is audited by the writing-reviewer render gate
• Print: Distinguishable in black and white; color is not the only means of distinction (being distinguishable after black-and-white degradation is a hard constraint)

---

List of Figures

references/diagram-catalog.md Define the list-of-figures format and creation method.

---

PNG export

Publishers usually need a bitmap version.scripts/svg2png.js will read assets/render-fonts.css, converting SVG to high-resolution PNG:

# 单张转换（默认 600 DPI）
node scripts/svg2png.js input.svg

# 指定输出文件和 DPI
node scripts/svg2png.js input.svg output.png 300

# 批量转换目录下所有 SVG
find figures/ -name "*.svg" -exec node scripts/svg2png.js {} \;

Dependencies: The quick preview wrapper requires the system to already have rsvg-convert; high-DPI export requires Puppeteer and Chrome/Chromium. If missing, the script will clearly report an error and will not install automatically. Before using the high-DPI feature for the first time, the user runs it themselves:npm install puppeteer

Recommended print DPI：

• 300 DPI: Minimum print requirement
• 600 DPI: Recommended, clear and sharp
• 1200 DPI: Highest quality for line art

---

Finished-manuscript consistency scan (v1.9.0, for existing manuscripts)

Outside the generation workflow, run a rule inspection on all inline SVGs offinished manuscripts(report only, do not modify the manuscript; does not replace the geometry/visual audit of the writing-reviewer render gate):

python3 scripts/scan_consistency.py --book-root <书仓根目录> --report <报告输出.md>
# 阈值可调：--padding 40（安全边距 px）、--arrow-gap 8（箭头悬空 px）
# CI 门禁形态：--fail-on hard（存在 hard finding 时退出码 1）

Rule coverage (19 rules; each finding carries rule ID / file / SVG index / location / severity hard|soft):

• Whitespace: Content is less than the threshold from the canvas edge (default 40px, style-guide §1)
• Arrow endpoint: The tip penetrates the target box (penetrating boxes is prohibited), is more than the threshold from the nearest target box, and has no data-arrow-role="axis|annotation" + dangling arrow declared by a non-empty note (style-guide §5.5.3 / FIGURES-OUTLINE DEC-128)
• marker hard constraints: Non- arrow multiple markers / missing markerUnits="userSpaceOnUse"+orient="auto" / dangling url(#id) references (v1.6.0)
• Syntax：<style> block,style=、font-family, full-canvas background rectangle, width/height/viewBox contract (v1.8.9)
• Identity：data-figure-id missing (soft, historical no-backfill policy) / unsafe format / fig-template-* committed to manuscript / duplicate across figures
• sidecar sync: canonical inline SVG ↔ manuscript/**/*_images/<stem>-svg-N.svg derived cache contents are consistent (T261 policy)

Historical policy: For SYNTAX/IDENTITY findings in historical manuscripts before v1.8.9, only log them and do not require backfilling (consistent with this skill's existing policy of "do not backfill historical manuscripts"). v1.9.1 adds --exemptions <台账.json>: item-by-item exemption of already-adjudicated historical items (key=file/svg_index/rule_id); hits are not counted as findings, misses raise an alert to prevent ledger drift, and a bad ledger fails closed; whole-rule exemptions are intentionally excluded—violations in new figures are always reported. It does not intrude on BLOCKED Task-001 (producer conflict) / Task-002 (shape containment): this scan does not modify producers and does not perform containment geometry decisions.

---

Success criteria

• Each figure expresses only 1-2 core concepts
• Architecture diagrams have clear hierarchy, and flowcharts have coherent logic
• Style is concise and professional, with no decorative elements
• SVG renders correctly in Markdown preview (source contract: the opening tag is strictly viewBox="0 0 720 H", width="720", height="H", and has a project-unique safe data-figure-id; no embedded font-family, no <style>/style=, colors use only the fill/stroke attribute inline,no background rectangle, xmllint well-formed; controlled wrapper rendering without warnings)
• Caption format unified:Figure N-X: Title
• Figure density meets standard: figures/section ≥ 0.7, figures/10k words ≥ 0.8
• Figure-body consistency: nodes/hierarchy/direction/dimensions match the body argument, replacing mermaid/ASCII figures is information-lossless
• Visual inspection passed: after rendering, no overflow/unexpected overlap/misaligned arrows, font size readable, distinguishable in black and white, aesthetically pleasing; intentional shape inclusion only via auditable container narrow declaration and documented by writing-reviewer render gate
• Print-friendly: text ≥8pt clearly readable under 16-mo 115mm full-width layout, distinguishable in black-and-white printing, text contrast ≥4.5:1 (WCAG AA), CMYK conversion without color shift
• Color compliance (v1.5.0): newly generated figurestransparent background(no canvas background rectangle); choose 1 of 8 palette groups, module colors within the group used for soft multi-color differentiation of internal modules (4-6 colors per figure), adjacent modules in different colors; text color uniformly dark gray; colors only used in fill/stroke attribute inline; existing 34 white-background monochrome figures remain stable without retroactive changes
• Visual friendliness (v1.8.7): text within dark backgrounds (L* ≤ 50) modules uses light color #FFFFFF/#EDF2F7(dark background with dark text forbidden); text vs its module contrast ≥ 4.5:1; arrow endpoints x2 = 目标框边 − 4px, direction points to target; every node box with title semantics has a non-empty <text>, coordinates within the box, fill different color from module (see style-guide §5.5)
• Blue focus + two-tier text (v1.8.8): text color only #2D3436/#636E72(+ light text on dark background #FFFFFF/#EDF2F7), no longer using #1A202C/#4A5568; project canonical primary color only for focus node fill/stroke, forbidden as text fill; each structure/flowchart ≥1 focus node (see style-guide §5.0/§5.1)
• Relationships and label cards (v1.8.11): meaningful relationship lines fully preserved and not pressing on text; branching continuous, adjacent hierarchy connections compact; label cards rounded only on the title top, step numbers in an independent upper band, legend reader-oriented (see style-guide §六)

Source production contract and controlled rendering are onlynecessary but not sufficientconditions—they guarantee the SVG is parseable and the canvas and styles are controlled, but not that the figure is correct and aesthetically pleasing. The three reviews of density + consistency + visual inspection are the acceptance basis (references/review-checklist.md）。