Svg Audit

svg-audit

Find what is wrong with an SVG or an animated scene, rank it by how much it hurts, and say exactly how to fix each item. Default mode is read-only: print the report and stop. Apply fixes only when the user asks ("fix it", "--fix", "apply").

1. Identify the artifact and its target

Ask only if the target cannot be inferred from where the file lives or how it is referenced (grep the repo for its filename).

The references above live in the sibling animated-svg and motion-scene skills of the svg-forge plugin; this skill reads them, so install the plugin, not this folder alone.

2. Run the validator (SVG files)

bashCopy code
python skills/animated-svg/scripts/validate_svg.py path/to/file.svg --target standalone --strict-contrast --json

Use --target web for inline page SVGs. For one half of a <picture> pair add --theme dark or --theme light; otherwise text with no background of its own is measured on both GitHub pages. Every error is a finding. Warnings become findings when they matter for the target. Quote rule ids (SV0xx) so the user can look them up; SV021-SV023 are WCAG contrast (text 4.5:1, large text and solid shapes 3:1), with each measurement under stats.contrast.

Then render the timeline so motion findings rest on frames, not guesses:

bashCopy code
python skills/animated-svg/scripts/frames.py path/to/file.svg --theme both

Read the PNG contact sheet it writes: entrances, overlaps, labels that are hidden at rest, and whether the seam frame matches t=0. Exit 3 means no browser was found; say so in the report instead of guessing.

For a scene component, there is no validator: read the component and its helpers instead, and apply the checks in section 3.

3. Review what the validator cannot see

Work through each lens and record findings with a file and line.

Render-target safety

• Standalone: anything that needs network, script, or an HTML context fails silently on GitHub. External fonts fall back to system fonts, so check text still fits.
• Dark and light: text needs 4.5:1 and marks 3:1 on both GitHub themes (the validator measures this), or the file must ship as a <picture> pair. In-SVG prefers-color-scheme does not follow GitHub's theme and fails on WebKit. For a fix, regenerate with forge.py --theme both or a preset; it tunes every color to pass.
• Paint order: a far edge showing through a near panel, a wire crossing the face of the panel it should end at, a dashed guide over its own plate. The fix is order and an opaque fill, not a mask.
• Browser quirks: SMIL path morphs are the only morphs Safari plays; calcMode misspelled (calcmod) silently drops keySplines; pathLength together with vector-effect="non-scaling-stroke" stops line draws short in Chrome.

Motion quality

• Rest frame: read the static attributes as the first frame and judge it as the thumbnail. A flat grid, an empty tray or every element at opacity="0" fails; so does a rest that looks like nothing rendered yet.
• One highlight: one bright mark at rest; a beat moves it, never adds a second. Two lit places at once is a finding.
• Loop shape: a loop that opens on an empty stage leaves a half-built poster and frozen frame; opening on the finished state with a clear window, or a static ghost layer under the build-up, is the fix.
• A state change: at least one beat decides something (a row rejected, a check popped, a slot filled); motion with nothing decided is a polish finding.
• One clock: beats in a loop should share one duration so they never drift apart.
• Seamless loop: the last keyframe equals the first, or the restart happens while the element is invisible.
• Easing: multi-keyframe animations need per-segment easing (keySplines per segment, or an ease array in Motion when times is set).
• Budget: count animated elements; more than about 12 in one scene, or 40 in one file, reads as noise and costs CPU.
• Only transform and opacity (plus stroke dash properties for line draws) should animate in scenes.

Accessibility

• Meaningful graphic: role="img" plus <title> (and <desc> when it carries information) referenced by aria-labelledby, or alt text on the <img>.
• Decorative graphic: aria-hidden="true" (inline) or empty alt (image).
• Auto-playing motion longer than 5 s has no pause control inside an image: note it, do not block on it.

Weight and hygiene

• Size against the budget for the target (standalone: aim under 50 KB, hard stop 100 KB unless the user accepts more). python skills/animated-svg/scripts/optimize_svg.py FILE --check reports what an animation-safe minify would save without writing anything.
• Embedded rasters at more than twice their drawn size, unused <defs>, duplicated paths that could be <use>.
• Ids prefixed and unique when the file inlines icons or may be inlined into a page.
• Deterministic output if the file is generated: same input, same bytes.

4. Report

Print a table ranked by severity, then a short verdict.

Copy code
| # | severity | where | finding | fix |
| 1 | error    | card.svg:12 | <image href="https://..."> is blocked by GitHub's image proxy | inline it as a data URI under 64 KB, or drop it |
| 2 | warn     | card.svg:40 | 6 s loop with beats on 4 s and 6 s clocks drifts | put every beat on the 6 s clock |
verdict: renders on GitHub after fix 1; 2 is polish.

Severity: error (does not render or is unsafe), warn (renders but looks wrong somewhere or hurts access), polish (quality).

5. Fix mode (only when asked)

• Apply fixes in severity order, one finding at a time, keeping unrelated markup byte-identical.
• Re-run the validator after each change; the report's errors must reach zero.
• For generated files, fix the generator or its input, not the output.
• Show the diff and the new validator result.