Fireworks Tech Graph
Generate production-quality SVG technical diagrams exported as PNG via cairosvg (recommended), rsvg-convert, or puppeteer.
Install Source
Install this skill from GitHub:
npx skills add yizhiyanhua-ai/fireworks-tech-graph
Public package page:
https://www.npmjs.com/package/@yizhiyanhua-ai/fireworks-tech-graph
Do not pass @yizhiyanhua-ai/fireworks-tech-graph directly to skills add, because the CLI expects a GitHub or local repository source.
Update command:
npx skills add yizhiyanhua-ai/fireworks-tech-graph --force -g -y
Helper Scripts (Recommended)
Four helper scripts in scripts/ directory provide stable SVG generation and validation:
1. generate-diagram.sh - Validate SVG + export PNG
./scripts/generate-diagram.sh -t architecture -s 1 -o ./output/arch.svg
- Validates an existing SVG file
- Exports PNG after validation
- Example:
./scripts/generate-diagram.sh -t architecture -s 1 -o ./output/arch.svg
2. generate-from-template.py - Create starter SVG from template
python3 ./scripts/generate-from-template.py architecture ./output/arch.svg '{"title":"My Diagram","nodes":[],"arrows":[]}'
- Loads a built-in SVG template
- Renders nodes, arrows, and legend entries from JSON input
- Escapes text content to keep output XML-valid
3. validate-svg.sh - Validate SVG syntax
./scripts/validate-svg.sh <svg-file>
- Checks XML syntax
- Verifies tag balance
- Validates marker references
- Checks attribute completeness
- Validates path data
4. test-all-styles.sh - Batch test all styles
./scripts/test-all-styles.sh
- Tests multiple diagram sizes
- Validates all generated SVGs
- Generates test report
When to use scripts:
- Use scripts when generating complex SVGs to avoid syntax errors
- Scripts provide automatic validation and error reporting
- Recommended for production diagrams
When to generate SVG directly:
- Simple diagrams with few elements
- Quick prototypes
- When you need full control over SVG structure
Workflow (Always Follow This Order)
- Classify the diagram type (see Diagram Types below)
- Extract structure — identify layers, nodes, edges, flows, and semantic groups from user description
- Plan layout — apply the layout rules for the diagram type
- Load style reference — always load
references/style-1-flat-icon.md unless user specifies another; load the matching references/style-N.md for exact color tokens and SVG patterns
- Map nodes to shapes — use Shape Vocabulary below
- Check icon needs — load
references/icons.md for known products
- Write SVG with adaptive strategy (see SVG Generation Strategy below)
- Validate: Run
python3 -c "import xml.etree.ElementTree as ET; ET.parse('file.svg')" to check XML syntax
- Export PNG: Use
cairosvg (recommended). See SVG → PNG Conversion section below for full method comparison
- Report the generated file paths
- (Optional) Visual self-review — if your runtime can read images, load the exported PNG back and inspect it. Syntactic validity does not guarantee visual correctness: arrows may cross through component interiors, labels may collide with lifelines or other labels, boxes may overlap, alt-frame text may sit on top of a message, or a legend may cover content. If you see any of these, revise the SVG and re-export; repeat until the rendered image is clean. Common fixes:
- Route arrows through gaps between boxes, not through box interiors
- Move arrow labels 6-8px away from the arrow line (offset-first); add background rects only when offset is insufficient
- Widen inter-row/inter-column gutters so same-layer arrows have clear corridors
- Collapse repeated cross-layer arrows into a single "delegates down" rail outside the content area
- Move legend/notes out of any region where arrows or labels land
- Increase viewBox height/width rather than packing elements tighter
- If a filtered element (drop-shadow, blur) is missing one side of its border, move it ≥30px away from that viewBox edge, or remove the filter and rely on color/contrast for visual separation
Skip this step silently if image reading is unavailable — do not guess.
Diagram Types & Layout Rules
Architecture Diagram
Nodes = services/components. Group into horizontal layers (top→bottom or left→right).
- Typical layers: Client → Gateway/LB → Services → Data/Storage
- Use
<rect> dashed containers to group related services in the same layer
- Arrow direction follows data/request flow
- ViewBox:
0 0 960 600 standard, 0 0 960 800 for tall stacks
Data Flow Diagram
Emphasizes what data moves where. Focus on data transformation.
- Label every arrow with the data type (e.g., "embeddings", "query", "context")
- Use wider arrows (
stroke-width: 2.5) for primary data paths
- Dashed arrows for control/trigger flows
- Color arrows by data category (not just Agent/RAG — use semantics)
Flowchart / Process Flow
Sequential decision/process steps.
- Top-to-bottom preferred; left-to-right for wide flows
- Diamond shapes for decisions, rounded rects for processes, parallelograms for I/O
- Keep node labels short (≤3 words); put detail in sub-labels
- Align nodes on a grid: x positions snap to 120px intervals, y to 80px
Agent Architecture Diagram
Shows how an AI agent reasons, uses tools, and manages memory.
Key conceptual layers to always consider:
- Input layer: User, query, trigger
- Agent core: LLM, reasoning loop, planner
- Memory layer: Short-term (context window), Long-term (vector/graph DB), Episodic
- Tool layer: Tool calls, APIs, search, code execution
- Output layer: Response, action, side-effects
Use cyclic arrows (loop arcs) to show iterative reasoning. Separate memory types visually.
Memory Architecture Diagram (Mem0, MemGPT-style)
Specialized agent diagram focused on memory operations.
- Show memory write path and read path separately (different arrow colors)
- Memory tiers: Working Memory → Short-term → Long-term → External Store
- Label memory operations:
store(), retrieve(), forget(), consolidate()
- Use stacked rects or layered cylinders for storage tiers
Sequence Diagram
Time-ordered message exchanges between participants.
- Participants as vertical lifelines (top labels + vertical dashed lines)
- Messages as horizontal arrows between lifelines, top-to-bottom time order
- Activation boxes (thin filled rects on lifeline) show active processing
- Group with
<rect> loop/alt frames with label in top-left corner
- ViewBox height = 80 + (num_messages × 50)
Comparison / Feature Matrix
Side-by-side comparison of approaches, systems, or components.
- Column headers = systems, row headers = attributes
- Row height: 40px; column width: min 120px; header row height: 50px
- Checked cell: tinted background (e.g.
#dcfce7) + ✓ checkmark; unsupported: #f9fafb fill
- Alternating row fills (
#f9fafb / #ffffff) for readability
- Max readable columns: 5; beyond that, split into two diagrams
Timeline / Gantt
Horizontal time axis showing durations, phases, and milestones.
- X-axis = time (weeks/months/quarters); Y-axis = items/tasks/phases
- Bars: rounded rects, colored by category, labeled inside or beside
- Milestone markers: diamond or filled circle at specific x position with label above
- ViewBox:
0 0 960 400 typical; wider for many time periods: 0 0 1200 400
Mind Map / Concept Map
Radial layout from central concept.
- Central node at
cx=480, cy=280
- First-level branches: evenly distributed around center (360/N degrees)
- Second-level branches: branch off first-level at 30-45° offset
- Use curved
<path> with cubic bezier for branches, not straight lines
Class Diagram (UML)
Static structure showing classes, attributes, methods, and relationships.
- Class box: 3-compartment rect (name / attributes / methods), min width 160px
- Top compartment: class name, bold, centered (abstract = italic)
- Middle: attributes with visibility (
+ public, - private, # protected)
- Bottom: method signatures, same visibility notation
- Relationships:
- Inheritance (extends): solid line + hollow triangle arrowhead, child → parent
- Implementation (interface): dashed line + hollow triangle, class → interface
- Association: solid line + open arrowhead, label with multiplicity (1, 0.., 1..)
- Aggregation: solid line + hollow diamond on container side
- Composition: solid line + filled diamond on container side
- Dependency: dashed line + open arrowhead
- Interface:
<<interface>> stereotype above name, or circle/lollipop notation
- Enum: compartment rect with
<<enumeration>> stereotype, values in bottom
- Layout: parent classes top, children below; interfaces to the left/right of implementors
- ViewBox:
0 0 960 600 standard; 0 0 960 800 for deep hierarchies
Use Case Diagram (UML)
System functionality from user perspective.
- Actor: stick figure (circle head + body line) placed outside system boundary
- Label below figure, 13-14px
- Primary actors on left, secondary/supporting on right
- Use case: ellipse with label centered inside, min 140×60px
- Keep names verb phrases: "Create Order", "Process Payment"
- System boundary: large rect with dashed border + system name in top-left
- Relationships:
- Include: dashed arrow
<<include>> from base to included use case
- Extend: dashed arrow
<<extend>> from extension to base use case
- Generalization: solid line + hollow triangle (specialized → general)
- Layout: system boundary centered, actors outside, use cases inside
- ViewBox:
0 0 960 600 standard
State Machine Diagram (UML)
Lifecycle states and transitions of an entity.
- State: rounded rect with state name, min 120×50px
- Internal activities: small text
entry/ action, exit/ action, do/ activity
- Initial state: filled black circle (r=8), one outgoing arrow
- Final state: filled circle (r=8) inside hollow circle (r=12)
- Choice: small hollow diamond, guard labels on outgoing arrows
[condition]
- Transition: arrow with optional label
event [guard] / action
- Guard conditions in square brackets
- Actions after
/
- Composite/nested state: larger rect containing sub-states, with name tab
- Fork/join: thick horizontal or vertical black bar (synchronization)
- Layout: initial state top-left, final state bottom-right, flow top-to-bottom
- ViewBox:
0 0 960 600 standard
ER Diagram (Entity-Relationship)
Database schema and data relationships.
- Entity: rect with entity name in header (bold), attributes below
- Primary key attribute: underlined
- Foreign key: italic or marked with (FK)
- Min width: 160px; attribute font-size: 12px
- Relationship: diamond shape on connecting line
- Label inside diamond: "has", "belongs to", "enrolls in"
- Cardinality labels near entity:
1, N, 0..1, 0..*, 1..*
- Weak entity: double-bordered rect with double diamond relationship
- Associative entity: diamond + rect hybrid (rect with diamond inside)
- Line style: solid for identifying relationships, dashed for non-identifying
- Layout: entities in 2-3 rows, relationships between related entities
- ViewBox:
0 0 960 600 standard; wider 0 0 1200 600 for many entities
Network Topology
Physical or logical network infrastructure.
- Devices: icon-like rects or rounded rects
- Router: circle with cross arrows
- Switch: rect with arrow grid
- Server: stacked rect (rack icon)
- Firewall: brick-pattern rect or shield shape
- Load Balancer: horizontal split rect with arrows
- Cloud: cloud path (overlapping arcs)
- Connections: lines between device centers
- Ethernet/wired: solid line, label bandwidth
- Wireless: dashed line with WiFi symbol
- VPN: dashed line with lock icon
- Subnets/Zones: dashed rect containers with zone label (DMZ, Internal, External)
- Labels: device hostname + IP below, 12-13px
- Layout: tiered top-to-bottom (Internet → Edge → Core → Access → Endpoints)
- ViewBox:
0 0 960 600 standard
UML Coverage Map
Full mapping of UML 14 diagram types to supported diagram types:
| UML Diagram |
Supported As |
Notes |
| Class |
Class Diagram |
Full UML notation |
| Component |
Architecture Diagram |
Use colored fills per component type |
| Deployment |
Architecture Diagram |
Add node/instance labels |
| Package |
Architecture Diagram |
Use dashed grouping containers |
| Composite Structure |
Architecture Diagram |
Nested rects within components |
| Object |
Class Diagram |
Instance boxes with underlined name |
| Use Case |
Use Case Diagram |
Full actor/ellipse/relationship |
| Activity |
Flowchart / Process Flow |
Add fork/join bars |
| State Machine |
State Machine Diagram |
Full UML notation |
| Sequence |
Sequence Diagram |
Add alt/opt/loop frames |
| Communication |
— |
Approximate with Sequence (swap axes) |
| Timing |
Timeline |
Adapt time axis |
| Interaction Overview |
Flowchart |
Combine activity + sequence fragments |
| ER Diagram |
ER Diagram |
Chen/Crow's foot notation |
Shape Vocabulary
Map semantic concepts to consistent shapes across all diagram types:
| Concept |
Shape |
Notes |
| User / Human |
Circle + body path |
Stick figure or avatar |
| LLM / Model |
Rounded rect with brain/spark icon or gradient fill |
Use accent color |
| Agent / Orchestrator |
Hexagon or rounded rect with double border |
Signals "active controller" |
| Memory (short-term) |
Rounded rect, dashed border |
Ephemeral = dashed |
| Memory (long-term) |
Cylinder (database shape) |
Persistent = solid cylinder |
| Vector Store |
Cylinder with grid lines inside |
Add 3 horizontal lines |
| Graph DB |
Circle cluster (3 overlapping circles) |
|
| Tool / Function |
Gear-like rect or rect with wrench icon |
|
| API / Gateway |
Hexagon (single border) |
|
| Queue / Stream |
Horizontal tube (pipe shape) |
|
| File / Document |
Folded-corner rect |
|
| Browser / UI |
Rect with 3-dot titlebar |
|
| Decision |
Diamond |
Flowcharts only |
| Process / Step |
Rounded rect |
Standard box |
| External Service |
Rect with cloud icon or dashed border |
|
| Data / Artifact |
Parallelogram |
I/O in flowcharts |
Arrow Semantics
Always assign arrow meaning, not just color:
| Flow Type |
Color |
Stroke |
Dash |
Meaning |
| Primary data flow |
blue #2563eb |
2px solid |
none |
Main request/response path |
| Control / trigger |
orange #ea580c |
1.5px solid |
none |
One system triggering another |
| Memory read |
green #059669 |
1.5px solid |
none |
Retrieval from store |
| Memory write |
green #059669 |
1.5px |
5,3 |
Write/store operation |
| Async / event |
gray #6b7280 |
1.5px |
4,2 |
Non-blocking, event-driven |
| Embedding / transform |
purple #7c3aed |
1px solid |
none |
Data transformation |
| Feedback / loop |
purple #7c3aed |
1.5px curved |
none |
Iterative reasoning loop |
Always include a legend when 2+ arrow types are used.
Layout Rules & Validation
Spacing:
- Same-layer nodes: 80px horizontal, 120px vertical between layers
- Canvas margins: 40px minimum, 60px between node edges
- Snap to 8px grid: horizontal 120px intervals, vertical 120px intervals
Arrow Labels (CRITICAL):
- Offset-first (default): place label 6-8px above horizontal arrows, or 8px left/right of vertical arrows — do not overlap the arrow line
- Background fallback: add
<rect fill="canvas_bg" opacity="0.95"/> only when the offset label still crosses another visual element (another arrow, a node edge, etc.)
- Place mid-arrow, ≤3 words, stagger by 15-20px when multiple arrows converge
- Maintain 10px safety distance from nodes
Arrow Routing:
- Prefer orthogonal (L-shaped) paths to minimize crossings
- Anchor arrows on component edges, not geometric centers
- Route around dense node clusters, use different y-offsets for parallel arrows
- Jump-over arcs (5px radius) for unavoidable crossings
Post-Generation Arrow Optimization:
When a user asks to "优化箭头" / "fix arrow routing" / "optimize the diagram" on an already-generated diagram, preserve all nodes, containers, styles, and layout — only modify the arrows entries in the JSON data, then re-render with generate-from-template.py.
Available arrow override fields (in recommended order of use):
| Field |
Type |
When to Use |
source_port / target_port |
"left" / "right" / "top" / "bottom" |
Arrow exits/enters from the wrong edge |
corridor_x |
[x, ...] |
Hint vertical segments toward this x lane (soft preference) |
corridor_y |
[y, ...] |
Hint horizontal segments toward this y lane (soft preference) |
route_points |
[[x1,y1], [x2,y2], ...] |
Force exact waypoints (bypasses auto-routing); keep segments orthogonal |
routing_padding |
number (default: 24) |
(Advanced) Adjust obstacle clearance for this arrow |
port_clearance |
number |
(Advanced) Adjust first-segment offset from node edge |
label_style |
"badge" / "offset" |
Choose "offset" when badge backgrounds create visual clutter; keep "badge" (default) for legacy/high-contrast labels |
For JSON/template rendering, the default remains "badge" for backward compatibility. Set "label_style": "offset" on individual arrows when you want offset-first labels without background rects.
Optimization steps:
- Read the existing SVG — identify which arrows overlap, cross nodes, or look misaligned
- Find those arrows in the JSON data by
source / target pair
- Add
source_port / target_port if the exit/entry direction is wrong; add corridor_x / corridor_y to space parallel arrows apart; use route_points only when hints alone cannot resolve the path
- Re-run
generate-from-template.py with the updated JSON and validate with validate-svg.sh
Example — spacing two overlapping arrows into separate corridors:
{ "source": "nodeA", "target": "nodeB", "corridor_y": [280] }
{ "source": "nodeC", "target": "nodeD", "corridor_y": [320] }
Line Overlap Prevention (CRITICAL - most common bug on Codex):
When two arrows must cross each other, ALWAYS use jump-over arcs to prevent visual overlap:
- Crossing horizontal arrows: add a small semicircle arc (radius 5px, stroke same color as arrow, fill none) that "jumps over" the other line
- SVG pattern for jump-over: use a white/matching-background arc on the lower layer, then draw the upper arc on top
- Multiple crossings: stagger arc radii (5px, 7px, 9px) so arcs don't overlap each other
- Never let two arrows' straight-line segments cross without a jump-over arc
Validation Checklist (run before finalizing):
- Arrow-Component Collision: Arrows MUST NOT pass through component interiors (route around with orthogonal paths)
- Text Overflow: All text MUST fit with 8px padding (estimate:
text.length × 7px ≤ shape_width - 16px)
- Arrow-Text Alignment: Arrow endpoints MUST connect to shape edges (not floating); arrow labels should not overlap arrow lines (use offset positioning or background rects)
- Container Discipline: Prefer arrows entering and leaving section containers through open gaps between components, not through inner component bodies
- Filter Boundary Safety: For every element with
filter="url(...)", verify (element_x + element_width + filter_extension) ≤ viewBox_width AND element_x ≥ filter_extension. The default filter region extends 10-20% beyond bbox; staying near viewBox edges causes Chrome/cairosvg to clip the element's edge-side stroke (one side of the border vanishes while other sides render correctly)
- Arrow-Title Collision: Arrows MUST NOT cross through section/container title text or region labels (font-size ≥ 13px). For smaller annotations (< 13px), prefer routing around but tolerate if layout constraints require it. (Visual self-review check — not covered by
validate-svg.sh automated checks)
- Frame Label–Arrow Alignment (sequence diagrams): Section/frame label badges MUST be vertically centered with their first message arrow. Compute
badge_y = first_arrow_y - (badge_height / 2). When appending new sections to an existing diagram, verify alignment matches the existing sections — this is the most common regression when adding content incrementally. Use variables in Python list generation to enforce the constraint: sec_y = 840; badge_y = sec_y - 9 # for height=18 badge
SVG Technical Rules
- ViewBox:
0 0 960 600 default; 0 0 960 800 tall; 0 0 1200 600 wide
- Fonts: embed via
<style>font-family: ...</style> — no external @import (cairosvg / rsvg-convert cannot fetch external URLs)
<defs>: arrow markers, gradients, filters, clip paths
- Text: minimum 12px, prefer 13-14px labels, 11px sub-labels, 16-18px titles
- All arrows:
<marker> with markerEnd, sized markerWidth="10" markerHeight="7"
- Drop shadows:
<feDropShadow> in <filter>, apply sparingly (key nodes only)
- Curved paths: use
M x1,y1 C cx1,cy1 cx2,cy2 x2,y2 cubic bezier for loops/feedback arrows
- Clip content: use
<clipPath> if text might overflow a node box
- Z-order (drawing order): SVG uses painter's model — later elements cover earlier ones. Recommended layer order (bottom → top): ① canvas background ② dashed containers / region backgrounds ③ arrows and connection lines ④ node shapes (rects, circles) ⑤ text labels and annotations ⑥ legends and overlays. When arrows pass near text, draw arrows BEFORE text so text stays readable. Adjust per diagram needs — this is guidance, not rigid.
SVG Generation & Error Prevention
MANDATORY: Python List Method (ALWAYS use this):
python3 << 'EOF'
lines = []
lines.append('<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 960 700">')
lines.append(' <defs>')
# ... each line separately
lines.append('</svg>')
with open('/path/to/output.svg', 'w') as f:
f.write('\n'.join(lines))
print("SVG generated successfully")
EOF
Why mandatory: Prevents character truncation, typos, and syntax errors. Each line is independent and easy to verify.
Pre-Tool-Call Checklist (CRITICAL - use EVERY time):
- ✅ Can I write out the COMPLETE command/content right now?
- ✅ Do I have ALL required parameters ready?
- ✅ Have I checked for syntax errors in my prepared content?
If ANY answer is NO: STOP. Do NOT call the tool. Prepare the content first.
Error Recovery Protocol:
- First error: Analyze root cause, apply targeted fix
- Second error: Switch method entirely (Python list → chunked generation)
- Third error: STOP and report to user - do NOT loop endlessly
- Never: Retry the same failing command or call tools with empty parameters
Validation (run after generation):
python3 -c "import xml.etree.ElementTree as ET; ET.parse('file.svg')" && echo "✓ Valid XML"
# Or use cairosvg as a render-time check:
python3 -c "import cairosvg; cairosvg.svg2png(url='file.svg', write_to='/tmp/test.png')" && echo "✓ Renders" && rm /tmp/test.png
If using generate-from-template.py:
- Prefer
source / target node ids in arrow JSON so the generator can snap to node edges
- Keep
x1,y1,x2,y2 as hints or fallback coordinates, not the main routing primitive
- Let the generator choose orthogonal routes; avoid hardcoding center-to-center straight lines unless the path is guaranteed clear
Common Syntax Errors to Avoid:
- ❌
yt-anchor → ✅ y="60" text-anchor="middle"
- ❌
x="390 (missing y) → ✅ x="390" y="250"
- ❌
fill=#fff → ✅ fill="#ffffff"
- ❌
marker-end= → ✅ marker-end="url(#arrow)"
- ❌
L 29450 → ✅ L 290,220
- ❌ Missing
</svg> at end
- ❌ Element with
filter near viewBox edge — filter region extends 20% (default) or more beyond bbox; if that region exceeds viewBox, Chrome/cairosvg clip the filter rendering AND can drop the element's own stroke on that side. Keep filtered elements at least max(20% of element size, shadow blur radius × 3) away from viewBox edges, or omit the filter.
Output
- Default:
./[derived-name].svg and ./[derived-name].png in current directory
- Custom: user specifies path with
--output /path/ or 输出到 /path/
- PNG export: see SVG → PNG Conversion below
SVG → PNG Conversion
Method Comparison
| Tool |
Install |
Render Quality |
Notes |
rsvg-convert |
System (often preinstalled) |
⚠️ Fair |
Drops some CSS styles and <foreignObject> elements — missing borders/text on complex SVGs |
cairosvg (recommended) |
pip install cairosvg |
✅ Good |
Solid CSS support; clearly better than rsvg-convert |
puppeteer (headless Chrome) |
npm install puppeteer |
✅✅ Best |
Real browser engine; 100% fidelity but heavy (Node + Chromium) |
Recommended: cairosvg (Python one-liner)
# Single file (2x resolution for retina/docs)
python3 -c "import cairosvg; cairosvg.svg2png(url='input.svg', write_to='output.png', scale=2)"
# Batch convert all SVGs in a directory
python3 -c "
import cairosvg, os, glob
d = 'docs/00-core'
for svg in sorted(glob.glob(os.path.join(d, '*.svg'))):
png = svg.replace('.svg', '.png')
cairosvg.svg2png(url=svg, write_to=png, scale=2)
print(f'Done: {os.path.basename(svg)} -> {os.path.basename(png)}')
"
scale=2 produces 2x resolution PNG, ideal for high-DPI screens and embedded docs.
Fallback: rsvg-convert (simple but may drop styles)
# Single file
rsvg-convert -w 1920 file.svg -o file.png
# Batch (not recommended — complex SVGs may lose elements)
for f in docs/00-core/*.svg; do rsvg-convert -o "${f%.svg}.png" "$f"; done
# 2x resolution
for f in docs/00-core/*.svg; do rsvg-convert -z 2 -o "${f%.svg}.png" "$f"; done
Highest Fidelity: puppeteer (headless Chrome)
npm install puppeteer # auto-downloads Chromium
node svg2png.js [directory]
const puppeteer = require('puppeteer');
const fs = require('fs');
const path = require('path');
(async () => {
const dir = process.argv[2] || '.';
const svgFiles = fs.readdirSync(dir).filter(f => f.endsWith('.svg'));
const browser = await puppeteer.launch({
headless: 'new',
args: ['--no-sandbox', '--disable-setuid-sandbox']
});
for (const file of svgFiles) {
const svgPath = path.resolve(dir, file);
const pngPath = svgPath.replace(/\.svg$/, '.png');
const svgContent = fs.readFileSync(svgPath, 'utf-8');
const wMatch = svgContent.match(/width="(\d+)/);
const hMatch = svgContent.match(/height="(\d+)/);
const vbMatch = svgContent.match(/viewBox="[^"]*\s(\d+)\s(\d+)"/);
let width = wMatch ? parseInt(wMatch[1]) : (vbMatch ? parseInt(vbMatch[1]) : 1200);
let height = hMatch ? parseInt(hMatch[1]) : (vbMatch ? parseInt(vbMatch[2]) : 800);
const scale = 2;
const page = await browser.newPage();
await page.setViewport({ width, height, deviceScaleFactor: scale });
const html = `<!DOCTYPE html>
<html><head><style>
body { margin: 0; padding: 0; background: transparent; }
img { display: block; }
</style></head>
<body>
<img src="data:image/svg+xml;base64,${Buffer.from(svgContent).toString('base64')}" width="${width}" height="${height}" />
</body></html>`;
await page.setContent(html, { waitUntil: 'networkidle0' });
await page.screenshot({ path: pngPath, type: 'png', omitBackground: true });
await page.close();
console.log(`Done: ${file} -> ${path.basename(pngPath)} (${width}x${height} @${scale}x)`);
}
await browser.close();
})();
Gotchas (lessons learned)
rsvg-convert renders SVGs containing <foreignObject>, CSS filter, or complex <style> blocks incompletely — missing borders / missing text are the typical symptoms
cairosvg (built on Cairo) has much better CSS support than rsvg and is sufficient for most cases
cairosvg may fail to render CJK characters and emoji in <text> elements — Cairo's font API (cairo_select_font_face) does not reliably perform system fontconfig fallback, so glyphs not present in the matched font face render as □ (empty box). This commonly affects Chinese/Japanese/Korean text and emoji, depending on system font configuration. Workaround: use SVG as primary format for web/GitHub rendering (browsers handle CJK natively); reserve PNG export for Latin-only diagrams, or switch to the puppeteer path for full CJK+emoji fidelity
- If the SVG was generated by a browser (D3.js, Mermaid, etc.), only headless Chrome (puppeteer) renders it 100% faithfully
- Chrome headless CLI
--window-size=W,H is not the drawable area — even in --headless=new mode, browser chrome (scrollbars, internal UI surfaces) consumes ~15-20% of both width and height, so the actual SVG viewport is only ~0.84×W by ~0.84×H. Symptom: SVG content past x ≈ 0.84 × W or y ≈ 0.84 × H is cut off and renders as a solid white band, even though the SVG file itself is correct. Typical failure modes: a Legend in the top-right corner loses its right border; a bottom-row container loses its bottom dashed line. Fix: pass window dimensions ≥ SVG width × 1.2 AND SVG height × 1.2, then crop the raw screenshot back to (SVG_width × scale, SVG_height × scale) with PIL or ImageMagick. Example: for a 1280×580 SVG at 3× DPR, use --window-size=1600,800 then crop the output to 3840×1740. The Puppeteer / page.setViewport() path does NOT have this issue — it sets a precise viewport regardless of window UI.
Picking a Method
- Default →
cairosvg (pip install once, one-line conversion, good fidelity)
- No Python available →
rsvg-convert (acceptable for simple flat-color diagrams)
- Browser-generated SVG or pixel-perfect required →
puppeteer
Styles
| # |
Name |
Background |
Best For |
| 1 |
Flat Icon (default) |
White |
Blogs, docs, presentations |
| 2 |
Dark Terminal |
#0f0f1a |
GitHub, dev articles |
| 3 |
Blueprint |
#0a1628 |
Architecture docs |
| 4 |
Notion Clean |
White, minimal |
Notionnce |
| 5 |
Glassmorphism |
Dark gradient |
Product sites, keynotes |
| 6 |
Claude Official |
Warm cream #f8f6f3 |
Anthropic-style diagrams |
| 7 |
OpenAI Official |
Pure white #ffffff |
OpenAI-style diagrams |
| 8 |
Dark Luxury (AI-authored) |
#0a0a0a deep black |
Architecture docs, premium editorial — hand-craft SVG from references/style-8-dark-luxury.md |
Load references/style-N.md for exact color tokens and SVG patterns.
Style Selection
Default: Style 1 (Flat Icon) for most diagrams. Load references/style-diagram-matrix.md for detailed style-to-diagram-type recommendations.
These patterns appear frequently — internalize them:
RAG Pipeline: Query → Embed → VectorSearch → Retrieve → Augment → LLM → Response
Agentic RAG: adds Agent loop with Tool use between Query and LLM
Agentic Search: Query → Planner → [Search Tool / Calculator / Code] → Synthesizer → Response
Mem0 / Memory Layer: Input → Memory Manager → [Write: VectorDB + GraphDB] / [Read: Retrieve+Rank] → Context
Agent Memory Types: Sensory (raw input) → Working (context window) → Episodic (past interactions) → Semantic (facts) → Procedural (skills)
Multi-Agent: Orchestrator → [SubAgent A / SubAgent B / SubAgent C] → Aggregator → Output
Tool Call Flow: LLM → Tool Selector → Tool Execution → Result Parser → LLM (loop)
1---2name: fireworks-tech-graph3description: >-4 Use when the user wants to create any technical diagram - architecture, data5 flow, flowchart, sequence, agent/memory, or concept map - and export as6 SVG+PNG. Trigger on: "画图" "帮我画" "生成图" "做个图" "架构图" "流程图"7 "可视化一下" "出图" "generate diagram" "draw diagram" "visualize" or any8 system/flow description the user wants illustrated.9metadata:10 source: https://skillmd.com/skills/ninehills/fireworks-tech-graph11---1213# Fireworks Tech Graph1415Generate production-quality SVG technical diagrams exported as PNG via `cairosvg` (recommended), `rsvg-convert`, or `puppeteer`.1617## Install Source1819Install this skill from GitHub:2021```bash22npx skills add yizhiyanhua-ai/fireworks-tech-graph23```2425Public package page:2627```text28https://www.npmjs.com/package/@yizhiyanhua-ai/fireworks-tech-graph29```3031Do not pass `@yizhiyanhua-ai/fireworks-tech-graph` directly to `skills add`, because the CLI expects a GitHub or local repository source.3233Update command:3435```bash36npx skills add yizhiyanhua-ai/fireworks-tech-graph --force -g -y37```3839## Helper Scripts (Recommended)4041Four helper scripts in `scripts/` directory provide stable SVG generation and validation:4243### 1. `generate-diagram.sh` - Validate SVG + export PNG44```bash45./scripts/generate-diagram.sh -t architecture -s 1 -o ./output/arch.svg46```47- Validates an existing SVG file48- Exports PNG after validation49- Example: `./scripts/generate-diagram.sh -t architecture -s 1 -o ./output/arch.svg`5051### 2. `generate-from-template.py` - Create starter SVG from template52```bash53python3 ./scripts/generate-from-template.py architecture ./output/arch.svg '{"title":"My Diagram","nodes":[],"arrows":[]}'54```55- Loads a built-in SVG template56- Renders nodes, arrows, and legend entries from JSON input57- Escapes text content to keep output XML-valid5859### 3. `validate-svg.sh` - Validate SVG syntax60```bash61./scripts/validate-svg.sh <svg-file>62```63- Checks XML syntax64- Verifies tag balance65- Validates marker references66- Checks attribute completeness67- Validates path data6869### 4. `test-all-styles.sh` - Batch test all styles70```bash71./scripts/test-all-styles.sh72```73- Tests multiple diagram sizes74- Validates all generated SVGs75- Generates test report7677**When to use scripts:**78- Use scripts when generating complex SVGs to avoid syntax errors79- Scripts provide automatic validation and error reporting80- Recommended for production diagrams8182**When to generate SVG directly:**83- Simple diagrams with few elements84- Quick prototypes85- When you need full control over SVG structure8687## Workflow (Always Follow This Order)88891. **Classify** the diagram type (see Diagram Types below)902. **Extract structure** — identify layers, nodes, edges, flows, and semantic groups from user description913. **Plan layout** — apply the layout rules for the diagram type924. **Load style reference** — always load `references/style-1-flat-icon.md` unless user specifies another; load the matching `references/style-N.md` for exact color tokens and SVG patterns935. **Map nodes to shapes** — use Shape Vocabulary below946. **Check icon needs** — load `references/icons.md` for known products957. **Write SVG** with adaptive strategy (see SVG Generation Strategy below)968. **Validate**: Run `python3 -c "import xml.etree.ElementTree as ET; ET.parse('file.svg')"` to check XML syntax979. **Export PNG**: Use `cairosvg` (recommended). See **SVG → PNG Conversion** section below for full method comparison9810. **Report** the generated file paths9911. **(Optional) Visual self-review** — if your runtime can read images, load the exported PNG back and inspect it. Syntactic validity does not guarantee visual correctness: arrows may cross through component interiors, labels may collide with lifelines or other labels, boxes may overlap, alt-frame text may sit on top of a message, or a legend may cover content. If you see any of these, revise the SVG and re-export; repeat until the rendered image is clean. Common fixes:100 - Route arrows through gaps between boxes, not through box interiors101 - Move arrow labels 6-8px away from the arrow line (offset-first); add background rects only when offset is insufficient102 - Widen inter-row/inter-column gutters so same-layer arrows have clear corridors103 - Collapse repeated cross-layer arrows into a single "delegates down" rail outside the content area104 - Move legend/notes out of any region where arrows or labels land105 - Increase viewBox height/width rather than packing elements tighter106 - If a filtered element (drop-shadow, blur) is missing one side of its border, move it ≥30px away from that viewBox edge, or remove the filter and rely on color/contrast for visual separation107 Skip this step silently if image reading is unavailable — do not guess.108109## Diagram Types & Layout Rules110111### Architecture Diagram112Nodes = services/components. Group into **horizontal layers** (top→bottom or left→right).113- Typical layers: Client → Gateway/LB → Services → Data/Storage114- Use `<rect>` dashed containers to group related services in the same layer115- Arrow direction follows data/request flow116- ViewBox: `0 0 960 600` standard, `0 0 960 800` for tall stacks117118### Data Flow Diagram119Emphasizes **what data moves where**. Focus on data transformation.120- Label every arrow with the data type (e.g., "embeddings", "query", "context")121- Use wider arrows (`stroke-width: 2.5`) for primary data paths122- Dashed arrows for control/trigger flows123- Color arrows by data category (not just Agent/RAG — use semantics)124125### Flowchart / Process Flow126Sequential decision/process steps.127- Top-to-bottom preferred; left-to-right for wide flows128- Diamond shapes for decisions, rounded rects for processes, parallelograms for I/O129- Keep node labels short (≤3 words); put detail in sub-labels130- Align nodes on a grid: x positions snap to 120px intervals, y to 80px131132### Agent Architecture Diagram133Shows how an AI agent reasons, uses tools, and manages memory.134Key conceptual layers to always consider:135- **Input layer**: User, query, trigger136- **Agent core**: LLM, reasoning loop, planner137- **Memory layer**: Short-term (context window), Long-term (vector/graph DB), Episodic138- **Tool layer**: Tool calls, APIs, search, code execution139- **Output layer**: Response, action, side-effects140Use cyclic arrows (loop arcs) to show iterative reasoning. Separate memory types visually.141142### Memory Architecture Diagram (Mem0, MemGPT-style)143Specialized agent diagram focused on memory operations.144- Show memory **write path** and **read path** separately (different arrow colors)145- Memory tiers: Working Memory → Short-term → Long-term → External Store146- Label memory operations: `store()`, `retrieve()`, `forget()`, `consolidate()`147- Use stacked rects or layered cylinders for storage tiers148149### Sequence Diagram150Time-ordered message exchanges between participants.151- Participants as vertical **lifelines** (top labels + vertical dashed lines)152- Messages as horizontal arrows between lifelines, top-to-bottom time order153- Activation boxes (thin filled rects on lifeline) show active processing154- Group with `<rect>` loop/alt frames with label in top-left corner155- ViewBox height = 80 + (num_messages × 50)156157### Comparison / Feature Matrix158Side-by-side comparison of approaches, systems, or components.159- Column headers = systems, row headers = attributes160- Row height: 40px; column width: min 120px; header row height: 50px161- Checked cell: tinted background (e.g. `#dcfce7`) + `✓` checkmark; unsupported: `#f9fafb` fill162- Alternating row fills (`#f9fafb` / `#ffffff`) for readability163- Max readable columns: 5; beyond that, split into two diagrams164165### Timeline / Gantt166Horizontal time axis showing durations, phases, and milestones.167- X-axis = time (weeks/months/quarters); Y-axis = items/tasks/phases168- Bars: rounded rects, colored by category, labeled inside or beside169- Milestone markers: diamond or filled circle at specific x position with label above170- ViewBox: `0 0 960 400` typical; wider for many time periods: `0 0 1200 400`171172### Mind Map / Concept Map173Radial layout from central concept.174- Central node at `cx=480, cy=280`175- First-level branches: evenly distributed around center (360/N degrees)176- Second-level branches: branch off first-level at 30-45° offset177- Use curved `<path>` with cubic bezier for branches, not straight lines178179### Class Diagram (UML)180Static structure showing classes, attributes, methods, and relationships.181- **Class box**: 3-compartment rect (name / attributes / methods), min width 160px182 - Top compartment: class name, bold, centered (abstract = *italic*)183 - Middle: attributes with visibility (`+` public, `-` private, `#` protected)184 - Bottom: method signatures, same visibility notation185- **Relationships**:186 - Inheritance (extends): solid line + hollow triangle arrowhead, child → parent187 - Implementation (interface): dashed line + hollow triangle, class → interface188 - Association: solid line + open arrowhead, label with multiplicity (1, 0..*, 1..*)189 - Aggregation: solid line + hollow diamond on container side190 - Composition: solid line + filled diamond on container side191 - Dependency: dashed line + open arrowhead192- **Interface**: `<<interface>>` stereotype above name, or circle/lollipop notation193- **Enum**: compartment rect with `<<enumeration>>` stereotype, values in bottom194- Layout: parent classes top, children below; interfaces to the left/right of implementors195- ViewBox: `0 0 960 600` standard; `0 0 960 800` for deep hierarchies196197### Use Case Diagram (UML)198System functionality from user perspective.199- **Actor**: stick figure (circle head + body line) placed outside system boundary200 - Label below figure, 13-14px201 - Primary actors on left, secondary/supporting on right202- **Use case**: ellipse with label centered inside, min 140×60px203 - Keep names verb phrases: "Create Order", "Process Payment"204- **System boundary**: large rect with dashed border + system name in top-left205- **Relationships**:206 - Include: dashed arrow `<<include>>` from base to included use case207 - Extend: dashed arrow `<<extend>>` from extension to base use case208 - Generalization: solid line + hollow triangle (specialized → general)209- Layout: system boundary centered, actors outside, use cases inside210- ViewBox: `0 0 960 600` standard211212### State Machine Diagram (UML)213Lifecycle states and transitions of an entity.214- **State**: rounded rect with state name, min 120×50px215 - Internal activities: small text `entry/ action`, `exit/ action`, `do/ activity`216 - **Initial state**: filled black circle (r=8), one outgoing arrow217 - **Final state**: filled circle (r=8) inside hollow circle (r=12)218 - **Choice**: small hollow diamond, guard labels on outgoing arrows `[condition]`219- **Transition**: arrow with optional label `event [guard] / action`220 - Guard conditions in square brackets221 - Actions after `/`222- **Composite/nested state**: larger rect containing sub-states, with name tab223- **Fork/join**: thick horizontal or vertical black bar (synchronization)224- Layout: initial state top-left, final state bottom-right, flow top-to-bottom225- ViewBox: `0 0 960 600` standard226227### ER Diagram (Entity-Relationship)228Database schema and data relationships.229- **Entity**: rect with entity name in header (bold), attributes below230 - Primary key attribute: underlined231 - Foreign key: italic or marked with (FK)232 - Min width: 160px; attribute font-size: 12px233- **Relationship**: diamond shape on connecting line234 - Label inside diamond: "has", "belongs to", "enrolls in"235 - Cardinality labels near entity: `1`, `N`, `0..1`, `0..*`, `1..*`236- **Weak entity**: double-bordered rect with double diamond relationship237- **Associative entity**: diamond + rect hybrid (rect with diamond inside)238- Line style: solid for identifying relationships, dashed for non-identifying239- Layout: entities in 2-3 rows, relationships between related entities240- ViewBox: `0 0 960 600` standard; wider `0 0 1200 600` for many entities241242### Network Topology243Physical or logical network infrastructure.244- **Devices**: icon-like rects or rounded rects245 - Router: circle with cross arrows246 - Switch: rect with arrow grid247 - Server: stacked rect (rack icon)248 - Firewall: brick-pattern rect or shield shape249 - Load Balancer: horizontal split rect with arrows250 - Cloud: cloud path (overlapping arcs)251- **Connections**: lines between device centers252 - Ethernet/wired: solid line, label bandwidth253 - Wireless: dashed line with WiFi symbol254 - VPN: dashed line with lock icon255- **Subnets/Zones**: dashed rect containers with zone label (DMZ, Internal, External)256- **Labels**: device hostname + IP below, 12-13px257- Layout: tiered top-to-bottom (Internet → Edge → Core → Access → Endpoints)258- ViewBox: `0 0 960 600` standard259260## UML Coverage Map261262Full mapping of UML 14 diagram types to supported diagram types:263264| UML Diagram | Supported As | Notes |265|-------------|-------------|-------|266| Class | Class Diagram | Full UML notation |267| Component | Architecture Diagram | Use colored fills per component type |268| Deployment | Architecture Diagram | Add node/instance labels |269| Package | Architecture Diagram | Use dashed grouping containers |270| Composite Structure | Architecture Diagram | Nested rects within components |271| Object | Class Diagram | Instance boxes with underlined name |272| Use Case | Use Case Diagram | Full actor/ellipse/relationship |273| Activity | Flowchart / Process Flow | Add fork/join bars |274| State Machine | State Machine Diagram | Full UML notation |275| Sequence | Sequence Diagram | Add alt/opt/loop frames |276| Communication | — | Approximate with Sequence (swap axes) |277| Timing | Timeline | Adapt time axis |278| Interaction Overview | Flowchart | Combine activity + sequence fragments |279| ER Diagram | ER Diagram | Chen/Crow's foot notation |280281## Shape Vocabulary282283Map semantic concepts to consistent shapes across all diagram types:284285| Concept | Shape | Notes |286|---------|-------|-------|287| User / Human | Circle + body path | Stick figure or avatar |288| LLM / Model | Rounded rect with brain/spark icon or gradient fill | Use accent color |289| Agent / Orchestrator | Hexagon or rounded rect with double border | Signals "active controller" |290| Memory (short-term) | Rounded rect, dashed border | Ephemeral = dashed |291| Memory (long-term) | Cylinder (database shape) | Persistent = solid cylinder |292| Vector Store | Cylinder with grid lines inside | Add 3 horizontal lines |293| Graph DB | Circle cluster (3 overlapping circles) | |294| Tool / Function | Gear-like rect or rect with wrench icon | |295| API / Gateway | Hexagon (single border) | |296| Queue / Stream | Horizontal tube (pipe shape) | |297| File / Document | Folded-corner rect | |298| Browser / UI | Rect with 3-dot titlebar | |299| Decision | Diamond | Flowcharts only |300| Process / Step | Rounded rect | Standard box |301| External Service | Rect with cloud icon or dashed border | |302| Data / Artifact | Parallelogram | I/O in flowcharts |303304## Arrow Semantics305306Always assign arrow meaning, not just color:307308| Flow Type | Color | Stroke | Dash | Meaning |309|-----------|-------|--------|------|---------|310| Primary data flow | blue `#2563eb` | 2px solid | none | Main request/response path |311| Control / trigger | orange `#ea580c` | 1.5px solid | none | One system triggering another |312| Memory read | green `#059669` | 1.5px solid | none | Retrieval from store |313| Memory write | green `#059669` | 1.5px | `5,3` | Write/store operation |314| Async / event | gray `#6b7280` | 1.5px | `4,2` | Non-blocking, event-driven |315| Embedding / transform | purple `#7c3aed` | 1px solid | none | Data transformation |316| Feedback / loop | purple `#7c3aed` | 1.5px curved | none | Iterative reasoning loop |317318Always include a **legend** when 2+ arrow types are used.319320## Layout Rules & Validation321322**Spacing**:323- Same-layer nodes: 80px horizontal, 120px vertical between layers324- Canvas margins: 40px minimum, 60px between node edges325- Snap to 8px grid: horizontal 120px intervals, vertical 120px intervals326327**Arrow Labels** (CRITICAL):328- **Offset-first** (default): place label 6-8px above horizontal arrows, or 8px left/right of vertical arrows — do not overlap the arrow line329- **Background fallback**: add `<rect fill="canvas_bg" opacity="0.95"/>` only when the offset label still crosses another visual element (another arrow, a node edge, etc.)330- Place mid-arrow, ≤3 words, stagger by 15-20px when multiple arrows converge331- Maintain 10px safety distance from nodes332333**Arrow Routing**:334- Prefer orthogonal (L-shaped) paths to minimize crossings335- Anchor arrows on component edges, not geometric centers336- Route around dense node clusters, use different y-offsets for parallel arrows337- Jump-over arcs (5px radius) for unavoidable crossings338339**Post-Generation Arrow Optimization**:340341When a user asks to "优化箭头" / "fix arrow routing" / "optimize the diagram" on an already-generated diagram, preserve all nodes, containers, styles, and layout — only modify the `arrows` entries in the JSON data, then re-render with `generate-from-template.py`.342343Available arrow override fields (in recommended order of use):344345| Field | Type | When to Use |346|-------|------|-------------|347| `source_port` / `target_port` | `"left"` / `"right"` / `"top"` / `"bottom"` | Arrow exits/enters from the wrong edge |348| `corridor_x` | `[x, ...]` | Hint vertical segments toward this x lane (soft preference) |349| `corridor_y` | `[y, ...]` | Hint horizontal segments toward this y lane (soft preference) |350| `route_points` | `[[x1,y1], [x2,y2], ...]` | Force exact waypoints (bypasses auto-routing); keep segments orthogonal |351| `routing_padding` | number (default: 24) | *(Advanced)* Adjust obstacle clearance for this arrow |352| `port_clearance` | number | *(Advanced)* Adjust first-segment offset from node edge |353| `label_style` | `"badge"` / `"offset"` | Choose `"offset"` when badge backgrounds create visual clutter; keep `"badge"` (default) for legacy/high-contrast labels |354355For JSON/template rendering, the default remains `"badge"` for backward compatibility. Set `"label_style": "offset"` on individual arrows when you want offset-first labels without background rects.356357Optimization steps:3581. Read the existing SVG — identify which arrows overlap, cross nodes, or look misaligned3592. Find those arrows in the JSON data by `source` / `target` pair3603. Add `source_port` / `target_port` if the exit/entry direction is wrong; add `corridor_x` / `corridor_y` to space parallel arrows apart; use `route_points` only when hints alone cannot resolve the path3614. Re-run `generate-from-template.py` with the updated JSON and validate with `validate-svg.sh`362363Example — spacing two overlapping arrows into separate corridors:364```json365{ "source": "nodeA", "target": "nodeB", "corridor_y": [280] }366{ "source": "nodeC", "target": "nodeD", "corridor_y": [320] }367```368369**Line Overlap Prevention** (CRITICAL - most common bug on Codex):370When two arrows must cross each other, ALWAYS use jump-over arcs to prevent visual overlap:371- Crossing horizontal arrows: add a small semicircle arc (radius 5px, stroke same color as arrow, fill none) that "jumps over" the other line372- SVG pattern for jump-over: use a white/matching-background arc on the lower layer, then draw the upper arc on top373- Multiple crossings: stagger arc radii (5px, 7px, 9px) so arcs don't overlap each other374- Never let two arrows' straight-line segments cross without a jump-over arc375376**Validation Checklist** (run before finalizing):3771. **Arrow-Component Collision**: Arrows MUST NOT pass through component interiors (route around with orthogonal paths)3782. **Text Overflow**: All text MUST fit with 8px padding (estimate: `text.length × 7px ≤ shape_width - 16px`)3793. **Arrow-Text Alignment**: Arrow endpoints MUST connect to shape edges (not floating); arrow labels should not overlap arrow lines (use offset positioning or background rects)3804. **Container Discipline**: Prefer arrows entering and leaving section containers through open gaps between components, not through inner component bodies3815. **Filter Boundary Safety**: For every element with `filter="url(...)"`, verify `(element_x + element_width + filter_extension) ≤ viewBox_width` AND `element_x ≥ filter_extension`. The default filter region extends 10-20% beyond bbox; staying near viewBox edges causes Chrome/cairosvg to clip the element's edge-side stroke (one side of the border vanishes while other sides render correctly)3826. **Arrow-Title Collision**: Arrows MUST NOT cross through section/container title text or region labels (font-size ≥ 13px). For smaller annotations (< 13px), prefer routing around but tolerate if layout constraints require it. *(Visual self-review check — not covered by `validate-svg.sh` automated checks)*3837. **Frame Label–Arrow Alignment** (sequence diagrams): Section/frame label badges MUST be vertically centered with their first message arrow. Compute `badge_y = first_arrow_y - (badge_height / 2)`. When appending new sections to an existing diagram, verify alignment matches the existing sections — this is the most common regression when adding content incrementally. Use variables in Python list generation to enforce the constraint: `sec_y = 840; badge_y = sec_y - 9 # for height=18 badge`384385## SVG Technical Rules386387- ViewBox: `0 0 960 600` default; `0 0 960 800` tall; `0 0 1200 600` wide388- Fonts: embed via `<style>font-family: ...</style>` — no external `@import` (cairosvg / rsvg-convert cannot fetch external URLs)389- `<defs>`: arrow markers, gradients, filters, clip paths390- Text: minimum 12px, prefer 13-14px labels, 11px sub-labels, 16-18px titles391- All arrows: `<marker>` with `markerEnd`, sized `markerWidth="10" markerHeight="7"`392- Drop shadows: `<feDropShadow>` in `<filter>`, apply sparingly (key nodes only)393- Curved paths: use `M x1,y1 C cx1,cy1 cx2,cy2 x2,y2` cubic bezier for loops/feedback arrows394- Clip content: use `<clipPath>` if text might overflow a node box395- Z-order (drawing order): SVG uses painter's model — later elements cover earlier ones. Recommended layer order (bottom → top): ① canvas background ② dashed containers / region backgrounds ③ arrows and connection lines ④ node shapes (rects, circles) ⑤ text labels and annotations ⑥ legends and overlays. When arrows pass near text, draw arrows BEFORE text so text stays readable. Adjust per diagram needs — this is guidance, not rigid.396397## SVG Generation & Error Prevention398399**MANDATORY: Python List Method** (ALWAYS use this):400```python401python3 << 'EOF'402lines = []403lines.append('<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 960 700">')404lines.append(' <defs>')405# ... each line separately406lines.append('</svg>')407408with open('/path/to/output.svg', 'w') as f:409 f.write('\n'.join(lines))410print("SVG generated successfully")411EOF412```413414**Why mandatory**: Prevents character truncation, typos, and syntax errors. Each line is independent and easy to verify.415416**Pre-Tool-Call Checklist** (CRITICAL - use EVERY time):4171. ✅ Can I write out the COMPLETE command/content right now?4182. ✅ Do I have ALL required parameters ready?4193. ✅ Have I checked for syntax errors in my prepared content?420421**If ANY answer is NO**: STOP. Do NOT call the tool. Prepare the content first.422423**Error Recovery Protocol**:424- **First error**: Analyze root cause, apply targeted fix425- **Second error**: Switch method entirely (Python list → chunked generation)426- **Third error**: STOP and report to user - do NOT loop endlessly427- **Never**: Retry the same failing command or call tools with empty parameters428429**Validation** (run after generation):430```bash431python3 -c "import xml.etree.ElementTree as ET; ET.parse('file.svg')" && echo "✓ Valid XML"432# Or use cairosvg as a render-time check:433python3 -c "import cairosvg; cairosvg.svg2png(url='file.svg', write_to='/tmp/test.png')" && echo "✓ Renders" && rm /tmp/test.png434```435436**If using `generate-from-template.py`**:437- Prefer `source` / `target` node ids in arrow JSON so the generator can snap to node edges438- Keep `x1,y1,x2,y2` as hints or fallback coordinates, not the main routing primitive439- Let the generator choose orthogonal routes; avoid hardcoding center-to-center straight lines unless the path is guaranteed clear440441**Common Syntax Errors to Avoid**:442- ❌ `yt-anchor` → ✅ `y="60" text-anchor="middle"`443- ❌ `x="390` (missing y) → ✅ `x="390" y="250"`444- ❌ `fill=#fff` → ✅ `fill="#ffffff"`445- ❌ `marker-end=` → ✅ `marker-end="url(#arrow)"`446- ❌ `L 29450` → ✅ `L 290,220`447- ❌ Missing `</svg>` at end448- ❌ Element with `filter` near viewBox edge — filter region extends 20% (default) or more beyond bbox; if that region exceeds viewBox, Chrome/cairosvg clip the filter rendering AND can drop the element's own stroke on that side. Keep filtered elements at least `max(20% of element size, shadow blur radius × 3)` away from viewBox edges, or omit the filter.449450## Output451452- **Default**: `./[derived-name].svg` and `./[derived-name].png` in current directory453- **Custom**: user specifies path with `--output /path/` or `输出到 /path/`454- **PNG export**: see **SVG → PNG Conversion** below455456## SVG → PNG Conversion457458### Method Comparison459460| Tool | Install | Render Quality | Notes |461|------|---------|----------------|-------|462| `rsvg-convert` | System (often preinstalled) | ⚠️ Fair | Drops some CSS styles and `<foreignObject>` elements — missing borders/text on complex SVGs |463| **`cairosvg` (recommended)** | `pip install cairosvg` | ✅ Good | Solid CSS support; clearly better than rsvg-convert |464| `puppeteer` (headless Chrome) | `npm install puppeteer` | ✅✅ Best | Real browser engine; 100% fidelity but heavy (Node + Chromium) |465466### Recommended: cairosvg (Python one-liner)467468```bash469# Single file (2x resolution for retina/docs)470python3 -c "import cairosvg; cairosvg.svg2png(url='input.svg', write_to='output.png', scale=2)"471472# Batch convert all SVGs in a directory473python3 -c "474import cairosvg, os, glob475d = 'docs/00-core'476for svg in sorted(glob.glob(os.path.join(d, '*.svg'))):477 png = svg.replace('.svg', '.png')478 cairosvg.svg2png(url=svg, write_to=png, scale=2)479 print(f'Done: {os.path.basename(svg)} -> {os.path.basename(png)}')480"481```482483> `scale=2` produces 2x resolution PNG, ideal for high-DPI screens and embedded docs.484485### Fallback: rsvg-convert (simple but may drop styles)486487```bash488# Single file489rsvg-convert -w 1920 file.svg -o file.png490491# Batch (not recommended — complex SVGs may lose elements)492for f in docs/00-core/*.svg; do rsvg-convert -o "${f%.svg}.png" "$f"; done493494# 2x resolution495for f in docs/00-core/*.svg; do rsvg-convert -z 2 -o "${f%.svg}.png" "$f"; done496```497498### Highest Fidelity: puppeteer (headless Chrome)499500```bash501npm install puppeteer # auto-downloads Chromium502node svg2png.js [directory]503```504505<details>506<summary>svg2png.js — full puppeteer script</summary>507508```javascript509const puppeteer = require('puppeteer');510const fs = require('fs');511const path = require('path');512513(async () => {514 const dir = process.argv[2] || '.';515 const svgFiles = fs.readdirSync(dir).filter(f => f.endsWith('.svg'));516517 const browser = await puppeteer.launch({518 headless: 'new',519 args: ['--no-sandbox', '--disable-setuid-sandbox']520 });521522 for (const file of svgFiles) {523 const svgPath = path.resolve(dir, file);524 const pngPath = svgPath.replace(/\.svg$/, '.png');525 const svgContent = fs.readFileSync(svgPath, 'utf-8');526527 const wMatch = svgContent.match(/width="(\d+)/);528 const hMatch = svgContent.match(/height="(\d+)/);529 const vbMatch = svgContent.match(/viewBox="[^"]*\s(\d+)\s(\d+)"/);530531 let width = wMatch ? parseInt(wMatch[1]) : (vbMatch ? parseInt(vbMatch[1]) : 1200);532 let height = hMatch ? parseInt(hMatch[1]) : (vbMatch ? parseInt(vbMatch[2]) : 800);533534 const scale = 2;535 const page = await browser.newPage();536 await page.setViewport({ width, height, deviceScaleFactor: scale });537538 const html = `<!DOCTYPE html>539<html><head><style>540 body { margin: 0; padding: 0; background: transparent; }541 img { display: block; }542</style></head>543<body>544 <img src="data:image/svg+xml;base64,${Buffer.from(svgContent).toString('base64')}" width="${width}" height="${height}" />545</body></html>`;546547 await page.setContent(html, { waitUntil: 'networkidle0' });548 await page.screenshot({ path: pngPath, type: 'png', omitBackground: true });549 await page.close();550551 console.log(`Done: ${file} -> ${path.basename(pngPath)} (${width}x${height} @${scale}x)`);552 }553554 await browser.close();555})();556```557558</details>559560### Gotchas (lessons learned)561562- `rsvg-convert` renders SVGs containing `<foreignObject>`, CSS `filter`, or complex `<style>` blocks **incompletely** — missing borders / missing text are the typical symptoms563- `cairosvg` (built on Cairo) has much better CSS support than rsvg and is sufficient for most cases564- `cairosvg` **may fail to render CJK characters and emoji** in `<text>` elements — Cairo's font API (`cairo_select_font_face`) does not reliably perform system fontconfig fallback, so glyphs not present in the matched font face render as □ (empty box). This commonly affects Chinese/Japanese/Korean text and emoji, depending on system font configuration. **Workaround**: use SVG as primary format for web/GitHub rendering (browsers handle CJK natively); reserve PNG export for Latin-only diagrams, or switch to the puppeteer path for full CJK+emoji fidelity565- If the SVG was generated by a browser (D3.js, Mermaid, etc.), only headless Chrome (puppeteer) renders it 100% faithfully566- **Chrome headless CLI `--window-size=W,H` is not the drawable area** — even in `--headless=new` mode, browser chrome (scrollbars, internal UI surfaces) consumes ~15-20% of both width and height, so the actual SVG viewport is only ~0.84×W by ~0.84×H. Symptom: SVG content past `x ≈ 0.84 × W` or `y ≈ 0.84 × H` is cut off and renders as a solid white band, even though the SVG file itself is correct. Typical failure modes: a Legend in the top-right corner loses its right border; a bottom-row container loses its bottom dashed line. Fix: pass window dimensions **≥ SVG width × 1.2 AND SVG height × 1.2**, then crop the raw screenshot back to `(SVG_width × scale, SVG_height × scale)` with PIL or ImageMagick. Example: for a 1280×580 SVG at 3× DPR, use `--window-size=1600,800` then crop the output to 3840×1740. The Puppeteer / `page.setViewport()` path does NOT have this issue — it sets a precise viewport regardless of window UI.567568### Picking a Method5695701. **Default** → `cairosvg` (pip install once, one-line conversion, good fidelity)5712. **No Python available** → `rsvg-convert` (acceptable for simple flat-color diagrams)5723. **Browser-generated SVG or pixel-perfect required** → `puppeteer`573574## Styles575576| # | Name | Background | Best For |577|---|------|-----------|----------|578| 1 | **Flat Icon** (default) | White | Blogs, docs, presentations |579| 2 | **Dark Terminal** | `#0f0f1a` | GitHub, dev articles |580| 3 | **Blueprint** | `#0a1628` | Architecture docs |581| 4 | **Notion Clean** | White, minimal | Notionnce |582| 5 | **Glassmorphism** | Dark gradient | Product sites, keynotes |583| 6 | **Claude Official** | Warm cream `#f8f6f3` | Anthropic-style diagrams |584| 7 | **OpenAI Official** | Pure white `#ffffff` | OpenAI-style diagrams |585| 8 | **Dark Luxury** *(AI-authored)* | `#0a0a0a` deep black | Architecture docs, premium editorial — hand-craft SVG from `references/style-8-dark-luxury.md` |586587Load `references/style-N.md` for exact color tokens and SVG patterns.588589## Style Selection590591**Default**: Style 1 (Flat Icon) for most diagrams. Load `references/style-diagram-matrix.md` for detailed style-to-diagram-type recommendations.592593These patterns appear frequently — internalize them:594595**RAG Pipeline**: Query → Embed → VectorSearch → Retrieve → Augment → LLM → Response596**Agentic RAG**: adds Agent loop with Tool use between Query and LLM597**Agentic Search**: Query → Planner → [Search Tool / Calculator / Code] → Synthesizer → Response598**Mem0 / Memory Layer**: Input → Memory Manager → [Write: VectorDB + GraphDB] / [Read: Retrieve+Rank] → Context599**Agent Memory Types**: Sensory (raw input) → Working (context window) → Episodic (past interactions) → Semantic (facts) → Procedural (skills)600**Multi-Agent**: Orchestrator → [SubAgent A / SubAgent B / SubAgent C] → Aggregator → Output601**Tool Call Flow**: LLM → Tool Selector → Tool Execution → Result Parser → LLM (loop)