Refine SVG diagrams for readability in documents and slides. Use this skill when a user wants text resized, blocks widened, arrows rerouted, overlapping labels fixed, or an existing figure made easier to edit and export without redesigning it from scratch.
Installation
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Refine SVG diagrams for readability in documents and slides. Use this skill when a user wants text resized, blocks widened, arrows rerouted, overlapping labels fixed, or an existing figure made easier to edit and export without redesigning it from scratch.
license
BSD-3-Clause (see repo LICENSE)
SVG Diagram Tuning
Overview
Use this skill to improve an existing SVG diagram without changing its meaning.
Focus on readability first: text, spacing, arrows, and visual hierarchy.
When to use
Text is too small or cropped
Blocks overlap or feel cramped
Arrow flow is unclear
The figure needs to export better into DOCX or PDF
Workflow
Inspect the current structure and identify the source of crowding.
Fix geometry before increasing font sizes aggressively.
Sweep the whole semantic family before replying: if one card title, legend, callout,
or arrow corridor is wrong, inspect the sibling elements of the same type and fix
the full class of issue in one pass.
Rebalance titles, body text, padding, and connector anchors together rather than as
isolated micro-fixes.
Rebalance line breaks across sibling cards together. If one block is rewrapped,
inspect whether its peers need the same semantic treatment.
When a defect sits inside a local cluster such as source block + target block + connector, rebalance that whole sub-ensemble before changing the single line the
user pointed at.
If the user asks to move only the arrow or only the block, obey that constraint
literally. Do not compensate by silently moving the other element.
Preserve deliberate alignment contracts such as shared bottoms, shared centers,
and column-internal spacing whenever you resize or move one member of the set.
Before editing, classify the requested change explicitly as one of:
arrow-only
block-only
text-only
local sub-ensemble rebalance
Then edit only at that scope unless the user broadens it.
If the same local region attracts repeated complaints, stop doing line-by-line
nudges and rebalance the whole region in one pass before replying again.
Keep one editable SVG as the source of truth.
Re-render only after the SVG itself is clean.
GitHub-first guardrails
Use these rules whenever the SVG will be viewed on GitHub, in a README, or in a
blob/raw page:
Treat text overflow as a hard failure. If any title, label, body line, or callout
crosses a block edge in the target renderer, the SVG is not done.
Treat repeated user complaints about one SVG as evidence that the previous pass was
incomplete. Do a full regression sweep before responding again.
Treat browser rendering as the target, not only one local SVG engine.
Prefer conservative geometry over tight packing; GitHub/browser rendering is less
forgiving than local slide or DOCX export.
Use browser-safe font stacks first (Arial, Helvetica, sans-serif) unless the
document already relies on a guaranteed embedded font.
Keep decorative rules, dividers, and arrows out of text corridors. If a line comes
near a label, move the line, not the label.
Remove decorative rules entirely when they do not add structural meaning. Do not
preserve a horizontal lane line just because it existed in an earlier revision.
Keep a semantic vertical rhythm. Similar elements should use the same spacing
pattern between title, kicker, body, note, and the next section break.
Keep a semantic line-break rhythm too. Do not let one peer block use arbitrary
manual wraps while its siblings use balanced semantic phrases.
After moving or resizing blocks, recalculate arrow anchors from the final geometry.
Do not leave connector coordinates inherited from an older layout.
For repeated connectors, keep arrow placement symmetric across the row or column so
the figure reads as intentional rather than hand-adjusted.
Center connectors on the geometry they are meant to describe. A vertical flow arrow
should sit on the actual center axis of the card or lane, not on a stale inherited x.
Treat lane rules and section dividers as a family too. They should share a deliberate
start/end axis rather than drifting with each label width.
Prefer widening a badge, pill, or summary card before wrapping what is really one
short label or one atomic message. Use wrapping only when the content is genuinely
paragraph-like.
Treat one-line summary callouts as a special case. If a banner or flow summary was
intentionally designed as one atomic sentence, do not let later grid tightening
break it into two lines without an explicit semantic reason.
For multiline card copy, make the block tall enough for the wrapped text first.
Do not push a footer note, divider, or arrow closer just to preserve a fixed box
height.
If a block contains a title plus explanatory copy, reserve explicit top, middle,
and bottom zones. Do not hand-place each text line independently without a repeatable
vertical rhythm.
If a block contains a title, one or more code pills, and explanatory copy, treat
that as a stacked mixed-content card. Reserve explicit title, pill, body, and
bottom-padding zones before tuning line breaks.
Treat manual line breaks as part of the layout contract. Rewrap body and note copy
by meaning, not by whatever happened to fit at one intermediate width.
For a family of peer cards, choose one text structure on purpose: for example one
centered title plus two balanced body lines, or one title plus body plus note.
Do not mix one-line, two-line, and awkward broken phrases without semantic reason.
Reserve a real vertical gutter between body text and footer notes. If the last body
line visually touches the note below, the card height or note position is wrong even
if the text does not literally overlap.
Treat edge-touching as a defect class too. Adjacent cards, callouts, or side panels
should keep a visible gutter; “not overlapping” is not a sufficient quality bar.
Do not rely on implicit spacing between a numbered badge and the following title.
Reserve explicit horizontal gap in the geometry.
Do not keep long callouts on one line. Wrap them with tspan and increase the box
size before shrinking text.
Give legends and reading guides their own lane. Do not let a legend compete for the
same vertical band as the last row of cards.
If an error label or callout sits between a right-side card and a lower band, give
that label its own corridor and rebalance both bands together. Do not wedge it into
leftover space and hope the connector still reads cleanly.
Keep card titles aligned by family. If most peer blocks use centered titles, do not
leave one or two titles left-aligned without an explicit semantic reason.
When compacting a panel that contains inner cards, reduce the panel height and then
rebalance the inner cards as a family so the bottom gutter stays intentional.
If a bottom band contains several related elements, prefer rebalancing that whole
band instead of ratcheting one card up and down across many micro-fixes.
When a right column or side column is moved, move its dependent badges and connectors
by the same delta unless there is an explicit reason to break the column contract.
When a user asks for repeated micro-moves on the same connector, keep a strict log
of what was allowed to move so you do not accidentally drift nearby geometry.
If a connector was intentionally converted to pure horizontal or pure vertical, do
not reintroduce a diagonal unless the user asks for it or the semantic mapping fails.
Attach area labels to the area they name. If a section header describes a pastel
panel or grouped zone, place it inside that panel or flush with its edge so the
target region is obvious at first glance.
Attach connector labels to the connector they qualify. Labels like allocations
should read as annotations of a nearby edge, not as loose text in empty space.
Shorten labels like lane headers or section names before tightening letter spacing.
When two renderers disagree, prefer the layout with more whitespace.
AGILAB Workflow
Edit the canonical SVG under ../thales_agilab/docs/source.
Sync the mirrored SVG under agilab/docs/source when the page is public.
Validate the edited SVG as XML before rebuilding docs.
Check the .rst page that references the figure so path changes do not break
the published page.
Validate the rendered HTML page after publish instead of assuming the raw SVG
source path will exist on GitHub Pages.
AGILAB Validation
Parse the SVG locally with Python XML tooling if needed.
Before replying, perform a semantic sweep of:
all card titles
all card bodies/notes
all legends/callouts
all arrows and arrowheads
section labels and lane headers
Check body-to-note spacing inside every card, not only overflow at the card border.
Check that line breaks are semantically balanced across sibling cards instead of
looking random or width-driven.
Check gutters between neighboring panels and side callouts, not only strict overlap.
Check that arrows, lane rules, and labels still share the same axes after any grid
shift. Geometry drift in connectors is a first-class defect.
Check alignment contracts in the local region you touched: shared bottoms, shared
centers, shared column offsets, and family spacing should still hold after the edit.
Check that every area label still has an obvious target panel after any resize or
repositioning.
Check that edge labels still read as edge labels rather than free-floating text.
Check whether each divider or lane rule is still justified. If it no longer adds
meaning, remove it instead of polishing its alignment.
Check that the final edit still matches the exact move contract requested by the
user: for example move only the arrow, move only the block, or rebalance all.
Re-render the SVG and visually inspect every text-bearing block for overflow,
collisions, and clipped whitespace before pushing.
If the same figure has already drawn a repeated complaint, inspect the rendered
raster before replying; do not trust source coordinates alone.
Re-check any badge, banner, or summary card that was previously one line after any
global width or grid change. Do not assume it will survive a layout normalization.
Re-check mixed-content cards for title-to-pill, pill-to-body, and body-to-bottom
gutters after any resize.
If the user pointed out one concrete defect, verify the same defect does not remain
in sibling blocks before declaring the SVG fixed.
Confirm the figure is referenced from the expected .rst page.
For published docs, verify the embedding page such as architecture.html or
agi-core-architecture.html; Sphinx may publish figure assets under _images/.
For GitHub-facing SVGs, validate with at least two renderers when possible:
rsvg-convert plus a browser-adjacent renderer such as Quick Look (qlmanage) or
an actual browser screenshot workflow.
If the user points to a GitHub blob/raw URL, treat that observed rendering issue as
real even if a local renderer looks acceptable.
Priority order
eliminate overflow and collisions
fix the whole class of related defects, not just the line the user mentioned
remove overlap
clarify hierarchy
widen crowded blocks
increase text size
simplify wording when layout alone is not enough
add whitespace before trusting typography tweaks
keep section labels and divider rules on one shared visual axis
recompute connector geometry after every layout shift
Anti-patterns
Do not reply after fixing only the one line the user cited if adjacent blocks still
have the same defect class.
Do not solve GitHub overflow by shrinking text first when geometry can be widened,
rewrapped, or reflowed.
Do not leave arbitrary manual wraps in a diagram after resizing a block. Revisit
every edited phrase and choose deliberate semantic breaks.
Do not place legends, guides, or notes into leftover whitespace without checking
whether they visually collide with the main diagram bands.
Do not keep decorative lane rules by inertia. If the section header already reads
clearly without the rule, delete the rule.
Do not “solve” a local layout complaint by alternating block moves and arrow moves
without first deciding which element is actually allowed to change.
Do not move one card in a bottom or side band without checking the alignment promise
of the neighboring cards in that same band.
Do not answer “done” after a sequence of micro-moves unless you have verified that
the final state still respects the user's latest constraint.
Do not leave area labels floating far from the panel they describe.
Do not leave connector labels in ambiguous whitespace where they could refer to more
than one relation.
References
Read references/layout.md for the tuning checklist.
