artifact-diagramming

name	artifact-diagramming
description	Diagramming know-how for Artifacts - when a picture earns its place, how to draw one that shows the real mechanism, and the inline-SVG mechanics that keep it legible in both themes.

Draw as the engineer who has to live with the decision, not as a decorator: a diagram earns its place when it lets a cold reader see a mechanism they would otherwise have to assemble from prose - where data flows, which components talk, what changes between two options, what state a request moves through. If a sentence says it faster, write the sentence.

What to draw

Depict the mechanism, not its name. A box labeled "cache" says less than the prose; the path a request takes through it, the two stores it sits between, and the arrow that disappears when the cache is removed say what the words can't. Show the parts that the argument hinges on - the boundary being crossed, the hop being added, the data that moves - and leave out the parts that don't.

Comparing options? Draw the difference. Two architectures side by side, a before and an after, the one edge that each option adds or removes - the reader should be able to point at what they are choosing between. A separate labeled box per option, with nothing connecting them to the system, is not a comparison; it is a restated option list.

Match complexity to the stakes. A one-hop question is a three-box diagram; a migration that reroutes writes through a queue needs the queue, the writer, the reader, and the ordering arrow. Draw as much as the decision actually turns on - no forced minimalism, no inventory of the whole system either.

Label the arrows. An unlabeled arrow is "related somehow"; writes, invalidates, polls every 30s is information. A legend is only worth it when the same encoding (dashed, colored, doubled) repeats; otherwise put the meaning on the mark itself.

Inline SVG mechanics

These mechanics apply where the page renders inline SVG natively (HTML pages); a markdown-rendered page draws its diagrams in whatever fence that lane's renderer supports, and the skill that owns the lane says which. Hand-author inline <svg> with native shapes (rect, circle, line, polyline, path) and <text> - no libraries, no runtime, no external images.

• Size by viewBox. Set viewBox="0 0 W H" and let CSS scale it (max-width: 100%; height: auto); choose W and H for the content, not a preset. Wide flows read left-to-right; layered stacks read top-to-bottom.
• Theme with currentColor. Strokes, text, and arrowheads in currentColor inherit the page's foreground in light and dark themes alike; reserve a literal hue for the one element that carries meaning (the option leaned toward, the hop under discussion), and make sure it reads on both grounds.
• Arrowheads are markers or polygons. A <defs><marker> referenced by marker-end="url(#arrow)" (fragment-internal id) or a small <polygon> at the line's end - never an image.
• Keep text legible. Roughly 11-13px at the drawn scale, text-anchor for alignment, short labels (a word or three); explanatory sentences belong in the caption below the figure, not in the drawing.
• Align to a grid. Shared baselines and even gaps are most of what makes a hand diagram read as deliberate; eyeballed offsets read as noise.
• One figure, one claim. Wrap the <svg> in <figure> with a <figcaption> that states what the picture shows, and give the <svg> role="img" plus an aria-label carrying the same claim for readers who cannot see it.
• Stay self-contained. No <script>, <style>, or <foreignObject> inside the SVG; gradients, patterns, and <use> reference ids in the same fragment (href="#id"). Long decorative path data is a sign the drawing wants a real graphics tool - simplify instead.