Show

show

Create a visual artifact as a raw, self-contained SVG file and stream it to the show viewer pane.

Workflow

Do NOT open the viewer pane before the artifact is ready. The pane opens as the last step, landing directly on the new artifact — never on an old one while you work.

1. Read the canvas budget (published by the viewer; the file persists between sessions):

   cat ~/.show/viewport
   # {"cols":94,"rows":51,"cell_w_px":20,"cell_h_px":40,"width_px":1880,"height_px":2040}
   

   width_px × height_px is your drawing area. If the file is missing (viewer has never run), assume 900×1300 portrait.

2. Design the SVG to that budget (rules below) and write it to disk. Any path works — prefer the project, e.g. ./diagrams/<slug>.svg.

3. Publish it — append to the queue first, then open/focus the viewer:

   echo "/absolute/path/to/artifact.svg" >> ~/.show/queue
   herdr plugin action invoke show.show
   

   The viewer always displays the newest queue entry, so it opens straight onto your artifact. If it was already open, the queue append alone re-renders it instantly.

Design rules

Canvas.

• Set viewBox="0 0 W H" with W = width_px, so 1 SVG unit renders as ≈1 real pixel — all the size numbers below then mean what they say.
• Keep H ≤ height_px for a pixel-perfect fit. Exceeding it triggers uniform downscaling; never exceed ~1.4× or text becomes unreadable.
• 24-unit safe margin on every side; nothing touches the edge.
• Transparent background — no full-canvas <rect>, no page/paper backdrop. The artifact composites directly onto a dark terminal; a white canvas looks like a hideous pasted document.

Layout — SVG has no layout engine, so do the arithmetic before writing markup.

• Plan every coordinate first: panel at x=80 with width 360 means its right edge is 440, so the next column starts at ~468. Catch collisions in this arithmetic pass, not by eyeballing.
• Budget text width numerically: ≈ 0.6 × font-size per character (0.62 for monospace). An 18px label of 22 chars is ~240 units wide — check it fits before placing it. If a label doesn't fit, shorten the label; never shrink the font or let it overflow.
• Grid rhythm: fixed row pitch (34–40 units), consistent 16-unit padding, one alignment column per element type.
• Use dominant-baseline="central" so text sits vertically centered in rows and pills.
• No overlapping text, ever. Annotations live in clear space and point with short leader lines — they never sit on top of content.

Style.

• Light-on-dark: light text and strokes (e.g. #cdd6f4, #a6adc8), 2–3 accent colors maximum, one meaning per color (e.g. blue = component, yellow = data flow, green = external).
• Exactly three text sizes: heading ~26, body ~17, secondary ~13. Body text never below 15 units.
• Local panels (node boxes, cards) are encouraged — rounded rects with strokes or subtle dark fills, scoped to their content, not the canvas.

Scope.

• Use the full canvas. The artifact renders at pane-filling size — design like it owns the space. If the content is sparse, scale the composition up (larger nodes, roomier spacing, bigger type) rather than leaving most of a tall pane empty.
• Degradation is asymmetric: too tall → uniform downscale → unreadable text (never do this); shorter than the budget → just empty space below (acceptable). When unsure, err short, never tall.
• Don't cram. The pane is usually tall and narrow — favor vertical stacking over wide sprawl.
• If the topic needs more than one screenful, emit multiple focused artifacts (append several paths to the queue) — the viewer is a stream with n/p navigation. One artifact = one idea.

Notes

• SVG only. Do not generate HTML or raster images for this flow.
• Self-contained only: inline styles, no external images/fonts/scripts.
• Always append an absolute path to the queue.
• If a later request refines the same diagram, write a new file (or overwrite and re-append) — each queue line is one entry in the visual stream.
• If herdr is not available (not inside a herdr session), skip the publish steps and just tell the user where the SVG was saved.