# Show

> Render a diagram or visual artifact for the user as a raw SVG in a live herdr pane. Use when the user says "show me <thing>" or invokes /show or asks to visualize, diagram, or sketch something while working inside a herdr session.

- Skill: `plannotator/show` (Agent Skill)
- Install (CLI): `npx skillmds@latest add plannotator/show`
- Raw SKILL.md: https://api.skillmd.com/api/skills/plannotator/show/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: plannotator (https://skillmd.com/u/plannotator)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/plannotator/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):

   ```bash
   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:

   ```bash
   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.