Create polished hand-drawn diagram pages that look like a sketched whiteboard or notebook page, then export them to PNG.
-
Use 1500x900 for sparse diagrams. Start dense branch diagrams or text-heavy bilingual diagrams at 1600x1000, then grow further if rendered text still reduces connector corridors.
-
Keep text short. Diagram text should explain, not become a document.
-
Prefer 3-6 major blocks for architecture diagrams.
-
Prefer 5-7 steps for flywheel diagrams.
-
For dense diagrams, use markerUnits="userSpaceOnUse" with an 8-10px marker box. Use 2.4-3px connectors and a 2-2.5px shared bus; do not let arrowhead size multiply with stroke width. Reserve heavier arrows for sparse hero flows.
-
Prefer a small filled triangle or open chevron in dense layouts. Never use a large filled triangle when the connector corridor cannot contain it.
-
For fan-out or fan-in with three or more branches, use one thin shared bus. Put arrowheads only on terminal directed legs: bus-to-targets for fan-out and merged-bus-to-next-node for fan-in. Keep about 28-36px between each bus and its target cards.
-
End each arrow tip 6-10px outside the target card instead of touching or entering its border.
-
For L-shaped, Z-shaped, or perimeter connectors, keep at least 24px of straight terminal run from the final bend to the arrow tip. Move the bend when necessary; never place an arrowhead directly on a corner.
-
Keep the primary flow solid. Draw fallback, failure, and return paths as dashed edge-routed connectors, and place their labels on opaque paper-colored backgrounds so lines never cut through text.
-
Route return, failure, and feedback arrows outside the primary forward flow,
preferably on the right or top edge of the lane. Show the complete path from
the source node back to the target node, and end the arrow just outside the
target card if SVG arrows are rendered beneath HTML cards.
-
Reserve visible breathing room for return-arrow corridors. If a right-side
result callback uses the right edge, start other feedback loops from the top
or middle of their source card so separate loops do not visually merge.
-
Leave enough horizontal space between adjacent forward-flow cards for arrows
to read as links, not as decorations squeezed between boxes.
-
Leave enough vertical space between stacked cards for the full arrow shaft,
arrowhead, and optional label. A forward-flow arrowhead should never touch or
overlap the next card; keep at least 28-36px of visible connector corridor
between card edges.
-
Measure rendered card height after text is inserted. Do not route from CSS min-height assumptions; translated text can grow a card and hide connectors drawn underneath it.
-
Separate branch lanes on both axes. Move the main lane and branch/fallback
lane apart horizontally, and stagger branch targets vertically so cross-lane
arrows do not graze cards or labels.
-
For structural, architecture, and relationship-heavy diagrams, assign
explicit anchor points per edge (top / right / bottom / left). Do not let
multiple unrelated relationships leave from the same visual point unless they
are intentionally a bundled bus.
-
Prefer straight, vertical, horizontal, or simple L-shaped connectors for
structural relationships. Use curves only when they clarify a return or
cross-lane relationship; never stack two similar curves under the same node.
-
Keep relationship labels offset from both the connector and the card edge.
Cardinality and edge labels should sit in their own small visual space, not
directly on top of a line.
-
If the layout cannot preserve readable connector corridors, shorten labels, reduce node count, or split the diagram before shrinking the gaps further.
-
Use a watermark only when the user asks for one.
-
For bilingual output, keep topology, ordering, colors, and visual hierarchy consistent, but do not force identical coordinates. Render each language separately and expand the canvas, cards, lanes, or gaps when translation wraps onto extra lines. Move downstream nodes before shrinking type or connector corridors.
-
Use this fixed-size marker pattern for dense SVG flows:
<marker id="arrow" markerWidth="10" markerHeight="10"
refX="9" refY="5" orient="auto" markerUnits="userSpaceOnUse">
<path d="M0,0 L10,5 L0,10 Z" fill="#1f2328"></path>
</marker>
-
If adding a watermark, keep it subtle and out of the content area:
<div class="watermark">@handle</div>
.watermark {
position: absolute;
right: 56px;
bottom: 12px;
color: rgba(31, 35, 40, 0.28);
font: 900 19px "Avenir Next", sans-serif;
letter-spacing: 0.05em;
transform: rotate(-2deg);
pointer-events: none;
}
