Diagram Generator

.svg

references/

Usage

# Prompt for the topic if no argument given
/baoyu-diagram

# Plain-text description
/baoyu-diagram "how JWT authentication works"

# Path to a markdown file as source content
/baoyu-diagram path/to/content.md

# Force a specific diagram type
/baoyu-diagram "transformer attention"    --type illustrative
/baoyu-diagram "Kubernetes architecture"  --type structural
/baoyu-diagram "CI/CD pipeline"           --type flowchart
/baoyu-diagram "OAuth 2.0 flow"           --type sequence
/baoyu-diagram "Shape hierarchy"          --type class

# Language and output path
/baoyu-diagram "微服务架构"              --lang zh
/baoyu-diagram "build pipeline" --out docs/build-pipeline.svg

Options

--type

flowchart

sequence

structural

illustrative

class

auto

--lang

en

zh

ja

ko

--out

diagram/{slug}/diagram.svg

Diagram types

references/flowchart.md

references/flowchart-phase-bands.md

references/sequence.md

references/structural.md

references/illustrative.md

references/class.md

--type flowchart

flowchart.md

structural.md

illustrative.md

flowchart.md

structural.md

structural.md

structural.md

structural.md

structural.md

sequence.md

illustrative.md

structural.md

class.md

event [guard] / action

flowchart.md

structural.md

structural.md

flowchart-phase-bands.md

flowchart-phase-bands.md

↻ returns to start

flowchart.md

Workflow

Step 1: Capture intent

1. Named elements — list every distinct actor, component, service, state, or phase explicitly named. Count them. If the count is 6+, plan multiple diagrams rather than cramming everything into one (see

   flowchart.md

   → "Planning before you write SVG").
2. Relationship type — for each interaction between elements, classify it:
   • Sequential steps / order of operations → flowchart signal
   • Containment ("X is inside Y", zones, hierarchies) → structural signal
   • Multi-actor message exchange (A sends to B, B replies to C) → sequence signal
   • Mechanism ("how does X produce Y") → illustrative signal More than one type present? Pick the dominant one, or plan two diagrams.
3. What the reader needs — complete this sentence before routing: "After seeing this diagram, the reader understands ___." If you can't finish it, the topic is underspecified — ask.
4. Label preview — for each element name, count the characters. Latin titles >30 chars (CJK >16) will overflow a 180-wide box and need shortening. Draft the abbreviated form now, before layout math, so Step 4 uses real labels.
5. Language — CJK vs. Latin. Affects text-width multipliers in Step 4 (15 px/char vs. 8 px/char for titles). Mixed content (CJK labels with some Latin terms) counts as CJK.

Step 2: Route the diagram type

--type

--type

Step 3: Load references

• references/design-system.md

  — philosophy, typography, color palette, hard rules

• references/svg-template.md

  — the

  <style>

  +

  <defs>

  boilerplate to copy verbatim

• references/layout-math.md

  — text-width estimation, viewBox sizing, arrow routing

• references/pitfalls.md

  — the pre-save checklist

• references/flowchart.md

• references/sequence.md

• references/structural.md

• references/illustrative.md

• references/class.md

• references/glyphs.md

  — the shared glyph library, tool card icon set, operator icons, and dark-mode rules

• references/flowchart-poster.md

  — when ≥3 poster-mode triggers fire in Step 4a (topic has a short name, named phases, parallel candidates, a loop termination mechanic, overflow annotations, or a footer quote)

• references/flowchart-phase-bands.md

  — when the prompt describes a multi-phase sequential operation where each phase contains parallel tools or steps and outcomes propagate between phases ("phase 1/2/3", "attack phases", "phased workflow with tools")

• references/structural-network.md

  — when drawing network topology: zone containers, wired/wireless device connectivity, security zones (DMZ / VPC / firewall)

• references/structural-matrix.md

  — when drawing a comparison matrix: feature table, ✓/✗ cells, side-by-side "option × attribute" grid

Step 3.5: Check the patterns library

references/patterns/

references/patterns/README.md

Step 4: Plan on paper first

• Mechanism name — does the topic have a short, nameable identity (Autoreason, AutoResearch, OAuth, JWT auth, Reflexion loop)? If yes, that's a candidate

  .title

  .
• Framing question — does the source contain a "why does this exist" sentence? Usually in the form "Problem X has no Y, so we built Z to …". That's a candidate subtitle.
• Phases — do the stages naturally cluster into 2–4 named groups (setup / loop body / judgment / convergence)? Each cluster is a candidate

  .eyebrow

  section.
• Anchor inputs — is there a constant input (the task prompt, a dataset, a knowledge base) that every stage references? That's a candidate anchor box above the main flow.
• Parallel candidates — at some point, does the process generate N alternatives that are then compared? "Produce A, B, AB and pick the best" is a candidate fan-out + judge pattern. Watch for the implicit "keep unchanged" candidate — many iterative methods include "the incumbent wins by default" as one of the options, even when the source doesn't name it explicitly.
• Loop scope + termination — which boxes are inside a loop that repeats? What is the specific termination rule — streak counter, convergence check, iteration cap, quality threshold? That's a candidate left-rail loop bracket + a dedicated termination box.
• Per-box context that won't fit in a subtitle — "sees task + A + critique / adversarial / fresh context" is too long for a 5-word subtitle but too important to drop. Those are candidate right-column

  .anno

  annotations.
• Quotable hook — does the source end with a test result, a quote, or a memorable framing? That's a candidate footer

  .caption

  .
• Role categories — how many distinct kinds of operation does the process have (draft / critique / synthesize / judge)? This determines the color budget. Identity is a category, not a sequence.

references/flowchart-poster.md

1. List the nodes / regions / shapes with their full label text (title + optional subtitle).
   • Simple flowchart: ≤5 nodes.
   • Poster flowchart: ≤12 nodes grouped into ≤4 eyebrow-divided phases.
   • Structural: ≤3 inner regions.
   • Illustrative: 1 subject.
   • Sequence: list actors (2–4, max 4) in left-to-right order, each with a short title (≤12 chars) and optional role subtitle; then list messages as ordered

     (sender, receiver, short label)

     tuples (6–10 total, 10 is the sweet spot); mark any self-messages; draft a side-note title for the protocol.
2. For every rect, compute the width using the formula in

   layout-math.md

   :

   • width = max(title_chars × 8, subtitle_chars × 7) + 24

     (Latin)
   • Replace 8 with 15 and 7 with 13 for CJK
   • Round up to the nearest 10
3. Pick colors by category, not sequence. ≤2 accent ramps per diagram. Gray for neutral/start/end. Reserve blue/green/amber/red for semantic meanings.
   • Sequence exception: assign one ramp per actor (default

     [gray, teal, purple, blue]

     ), up to 4 ramps total — arrows inherit the sender's ramp.
   • Poster-flowchart exception: up to 4 ramps, one per distinct agent/role (drafter=purple, critic=coral, synthesizer=teal, judge=amber). Baseline/anchor/convergence stay gray.
4. Check tier packing:

   N × box_width + (N-1) × gap ≤ 600

   . For sequence, use the lane table in

   layout-math.md

   (N=4 → centers 100/260/420/580) and verify every message label fits its lane span with

   label_chars × 7 ≤ |sender_x − receiver_x| − 8

   . For poster fan-out rows (3 candidates), see the coordinate sketch in

   flowchart.md

   .
5. Map arrows and verify none cross an unrelated box. Use L-bends where a straight line would collide. (Sequence messages are always straight horizontal lines — no L-bends. Fan-out candidates converge to a common

   ymid

   channel just above the judge box.)
6. Compute viewBox height:

   H = max_y + 20

   where

   max_y

   is the bottom of the lowest element. Poster flowcharts routinely reach H=800–950 — don't force them to be compact.

diagram/{slug}/plan.md

Step 5: Write the SVG

<svg width="100%" viewBox="0 0 680 H">

<style>

<defs>

svg-template.md

1. Background decorations (rare)
2. Containers (outer

   <rect>

   for structural diagrams)
3. Connectors and arrows (drawn first so nodes paint on top)
4. Nodes (rects with text)
5. Labels outside boxes (leader callouts, legends, external I/O labels)

• Two sizes only: 14px (

  t

  ,

  th

  ) and 12px (

  ts

  )
• Two weights only: 400 and 500
• Sentence case everywhere — "User login" not "User Login"
• Every

  <text>

  element gets a class (

  t

  ,

  ts

  , or

  th

  ) — never hardcode fill colors on text

Step 6: Run the pre-save checklist

references/pitfalls.md

1. viewBox height covers every element with a 20px buffer
2. No rect extends past x=640
3. Every labeled rect is wide enough for its text (char-width check)
4. No arrow crosses an unrelated box
5. Every

   <path>

   connector has

   fill="none"

   (or uses

   class="arr"

   )
6. Every

   <text>

   has a class — no hardcoded

   fill="black"

7. No

   text-anchor="end"

   at low x values (label would clip past x=0)
8. ≤2 accent ramps, colors encode category not sequence
9. No

   <!-- comments -->

   in the final output

Step 7: Save output

--out

diagram/{topic-slug}/
├── source-{slug}.md          # optional: user's input content if provided
├── plan.md                   # layout sketch from Step 4
└── diagram.svg               # final output

• Slug: 2–4 kebab-case words derived from the topic.
• Backup rule: if

  diagram.svg

  already exists at the target path, rename the existing one to

  diagram-backup-YYYYMMDD-HHMMSS.svg

  before writing the new file — never overwrite prior work silently.
• Plan: always save

  plan.md

  from Step 4 beside the SVG so the next iteration can re-read it.
• Source: if the user pasted source content, save it as

  source-{slug}.md

  in the same directory.

Step 8: Report

• Diagram type picked (and one-sentence why)
• Node count / complexity
• viewBox dimensions
• Language
• Output file path
• One suggestion for how to preview it (e.g., "Open in Chrome for light/dark check")

Core principles

• Draw the mechanism, not a diagram about the mechanism (illustrative). Draw the sequence, not the architecture (flowchart). Draw the containment, not the flow (structural). Draw the conversation, not the steps (sequence). Picking the wrong type is the single biggest failure mode — more harmful than any layout bug.
• One design system, always. No

  --style

  flag, no alternate themes, no per-topic visual variants. The cohesive look across every diagram is the product — if a reader sees two baoyu diagrams in different articles, they should feel they came from the same hand. Any request to "use a different style" is a request to break this principle; push back and ask what the underlying need is instead.
• Self-contained output. Every SVG carries its own styles and dark-mode rules. The reader should never need to edit anything after pasting it into their article.
• Math before markup. SVG has no auto-layout. Every coordinate is hand-computed. A diagram that "almost fits" has a bug — fix the math, don't nudge pixels.
• Color encodes meaning, not position. Five steps in a flowchart are not five colors. All five are gray unless one specific step deserves emphasis — in which case it gets the accent color.
• The reader has 3 seconds. If the diagram needs prose explanation to parse, it's failing. Simplify until it can stand alone with only its labels.

References

• references/design-system.md

  — palette, typography, hard rules

• references/svg-template.md

  — the

  <style>

  +

  <defs>

  boilerplate (copy verbatim)

• references/layout-math.md

  — coordinates, text widths, viewBox math, arrow routing

• references/pitfalls.md

  — the pre-save checklist

• references/flowchart.md

  — flowchart-specific rules and worked examples (includes state-machine sub-pattern)

• references/flowchart-poster.md

  — poster flowchart dialect (load on demand when ≥3 poster triggers fire)

• references/flowchart-phase-bands.md

  — phase-band flowchart (horizontal dashed phase containers, compact tool card rows, cross-band semantic arrows, operator icons, legend strip)

• references/sequence.md

  — sequence-diagram rules (actors, lifelines, messages, self-messages)

• references/structural.md

  — structural-specific rules and worked examples (subsystem, bus, radial star, rich interior, mixed arrows)

• references/structural-network.md

  — network topology sub-pattern (zone containers, wired/wireless, tiered layout)

• references/structural-matrix.md

  — comparison matrix sub-pattern (feature table, ✓/✗ cells, zebra rows)

• references/illustrative.md

  — illustrative-specific rules and worked examples

• references/class.md

  — UML class diagram rules (3-compartment rects, relationships, stereotypes)

• references/glyphs.md

  — shared glyph library (status circles, checkboxes, queue slots, icons, annotation circles) and concept-to-shape conventions

• references/patterns/

  — pre-planned starters for common AI-system topologies (RAG, agents, memory tiers, verifier loops, …)