| name | svg-check |
| description | Apply when editing, generating, or reviewing any SVG diagram. Pixel-perfect Playwright bbox-check is the acceptance test — eyeballing is not sufficient. Run on every SVG before declaring done. |
| license | MIT |
| version | 1.0.0 |
| tokens_target | 1800 |
| triggers | ["svg edit","svg review","diagram","pixel review","svg overflow"] |
| loads_after | [] |
| supersedes | [] |
Sub-Skill: SVG Check
Purpose. Catch text-overflow and foreign-rect-intersection bugs in SVG diagrams before commit. LLM eyeball review at 4× zoom misses these bug classes consistently — measurement is the only reliable test.
The acceptance test is the script output. Not your visual judgment.
When to apply
Apply this skill whenever:
- you are editing an existing SVG (
*.svg in any docs/diagrams folder),
- you are producing a new SVG from scratch,
- a designer agent reports an SVG as "clean" — verify with the script,
- you are reviewing a PR that touches
*.svg.
The two bug classes the script catches
-
OVERFLOW (own-container): a <text> whose rendered bbox extends past the bounds of its containing <rect> (in the same <g>). Caught by getBBox() measurement, tolerance 2 px.
-
FOREIGN-RECT INTERSECT: a <text> whose viewport bbox intersects a <rect> that is not an ancestor of the text — i.e. a tagline ascender that touches a structural box above/below it. Caught by getBoundingClientRect() intersection, tolerance 2 px.
Both classes filter false-positives: rects smaller than 40 × 18 (legend swatches) are not treated as containers; texts that start more than 5 px outside a rect's horizontal range are not treated as contained.
How to run
The script lives next to this file: overflow-check.js. It needs Playwright installed once per machine.
One-time setup
cd skills/svg-check
bash setup.sh
Or manually:
npm install playwright
npx playwright install chromium --with-deps
Run on one SVG
node skills/svg-check/overflow-check.js path/to/diagram.svg
Run on all SVGs in a folder
for svg in path/to/*.svg; do
out=$(node skills/svg-check/overflow-check.js "$svg" 2>&1)
if echo "$out" | grep -q "FOUND"; then
echo "FAIL: $svg"; echo "$out" | grep -E "FOUND| \[| \""
fi
done
The script exits non-zero when issues are found — suitable for use as a pre-commit gate or CI step.
Acceptance criteria
The script output must contain both of these lines, verbatim, for every SVG in scope:
OVERFLOW: CLEAN — 0 text overflows past their containing rect
FOREIGN-RECT INTERSECT: CLEAN — 0 text-vs-foreign-rect intersections
Anything else means not done. Fix the SVG (shorten text, widen rect, move element, change font-size) and re-run until both lines are CLEAN.
In addition, after the script is CLEAN, render a Playwright screenshot in light + dark mode and visually cross-check for bug classes the script does not cover (see § Limits below).
How to fix common overflow patterns
| Pattern | Fix |
|---|
| Mono-tag text wider than its 200 px box | Move trailing content to a mono-dim line below, or drop the suffix entirely. Match the sibling-box pattern. |
| Tagline ascenders touch the rect above | Extend the SVG viewBox height (500 → 520) and move the tagline down. Other elements stay put. |
| Two-line label tight in a folder glyph | Move from y=22/33 to y=21/34 (13 px line-height instead of 11 px). |
| Annotation text overflowing a chip | Either widen the chip rect or shorten the annotation. Do not suppress the script — fix the SVG. |
Examples
See EXAMPLES.md for real before/after fixes with script output.
Limits — what the script does NOT catch
These remain eyeball-only for now. When a missed bug class surfaces, extend the script with a new check class — do not rely on agent self-reporting.
- Text-vs-line overlaps: a
<text> crossing an <line> arrow.
- ≥12 px clearance between text-baseline and the nearest line below it.
- Sibling text overlaps: two
<text> elements at the same coords.
- Color contrast ratio in dark mode.
- Glyph render quality at small sizes (≤ 10 px).
Why this skill exists (incident history)
- 2026-05-11 #1: a four-designer parallel review declared
architecture.svg clean. The GEMINI CLI loader-tag overflowed its 200 px box by 42.6 px. No agent measured.
- 2026-05-11 #2: a follow-up three-cycle eyeball review missed that the tagline ascenders intruded into the folder-strip border above. The fix was a 20 px viewBox extension; the bug was a 2 px overlap that the agents could not detect by sight.
The script was built after the second miss. It catches both bug classes in under 5 seconds.
The rule that follows from these incidents: don't trust agent self-reports of "no issues at 4× zoom". Trust the measurement.
Required output for "done"
When reporting work on any SVG, paste the script output verbatim — both before the fix (showing the bug) and after the fix (showing CLEAN). Without that paste, the work is not done.
