Load only the relevant diagram type or shape section. User and selected style preferences take precedence over examples.
Nodes = services/components. Group into horizontal layers (top→bottom or left→right).
<rect> dashed containers to group related services in the same layer0 0 960 600 standard, 0 0 960 800 for tall stacksEmphasizes what data moves where. Focus on data transformation.
stroke-width: 2.5) for primary data pathsSequential decision/process steps.
Shows how an AI agent reasons, uses tools, and manages memory. Key conceptual layers to always consider:
Specialized agent diagram focused on memory operations.
store(), retrieve(), forget(), consolidate()Time-ordered message exchanges between participants.
<rect> loop/alt frames with label in top-left cornerSide-by-side comparison of approaches, systems, or components.
#dcfce7) + ✓ checkmark; unsupported: #f9fafb fill#f9fafb / #ffffff) for readabilityHorizontal time axis showing durations, phases, and milestones.
0 0 960 400 typical; wider for many time periods: 0 0 1200 400Radial layout from central concept.
cx=480, cy=280<path> with cubic bezier for branches, not straight linesStatic structure showing classes, attributes, methods, and relationships.
+ public, - private, # protected)<<interface>> stereotype above name, or circle/lollipop notation<<enumeration>> stereotype, values in bottom0 0 960 600 standard; 0 0 960 800 for deep hierarchiesSystem functionality from user perspective.
<<include>> from base to included use case<<extend>> from extension to base use case0 0 960 600 standardLifecycle states and transitions of an entity.
entry/ action, exit/ action, do/ activity[condition]event [guard] / action
/0 0 960 600 standardDatabase schema and data relationships.
1, N, 0..1, 0..*, 1..*0 0 960 600 standard; wider 0 0 1200 600 for many entitiesPhysical or logical network infrastructure.
0 0 960 600 standardFull 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 |
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 |
Always assign arrow meaning, not just color. The values below are defaults; the selected style reference overrides colors and stroke weights while preserving flow semantics:
| 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.
Spacing:
Arrow Labels (CRITICAL):
<rect fill="canvas_bg" opacity="0.95"/> only when the offset label still crosses another visual element (another arrow, a node edge, etc.)Arrow Routing:
marker-start + marker-end, or two visibly offset paths in that corridorPost-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], ...] |
Exact ordered waypoints; each leg is routed orthogonally and unsafe points are rejected |
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:
source / target pairsource_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 pathgenerate-from-template.py with the updated JSON and validate with validate-svg.shExample — 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 - common in AI-generated diagrams): When two arrows must cross each other, ALWAYS use jump-over arcs to prevent visual overlap:
Validation Checklist (run before finalizing):
text.length × 7px ≤ shape_width - 16px)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)validate-svg.sh automated checks)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 badgemarker-start, marker-mid, and marker-end URL MUST resolve to a <marker id="..."> definition0 0 960 600 default; 0 0 960 800 tall; 0 0 1200 600 wide<style>font-family: ...</style> — no external @import (cairosvg / rsvg-convert cannot fetch external URLs)<defs>: arrow markers, gradients, filters, clip paths<marker> with markerEnd, sized markerWidth="10" markerHeight="7"<feDropShadow> in <filter>, apply sparingly (key nodes only)M x1,y1 C cx1,cy1 cx2,cy2 x2,y2 cubic bezier for loops/feedback arrows<clipPath> if text might overflow a node boxExample: Python List Method. Use a maintainable SVG/XML generator that passes the same geometry, text and export checks:
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):
If ANY answer is NO: STOP. Do NOT call the tool. Prepare the content first.
Error Recovery Protocol:
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:
source / target node ids in arrow JSON so the generator can snap to node edgesx1,y1,x2,y2 as hints or fallback coordinates, not the main routing primitiveCommon 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</svg> at endfilter 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../[derived-name].svg and ./[derived-name].png in current directory--output /path/ or 输出到 /path/$SKILL_ROOT/references/motion-effects.mdUse $SKILL_ROOT/scripts/generate-diagram.sh by default. Load $SKILL_ROOT/references/png-export.md only when selecting a renderer manually, handling CJK/emoji fallback, converting browser-generated SVG, or using the bundled Puppeteer converter.
| # | 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 | Notion, Confluence, wikis |
| 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 $SKILL_ROOT/references/style-8-dark-luxury.md |
| 9 | C4 Review Canvas | Warm paper #f7f2e8 |
C4 reviews and ADRs; enforces one abstraction level |
| 10 | Cloud Fabric | Cloud blue #edf5fb |
Region/network/workload deployment ownership |
| 11 | Event Transit | Transit paper #fbf7ee |
Topics, processors, consumer groups, DLQ, state |
| 12 | Ops Pulse | Ops navy #07111f |
Golden signals, critical paths, correlated traces |
Load the matching $SKILL_ROOT/references/style-N-*.md for exact color tokens and SVG patterns.
Default: Style 1 (Flat Icon) for most diagrams. Load $SKILL_ROOT/references/style-diagram-matrix.md for detailed style-to-diagram-type recommendations.
Prompt fingerprints: C4评审画布/C4 review board → 9; 多区域云部署/deployment topology → 10; 事件地铁图/event metro map → 11; 可靠性脉冲/golden signals trace → 12; 让这张图动起来/生成 GIF/制作 GIF/animate this diagram/Generate a GIF → auto motion.
Auto-select these only with matching domain evidence; otherwise use Styles 1–7 or semantic_profile: "generic", and split mixed C4/deployment/event/ops views.
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)