Restore Diagram Legibility
Make an auto-generated graph diagram readable again after it has outgrown its
canvas. The content is usually fine — forced to 1:1 the labels are crisp — so
this is a delivery failure, not an authoring one, and the fix is reducing the
diagram's layout units, not styling its text.
All numbers in this skill are one measured instance (a 39-diagram corpus,
2026-07), shipped as evidence that a lever moves the needle — never as targets.
When to Use
- A generated Mermaid/Graphviz/DOT diagram renders at single-digit percent
scale in its display column, putting nominal 12px labels below ~1px
- Fullscreen or zoom helps by 2x against a 10x+ deficit
- The same diagram is legible when force-rendered at 1:1 (content is fine)
- NOT for hand-authoring a small diagram, and NOT for aesthetic styling —
see
create-2d-composition for composition work
Inputs
- Required: The diagram source (Mermaid, Graphviz/DOT, or another
Sugiyama/Dagre-family layout input)
- Required: A way to render and measure output width in layout units or
pixels (CLI renderer, browser devtools, or the generated SVG's viewBox)
- Optional: The display context's column width, to compute effective
label size (nominal font px x render scale)
Procedure
Step 1: Measure the Deficit Before Touching Anything
Compute the render scale and effective label size; confirm the situation
matches this skill.
# SVG output: viewBox width = layout units. Effective label px =
# nominal font px * (display column px / viewBox width).
grep -o 'viewBox="[^"]*"' diagram.svg
# e.g. viewBox="0 0 2685 900" in a 640px column:
# scale = 640/2685 = 23.8%; a 12px label renders at 2.9px
One measured instance: a system map rendered at 6.9% scale — nominal 12px
labels at 0.83px effective. Fullscreen was a 2x improvement against a ~15x
deficit.
Expected: A number pair (scale %, effective label px) and confirmation
that a 1:1 render is crisp. If 1:1 is also illegible, the problem is
authoring, not delivery — stop here, this skill does not apply.
On failure: If the renderer emits raster only, measure image width vs
display width instead; the ratio is the same scale factor.
Step 2: Skip the Two Levers That Measurably Do Not Work
Do not spend time on these; both were killed by measurement.
- Raising the render font is a no-op. Sugiyama/Dagre-family layout
engines measure node sizes in text units, so the canvas grows with the
font and the ratio barely moves. Measured: 5.2px -> 8.3px effective for a
much larger file — against a 10x+ deficit. This is a property of the
layout family, not of any one tool version.
- Predicting layout direction from topology fails. A star-shape
heuristic (one hub holding most edges -> flip direction) helped the two
diagrams still too wide but regressed 13 of 38, dropping the
median effective label from 25.9px to 16.3px. Direction can only be
measured (Step 6), not predicted.
Expected: The diagram source contains no font-size override added for
legibility and no direction attribute chosen by a topology heuristic; if
either is present from a prior attempt, it is reverted and the layout-unit
change from the revert is recorded.
On failure: If a font increase was already applied, revert it before
measuring the real levers — it inflates layout units and masks their effect.
Step 3: Wrap Long Labels at the Source
Node width tracks the longest unbroken line in the label, and total canvas
width follows. Break labels into short lines in the diagram source (Mermaid:
<br/> inside the label text; Graphviz: \n in the label attribute).
One measured instance: 2685 -> 901 layout units from wrapping alone.
Expected: Canvas width in layout units drops substantially on re-render;
labels occupy 2-3 short lines instead of one long one.
On failure: If wrapping changes nothing, the width driver is elsewhere —
check for one very wide row of disconnected nodes (Step 4) or a single
oversized cluster (Step 5).
Step 4: Chain Disconnected Components with Invisible Links
Layout engines place nodes with no edges in one wide row, spreading the
canvas. Add invisible links (Mermaid: ~~~; Graphviz: style=invis edges)
between disconnected components so the engine stacks them instead.
One measured instance: 3292 -> 881 layout units. The worst single case was a
cluster 3292 units wide holding 6 nodes and zero edges.
Expected: Disconnected nodes stack into rows/columns; canvas width drops.
On failure: If the renderer treats the invisible-link syntax as a real
edge (arrows appear), check the tool's spelling for an invisible or
unstyled link; the construct is general even where the syntax differs.
Step 5: Split One Canvas into Per-Cluster Diagrams
A whole system on one canvas divides one column width across every parallel
cluster. Emit one diagram per cluster (or per subsystem) instead; the index
page links them.
One measured instance: median effective label size went 0.8px -> 25.9px.
Do NOT pick split candidates by node count — in the measured corpus the
illegible clusters had a median of 6 nodes, identical to the legible ones;
width, not membership, is the axis.
Expected: Each split diagram is independently legible at its display
size; nothing shares a canvas with an unrelated cluster.
On failure: If clusters are interlinked so splitting breaks edges,
duplicate boundary nodes into both diagrams with a visual marker rather
than keeping one merged canvas.
Step 6: Pick Layout Direction by Rendering Both and Measuring
Direction (top-down vs left-right) is shape-dependent: measure, do not
predict (Step 2.2). Render the diagram in both directions, compare canvas
width in layout units, keep the narrower.
One measured instance: 2682 -> 1311 units from a direction flip — on that
diagram; the same flip regresses others, which is why the comparison is
per-diagram.
Expected: Both renders exist; the kept direction is the measured winner
for this diagram, not a global default.
On failure: If both directions are still too wide, return to Steps 3-5;
direction is the last lever, not the first.
Step 7: Re-Measure and Record the Numbers
Recompute scale % and effective label px per diagram. Record before/after in
the commit or PR that ships the change, as one measured instance.
Across the measured 39-diagram corpus: median effective label 13.7px ->
25.9px; 30/39 -> 37/39 diagrams at 10px or better. The legibility floor
comes from Step 1's formula for your display context — not from any
number in this skill.
Expected: The before/after pair is recorded next to the change; any
diagram still below the display's legibility floor is listed explicitly,
not averaged away.
On failure: If a diagram resists all four levers, say so in the record —
an explicit residual beats a silently truncated claim of success.
Validation
Common Pitfalls
- Raising the render font: Layout engines measure in text units, so the canvas grows with the font — measured 5.2px -> 8.3px against a 10x+ deficit, at a much larger file size. Wrap the text instead; the lever is the text, not the font
- Predicting direction from topology: A hub-shape heuristic regressed 13 of 38 diagrams (median 25.9px -> 16.3px). Render both directions and measure; direction is per-diagram
- Splitting by node count: The wrong axis — illegible and legible clusters had the same median node count (6); one 6-node zero-edge cluster was 3292 units wide. Split by measured width
- Shipping the numbers as targets: Every figure here is one measured instance. Copying "901 units" or "25.9px" into acceptance criteria turns evidence into cargo cult; measure your own corpus
- A rejected approach without its measurement: "We tried X, it did not help" is not a negative result — it earns its place only with the measurement that killed it, so the next reader can check whether their case differs
Related Skills
<!-- Keep under 500 lines. Extract large examples to references/EXAMPLES.md if needed. -->