sketchboard-diagram

name	sketchboard-diagram
description	Generate hand-drawn grid-paper style architecture diagrams, workflow loops, flywheels, and README visuals as self-contained HTML pages and PNG exports. Use when the user wants a sketchy whiteboard-style diagram, system map, process flow, loop diagram, or bilingual Chinese/English visual.
metadata	{"short-description":"Hand-drawn architecture diagrams as HTML and PNG"}

Sketchboard Diagram

Create polished hand-drawn diagram pages that look like a sketched whiteboard or notebook page, then export them to PNG.

When To Use

Use this skill for:

• architecture diagrams
• workflow maps
• flywheel / loop diagrams
• README visuals
• presentation visuals
• bilingual Chinese / English versions of the same diagram

Workflow

1. Pick a starting point:

   • examples/templates/architecture.html for multi-lane system maps.
   • examples/templates/flywheel.html for circular loops and self-reinforcing systems.
   • examples/retrieval-flow-zh.html or examples/retrieval-flow-en.html as a reference for dense fan-out, merge, fallback, and failure-state flows.

2. Copy the selected template or reference example to the requested output path.

3. Edit the HTML directly:

   • Replace title, subtitle, node labels, note cards, arrows, and paths.
   • Keep the grid-paper background, hand-drawn cards, and six-color palette unless the user asks for another style. Scale connector weight to diagram density.
   • If the user asks for Chinese and English, create two HTML files rather than mixing languages on one page.

4. Export PNG:

   node scripts/render-html-to-png.mjs output.html output.png
   

5. Review the PNG:

   • no overlapping arrows and labels
   • no clipped text
   • no tiny unreadable text
   • arrows clearly show direction
   • return / feedback arrows are fully visible from source to target
   • arrowheads are not hidden under cards or clipped by the canvas edge
   • dense branch diagrams use small fixed-size arrowheads with visible space before each target card
   • elbowed connectors keep visible straight shaft between the final bend and arrowhead
   • loop diagrams use matching step count and ring segments

Style Rules

• 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;
  }
  

Assets

• Templates:
  • examples/templates/architecture.html
  • examples/templates/flywheel.html
• Examples:
  • examples/architecture-zh.html
  • examples/architecture-en.html
  • examples/flywheel-zh.html
  • examples/flywheel-en.html
  • examples/retrieval-flow-zh.html
  • examples/retrieval-flow-en.html
• Renderer:
  • scripts/render-html-to-png.mjs

Common Prompts

Use sketchboard-diagram to draw a hand-drawn architecture map for this system. Output HTML and PNG.

用 sketchboard-diagram 画一张中文飞轮图，表达 daily loop、weekly review、knowledge layer、runtime loader 怎么形成自进化。

Create Chinese and English versions of the same sketchboard-style README diagram.