/handdrawn-diagram

name: handdrawn-diagram
description: >-
  Generate a hand-drawn (sketch-style) architecture or flow diagram as a
  committable image (SVG + PNG). Use when the user wants a sketch-aesthetic
  diagram for a README, docs, or hackathon/Devpost submission that still has
  correct, legible text and per-group color. Authors a Mermaid look:handDrawn
  source and renders it with mermaid-cli — works on any viewer and on Devpost.
  Triggers on: 'hand-drawn diagram', 'sketch diagram', '손그림 다이어그램',
  '손그림 아키텍처', '스케치 도식', 'handDrawn', 'Devpost diagram', '손그림으로 그려줘',
  '아키텍처 손그림', 'sketch-style architecture'.
allowed-tools: Read, Write, Edit, Bash, Glob

Hand-drawn diagram (Mermaid look:handDrawn → SVG/PNG)

Renders identically everywhere (README, GitHub/GitLab, Devpost, slides), unlike inline Mermaid (depends on the viewer's Mermaid version) or AI image generators (garbled text).

When to use

• User asks for a "hand-drawn / sketch / 손그림" architecture or flow diagram.
• A diagram is needed as an image file (Devpost, slides, print), not just inline.

Method

1. Write the Mermaid source (`.mmd`)

---
config:
  look: handDrawn
  theme: default
  themeVariables:
    fontFamily: "Apple SD Gothic Neo, Malgun Gothic, Noto Sans KR, sans-serif"
---
flowchart TD
    A(["Trigger"]):::main --> B["main step"]:::main
    B --> C{"decision?"}:::decision
    C -->|Yes| D["highlighted path"]:::main
    C -->|No| E["side step"]:::muted
    D --> F[("datastore")]:::muted
    E -.-> G["error / end"]:::alert
    classDef main     fill:#e8eaf6,stroke:#3949ab,stroke-width:2.5px,color:#1a237e;
    classDef decision fill:#fff8e1,stroke:#f9a825,stroke-width:2px,color:#e65100;
    classDef muted    fill:#fff,stroke:#9e9e9e,color:#616161;
    classDef alert    fill:#ffebee,stroke:#e53935,color:#b71c1c;

Rules that avoid broken output:

• **Quote every label** `["..."]` — `·—≥→/()` break unquoted.
• **No emojis in nodes** — headless Chromium renders them as tofu; use words.
• Shapes carry meaning — pick by role, not looks:
• `([..])` start/end terminal · `[..]` process step · `[(..)]` datastore/DB
• `{..}` **decision** (diamond) — every decision MUST have labeled branches:

`C{"logged in?"} -->|Yes| D` and `C -->|No| E`. Don't fake a branch with a plain `[..]` step; a fork without a diamond + condition labels reads as a straight line and loses the "when this / when that" meaning.

• `<br/>` for line breaks; Korean renders fine with the fontFamily above.

Color — meaning, not decoration (60-30-10)

Coloring every node flattens the hierarchy and nothing reads as important. Use **2–3 colors that each carry meaning**, and let most nodes stay neutral:

• **~60% `muted`** (neutral white/gray) — ordinary steps, datastores, side paths.
• **~30% `main`** (one accent, e.g. indigo) — the pipeline you want the eye to

follow (the happy path). Emphasize with `stroke-width`, not loud fills.

• **~10% semantic** — `decision` (amber) for diamonds, `alert` (red) for

error/terminal states. Reserve these so a color instantly signals a role.

Rule of thumb: if a reader can't guess what a color *means*, drop it. One accent is too plain (no role distinction); 5+ colors are noise (no hierarchy). 2–3 semantic colors give both hierarchy and classification while staying calm.

2. Render to SVG + PNG (no Chrome install needed)

printf '%s\n' '{"args":["--no-sandbox","--disable-setuid-sandbox"]}' > /tmp/pptr.json
npx -y @mermaid-js/mermaid-cli -i d.mmd -o d.svg -p /tmp/pptr.json -b white
npx -y @mermaid-js/mermaid-cli -i d.mmd -o d.png -p /tmp/pptr.json -b white -s 2

`-b white` = white bg · `-s 2` = 2× crisp PNG · `look:handDrawn` needs mermaid-cli v11+ (npx pulls latest).

3. Verify → embed → commit

• **Read/open the PNG** and confirm: text correct, no tofu, colors right.
• Embed the PNG: ``.
• Commit all three: `.mmd` (source) · `.svg` (vector master) · `.png` (embed).

Gotchas

• macOS has no `timeout` — don't wrap npx in it.
• Never put a triple-backtick inside an unquoted `awk`/`grep` pattern (zsh runs backticks as command substitution).
• Label needs `&` → write `and`.
• **CJK clips in handDrawn nodes.** rough.js under-estimates Korean/CJK glyph

width, so a wide 한글 label gets cut at the node's right edge (e.g. "다이어그램" → "다이어그"). Keep Korean node text short, break earlier with `<br/>`, or pad with a trailing space inside the quotes (`"손그림 다이어그램 "`). Always verify in step 3 by reading the PNG.

• **Mixed Korean+Latin on one line clips the trailing Latin.** A line like

`"순차 BUILD"` loses its last char (→ "순차 BUIL"), but a pure-Latin line (`"team BUILD"`) renders fine. So don't end a 한글 line with a Latin word: put the Latin token on its own `<br/>` line (`"순차<br/>BUILD"`) or pad the line. A single trailing space is often NOT enough — verify the PNG and add more.