CommunityImagegithub.com

SVG Flowchart Creator

Creates hand-drawn style SVG flowcharts and diagrams from user descriptions. Supports aspect ratio specification (16:9, 4:3, 1:1, A4, or custom W:H ratios).

What is SVG Flowchart Creator?

This skill, designed for AI agent tools like Claude Code, Cursor, or Codex, transforms verbal or written descriptions of processes, systems, or workflows into hand-drawn style SVG flowcharts. It produces diagrams with a distinctive whiteboard aesthetic—featuring wobbly edges, hatching fills, and handwriting fonts—rather than sterile corporate visuals. The skill supports various aspect ratios (16:9, 4:3, 1:1, A4, and custom W:H) to fit different use cases like presentations, documentation, or social media. It follows a structured workflow: understand and decompose the description, determine aspect ratio, plan layout, generate SVG with `feTurbulence` + `feDisplacementMap` for the sketchy effect, verify all arrows are present and correctly placed (a critical self-check to prevent missing connectors), then output the file. It also converts SVG to PNG for visual inspection before presenting results to the user. The skill enforces strict font usage (Ma Shan Zheng for Chinese, Comic Sans MS for English) and a detailed shape vocabulary (ellipses for actors, rounded rectangles for process steps, etc.).

Works with~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/retrocognition023/my-agent-skills/tree/HEAD/skills/svg-creator

Installed? Explore more Image skills: steipete/songsee, affaan-m/frontend-design, mattpocock/improve-codebase-architecture · View all 6 →

Ask in your favorite AI

Open a new chat with this agent skill pre-loaded.

Documentation

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

NameRatioTypical viewBoxBest for
16:916:90 0 1600 900Slides, presentations, widescreen displays
4:34:30 0 1200 900Traditional slides, documentation
1:11:10 0 1000 1000Social media, square thumbnails
A4~1:1.4140 0 1000 1414Printable documents, vertical posters
A4-landscape~1.414:10 0 1414 1000Printable 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

  1. Understand & decompose — Parse the user's description into discrete modules/steps/actors
  2. Determine aspect ratio — Use the user's specified ratio, or default to 16:9
  3. Plan layout — Decide the visual structure, adapting to the aspect ratio
  4. Generate SVG — Write clean SVG with hand-drawn styling and correct viewBox
  5. Verify arrows — Self-check that every connection between nodes has a visible arrow
  6. 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&amp;family=ZCOOL+KuaiLe&amp;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&amp;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

ConceptSVG ShapeExample
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> parallelogramBacklog, Report
Decision<path> diamondYes/No branch
Outer boundary<rect> with stroke-dasharraySystem 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:

  1. Every arrow <line> or <path> connector must have stroke-width="3" or thicker
  2. Every arrow must have a marker-end="url(#arrow-xxx)" attribute
  3. Never add filter="url(#sketchy)" or filter="url(#sketchy-line)" to any arrow — filters make thin lines invisible
  4. Leave a 5-10px gap between the shape edge and the arrow start/end point so the arrow tip is clearly visible
  5. 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) or x + width/2, y (for rects)
  6. 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:

  1. 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 (支付成功)
    ...
    
  2. 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 a marker-end attribute.

  3. Check for filter contamination: Search the SVG for any <line or connector <path that contains filter=. If found, remove the filter attribute from that element.

  4. 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)
  5. 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

  1. 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.svg exists: save as flowchart-v1.svg
    • If flowchart-v1.svg also exists: save as flowchart-v2.svg
    • Keep incrementing until an unused filename is found
    • Use ls or test -f to check existence before writing
  2. Write the SVG to the determined file path

  3. 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.png
    

    Then 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.

  4. 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.

  5. 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 filter to <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 Zheng for Chinese, Comic Sans MS for English. Never substitute with Caveat, Patrick Hand, Indie Flower, etc.
  • Text not looking handwritten: The Google Fonts @import requires internet access. If offline, fall back to system cursive fonts from the font stack (e.g., KaiTi for Chinese, Segoe Print for 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.

Related Skills