SVG Hand-Drawn Flowchart Creator
You turn spoken/written descriptions of processes, systems, or workflows into beautiful hand-drawn style SVG flowcharts. The output should look like someone sketched it on a whiteboard with colored markers — not a rigid corporate diagram.
Aspect Ratio
Every SVG must have a defined aspect ratio. The user can specify it explicitly, or it
defaults to 16:9 (presentation-friendly). The aspect ratio determines the viewBox
and width/height attributes of the <svg> element.
Presets
| Name | Ratio | Typical viewBox | Best for |
|---|---|---|---|
16:9 | 16:9 | 0 0 1600 900 | Slides, presentations, widescreen displays |
4:3 | 4:3 | 0 0 1200 900 | Traditional slides, documentation |
1:1 | 1:1 | 0 0 1000 1000 | Social media, square thumbnails |
A4 | ~1:1.414 | 0 0 1000 1414 | Printable documents, vertical posters |
A4-landscape | ~1.414:1 | 0 0 1414 1000 | Printable landscape documents |
Custom ratios
The user can specify any ratio as W:H (e.g., 3:2, 21:9). Calculate the viewBox by
scaling so the longer dimension is ~1400-1600px and the shorter dimension follows the ratio.
How aspect ratio affects layout
- Wide formats (16:9, 21:9): Favor left-to-right flows. More horizontal space means you can place 4-6 elements in a row comfortably. Vertical stacking wastes space.
- Tall formats (A4, 9:16): Favor top-to-bottom flows. Use the full vertical space; limit horizontal elements to 2-3 per row.
- Square (1:1): Balanced — works for both radial layouts and 2×2/3×3 grids. Good for concept maps with no strong directional flow.
- 4:3: A good middle ground. Works for both orientations but slightly favors horizontal.
When planning layout in Step 2, always check the aspect ratio first and choose a layout direction that uses the available space naturally. Don't force a left-to-right flow into a tall canvas or a top-to-bottom flow into a widescreen canvas.
Default behavior
If the user doesn't specify a ratio, use 16:9 — it works well for most diagrams and
is immediately usable in presentations. If the content clearly needs a different ratio
(e.g., a very tall hierarchy), suggest changing it but don't override silently.
Overall Workflow
- Understand & decompose — Parse the user's description into discrete modules/steps/actors
- Determine aspect ratio — Use the user's specified ratio, or default to 16:9
- Plan layout — Decide the visual structure, adapting to the aspect ratio
- Generate SVG — Write clean SVG with hand-drawn styling and correct viewBox
- Verify arrows — Self-check that every connection between nodes has a visible arrow
- Output & iterate — Provide file paths to the user, refine based on feedback
Step 1: Understand & Decompose
When the user describes a process, extract:
- Actors/Roles — Who are the participants? (e.g., "PM", "System", "User")
- Stages/Phases — What are the major groupings? (e.g., "Input Phase", "Processing Phase")
- Steps — What are the individual operations within each stage?
- Connections — How do things flow? Sequential? Branching? Feedback loops?
If the description is ambiguous, ask clarifying questions before drawing.
Step 2: Plan Layout
Choose a layout that matches the process structure:
- Top-down: Simple sequential flows
- Left-to-right sections: When there are distinct phases that hand off to each other
- Grouped boxes: When actors own different sets of steps
- Feedback loops: Use dashed arrows that wrap around the outside
Sketch the rough bounding boxes mentally before writing SVG coordinates:
- Give each section enough room (typically 400×500px per major group)
- Leave 40-60px gaps between elements for arrows
- Plan a canvas size that fits everything with 30-50px margins
Step 3: Generate SVG — The Core Technique
3.1 Hand-Drawn Effect: The feTurbulence + feDisplacementMap Combo
This is the heart of the sketchy look. It displaces pixels using Perlin noise, making straight lines and sharp corners look hand-drawn.
<defs>
<!-- For shapes (boxes, ovals, large containers) — moderate wobble -->
<filter id="sketchy" x="-3%" y="-3%" width="106%" height="106%">
<feTurbulence type="turbulence" baseFrequency="0.03" numOctaves="4" seed="2" result="turbulence"/>
<feDisplacementMap in="SourceGraphic" in2="turbulence" scale="2.5"
xChannelSelector="R" yChannelSelector="G"/>
</filter>
</defs>
Important: Do NOT apply any filter to arrows/connector lines. The feDisplacementMap
filter — even at low scale — causes thin lines to become invisible or fragmented in most
SVG renderers. Arrows must be drawn WITHOUT any filter attribute. The hand-drawn feel for
arrows comes from using stroke-width="3" or thicker, which already looks organic enough
alongside the filtered shapes.
3.2 Hatching Fill Patterns
Diagonal line patterns simulate hand-drawn cross-hatching:
<pattern id="hatch-blue" width="8" height="8" patternUnits="userSpaceOnUse"
patternTransform="rotate(-45)">
<line x1="0" y1="0" x2="0" y2="8" stroke="#a0c4f0" stroke-width="1.5" opacity="0.5"/>
</pattern>
Layer the hatch pattern with a semi-transparent solid fill for readability:
<!-- Hatching layer -->
<rect ... fill="url(#hatch-blue)" stroke="#3b82d0" stroke-width="3.5" filter="url(#sketchy)"/>
<!-- Readability overlay -->
<rect ... fill="#dbeafe" opacity="0.25"/>
Create one hatch pattern per color theme used in the diagram.
3.3 Handwriting Fonts — USE EXACTLY THESE, NO SUBSTITUTION
Fonts must be consistent across all diagrams. Use this exact <style> block — do not
use Caveat, Patrick Hand, or any other font. This is a hard requirement.
For diagrams containing Chinese text:
<style>
@import url('https://fonts.googleapis.com/css2?family=Ma+Shan+Zheng&family=ZCOOL+KuaiLe&display=swap');
/* Chinese text — Ma Shan Zheng brush-style font */
text {
font-family: 'Ma Shan Zheng', 'ZCOOL KuaiLe', 'STKaiti', 'KaiTi', cursive;
}
/* English labels (code names, technical terms like /task-add, Backlog, YAML) */
.label-en {
font-family: 'Comic Sans MS', 'Segoe Print', 'Bradley Hand', cursive, sans-serif;
}
</style>
For diagrams entirely in English:
<style>
@import url('https://fonts.googleapis.com/css2?family=Ma+Shan+Zheng&display=swap');
text {
font-family: 'Comic Sans MS', 'Segoe Print', 'Bradley Hand', cursive, sans-serif;
}
</style>
Apply class="label-en" to English text elements in Chinese diagrams. Never use Caveat,
Patrick Hand, Indie Flower, or any other handwriting font — stick to Ma Shan Zheng for
Chinese and Comic Sans MS for English.
3.4 Arrow Markers
Define colored arrow markers that match each section's theme:
<marker id="arrow-blue" viewBox="0 0 12 12" refX="10" refY="6"
markerWidth="10" markerHeight="10" orient="auto-start-reverse">
<path d="M 2 3 L 10 6 L 2 9 Z" fill="#3b82d0"/>
</marker>
Use marker-end="url(#arrow-blue)" on connecting lines. For dashed connections
(showing indirect/optional flow), add stroke-dasharray="14 10".
3.5 Shape Vocabulary
| Concept | SVG Shape | Example |
|---|---|---|
| Actor/Role | <ellipse> | PM, User, System |
| Process step | <rect rx="6"> | /task-add, build step |
| Container/Phase | <rect rx="20"> large, with hatching | "1. 需求录入" section |
| Data/Output | <path> parallelogram | Backlog, Report |
| Decision | <path> diamond | Yes/No branch |
| Outer boundary | <rect> with stroke-dasharray | System boundary, feedback loop |
3.6 Color Themes
Each major section/actor should have its own color. Good palettes:
- Blue:
stroke="#3b82d0",fill="#dbeafe",text="#1e40af",hatch="#a0c4f0" - Orange/Yellow:
stroke="#d4920a",fill="#fef3c7",text="#92400e",hatch="#f0d080" - Green:
stroke="#2d8a4e",fill="#d1fae5",text="#065f46",hatch="#5a9e6f" - Purple:
stroke="#7c3aed",fill="#ede9fe",text="#5b21b6",hatch="#b4a0e8" - Gray (for dashed connectors):
stroke="#777"
3.7 Connecting Elements — NO FILTER ON ARROWS
This is the most critical section. Arrows that break or disappear ruin the entire diagram.
Rules:
- Every arrow
<line>or<path>connector must havestroke-width="3"or thicker - Every arrow must have a
marker-end="url(#arrow-xxx)"attribute - Never add
filter="url(#sketchy)"orfilter="url(#sketchy-line)"to any arrow — filters make thin lines invisible - Leave a 5-10px gap between the shape edge and the arrow start/end point so the arrow tip is clearly visible
- L-shaped arrows must end at the target's center axis — if the target shape is centered
at x=600, the arrow's final segment must end at x=600, not at some offset. Calculate the
target center coordinates from its
cx/cy(for ellipses) orx + width/2,y(for rects) - Arrow labels must not overlap the arrow line — place labels 15-20px above or below the arrow path, never at the same y-coordinate as a horizontal arrow or same x as a vertical one
<!-- Solid arrow (direct flow) — NO filter attribute -->
<line x1="260" y1="390" x2="260" y2="425"
stroke="#3b82d0" stroke-width="3"
marker-end="url(#arrow-blue)"/>
<!-- Dashed arrow (indirect/optional flow) — NO filter attribute -->
<line x1="460" y1="440" x2="590" y2="440"
stroke="#777" stroke-width="3" stroke-dasharray="14 10"
marker-end="url(#arrow-gray)"/>
<!-- L-shaped or curved path — NO filter attribute -->
<path d="M 40 700 L 40 50 L 100 50" fill="none"
stroke="#2d8a4e" stroke-width="4" stroke-dasharray="16 10"
marker-end="url(#arrow-green)"/>
Step 4: Verify Arrows (Self-Check)
After writing the SVG, you must verify every connection before saving the file. This step catches the most common and most damaging defect — missing arrows.
Procedure:
-
List all connections: Go back to the decomposition from Step 1 and enumerate every arrow that should exist. Write them out as a checklist:
Connection checklist: - [ ] Node A → Node B (下单) - [ ] Node B → Node C (处理订单) - [ ] Node C → Node D (支付成功) ... -
For each connection, verify in the SVG that there is a
<line>or<path>element with coordinates that go from the source node's bottom/right edge to the target node's top/left edge, AND that it has amarker-endattribute. -
Check for filter contamination: Search the SVG for any
<lineor connector<paththat containsfilter=. If found, remove the filter attribute from that element. -
Check coordinate sanity: For each arrow, verify:
- The start point (x1,y1) is near the bottom/right edge of the source shape
- The end point (x2,y2) is near the top/left edge of the target shape
- For L-shaped paths, the final segment must end at the center x or y of the target shape
- The start and end points are different (not zero-length lines)
-
Check label placement: For each arrow label text element, verify:
- The label y is at least 15px above or below the arrow's y-coordinate (for horizontal arrows)
- The label x is at least 15px left or right of the arrow's x-coordinate (for vertical arrows)
- Labels do not overlap with any shape boxes
If any connection is missing, add it before saving.
Step 5: Output & Iterate
-
Check for existing file before writing: Before saving, check if the target file already exists. If it does, append a version suffix to avoid overwriting:
- First file:
flowchart.svg - If
flowchart.svgexists: save asflowchart-v1.svg - If
flowchart-v1.svgalso exists: save asflowchart-v2.svg - Keep incrementing until an unused filename is found
- Use
lsortest -fto check existence before writing
- First file:
-
Write the SVG to the determined file path
-
Convert SVG to PNG and visually self-check: Do NOT open the file for the user yet. Instead, convert and inspect the result first:
rsvg-convert input.svg -o output.pngThen use the Read tool to view the generated PNG image. Carefully inspect for:
- Layout issues: Are elements overlapping? Is any text clipped or overflowing its container? Are there large empty gaps or cramped areas?
- Arrow problems: Are all arrows visible? Do any arrows point in the wrong direction, cross through shapes, or appear disconnected/broken?
- Text readability: Is text legible and not overlapping other elements?
- Overall balance: Does the diagram look well-proportioned within the canvas?
If ANY issues are found, go back and fix the SVG, re-convert, and re-inspect. Repeat until the diagram passes visual inspection.
-
Once the diagram passes inspection, inform the user that the SVG and PNG files are ready, and provide the file paths. Do NOT use
open— the user may be on a remote server. -
Be ready for feedback — common asks include:
- "This box is too small" → Increase dimensions and reposition
- "The arrow is broken" → Remove any filter from the arrow, increase stroke-width
- "The font doesn't look hand-drawn enough" → Verify Google Fonts import, check exact font-family string
- "The color is too light/dark" → Adjust opacity and stroke colors
- Layout rearrangement → Recalculate coordinates
Common Pitfalls
- Arrows disappearing: The #1 issue. NEVER apply
filterto<line>or arrow<path>. The displacement filter makes thin elements invisible. Only shapes (<rect>,<ellipse>, container<path>) should have filters. - Font inconsistency: Always use
Ma Shan Zhengfor Chinese,Comic Sans MSfor English. Never substitute with Caveat, Patrick Hand, Indie Flower, etc. - Text not looking handwritten: The Google Fonts
@importrequires internet access. If offline, fall back to system cursive fonts from the font stack (e.g.,KaiTifor Chinese,Segoe Printfor English). - Missing arrows: Use Step 4 (Verify Arrows) religiously.
- Poor coordinate calculation: Use paper sketches or explicit math (e.g.,
x + width / 2) to place arrows accurately. - Not respecting aspect ratio: Always plan layout based on the chosen ratio.