flow-diagram

name	flow-diagram
description	Builds SVG user-flow diagrams for an audit (entry → screens → conversion/drop-off) following the PLAYBOOK §11a constants. Use when the user asks for a "flow diagram", "user flow", or "flow map".

flow-diagram

Hand-authors an SVG flow diagram per audit role (client, trainer, etc.), then converts to PNG for Notion.

Source format

SVG, hand-edited, saved to screenshots/flow-<role>.svg. Never Mermaid (Notion doesn't render it reliably).

Constants (PLAYBOOK §11a)

Element	Style
viewBox	900 × 130 linear, 900 × 200 branching
block size	112–180 × 55–60 px, rx=8
font	-apple-system, 'Segoe UI', Roboto, sans-serif
normal node	fill #fff stroke #e5e7eb
friction/warning	fill #fffbeb stroke #d97706
entry/highlight	fill #eff6ff stroke #1aa7e8
critical	fill #fef2f2 stroke #dc2626
arrow color	matches the node it points to

Template

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 900 130" font-family="-apple-system, 'Segoe UI', Roboto, sans-serif">
  <defs>
    <marker id="arr-normal" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="6" markerHeight="6" orient="auto">
      <path d="M0,0 L10,5 L0,10 z" fill="#9ca3af"/>
    </marker>
    <marker id="arr-warn" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="6" markerHeight="6" orient="auto">
      <path d="M0,0 L10,5 L0,10 z" fill="#d97706"/>
    </marker>
  </defs>

  <!-- Entry -->
  <rect x="10" y="40" width="140" height="55" rx="8" fill="#eff6ff" stroke="#1aa7e8" stroke-width="2"/>
  <text x="80" y="72" text-anchor="middle" font-size="13" fill="#0b1220">Landing</text>

  <!-- Arrow -->
  <line x1="150" y1="67" x2="195" y2="67" stroke="#9ca3af" stroke-width="1.5" marker-end="url(#arr-normal)"/>

  <!-- Normal node -->
  <rect x="200" y="40" width="140" height="55" rx="8" fill="#fff" stroke="#e5e7eb" stroke-width="1.5"/>
  <text x="270" y="72" text-anchor="middle" font-size="13" fill="#0b1220">Search</text>

  <!-- Friction node -->
  <rect x="580" y="40" width="140" height="55" rx="8" fill="#fffbeb" stroke="#d97706" stroke-width="2"/>
  <text x="650" y="66" text-anchor="middle" font-size="13" fill="#0b1220">Auth wall</text>
  <text x="650" y="82" text-anchor="middle" font-size="11" fill="#d97706">no context</text>
</svg>

Extend vertically for branching flows (split → two paths → rejoin).

Embedding

• HTML deliverable: <img class="flow-img" src="screenshots/flow-client.svg" alt="Client flow"> — browsers render SVG as image.
• Notion: convert to PNG (next section), upload via upload-image, embed via ![](<url>).

SVG → PNG

rsvg-convert -o screenshots/flow-client.png --width=1400 screenshots/flow-client.svg

Width 1400 gives enough resolution for Notion's image zoom without being heavy.

Rules

• One role per diagram. Don't cram buyer + seller in one SVG.
• Label friction, not pixels. Below-node label should say why it's friction ("no context", "requires login"), not repeat the node name.
• Entry node always blue (#eff6ff). End state (success) can be green stroke #059669 if you want — optional.
• Arrows match downstream node color when pointing to a friction/critical node, otherwise grey.
• Never inline SVG into the HTML. Keep it as a file so Notion can reuse the PNG.

After publishing

If the deliverable goes to Notion, always regenerate PNG and re-upload. Old URLs may 0-byte-fail — verify via curl -I.