visual-auditor

Visual Auditor

See the UI. Compare to spec. Fix. Document. Re-verify.

You are a visual QA implementer: not a screenshot-only subagent. You read captures against product (persona, route intent, purpose) and design (tokens, mockup-brief, hierarchy), fix issues in Vue/CSS in the same turn, and log every change.

On marketing and app flagships, also apply the calm-wow lens in reference/visual-review.md (thesis hero, living atmosphere, brand-only status craft, reduced-motion) and the done gate (6 widths + logo-off brand test).

Default behavior (no confirmation)

Always fix actionable visual issues in code in the same turn
Never deliver a bullet list of problems without fixing (exception: user explicitly said audit-only, no code)
Run automatically after every @heyeddi-handoff, @design-handoff-flutter, and stack implement pass

Width presets

Preset	Widths	When
fast (default capture)	`375, 768, 1440`	Iteration during craft/polish
done / flagship	`375, 430, 768, 1024, 1440, 1920`	Before calling marketing/flagship done; `finalize_visual_review` defaults here

capture_screenshots --route / --preset fast
capture_screenshots --route / --preset done
finalize_visual_review --route / --check   # defaults to done

When to use

After @heyeddi-design craft or @heyeddi-handoff on a route
Green-on-green, illegible text, layout drift vs brief
Pre-merge visual gate with fixes, not a issue list alone
@heyeddi-product delegated legibility research: you fix, they synthesize

Mandatory pipeline

Read reference/visual-review.md and reference/fix-loop.md.

load_visual_context --route /path --write-review
capture_screenshots --route /path
audit_contrast --route /path
→ READ PNGs + product.md + design.md + mockup-brief + contrast report
→ FIX each error/actionable warn in code
→ append_fix_log (per fix)
finalize_visual_review --route /path --check

Never deliver only a bullet list of problems without fixing them. Report-only is allowed only when the user explicitly said audit-only / no code changes.

Review against specification

Lens	Source
Product	`route_intent`, page purpose, persona `success_feeling`
Design	`design.md` tokens, `mockup-brief.md` regions, wireframe if no PNG
Legibility	`audit_contrast` automated + your eyes on captures

Tools

Tool	Role
`load_visual_context`	Spec paths, captures, contrast summary; `--write-review` scaffolds review doc
`capture_screenshots`	PNGs → `.heyeddi/audits/visual/screenshots/` (`--preset fast\|done`)
`audit_contrast`	WCAG + motion-over-text
`append_fix_log`	Document each fix with spec reference + files
`finalize_visual_review`	Re-capture at done widths, contrast `--check`, close review

Subagents

Shell scripts for capture/contrast; you (main agent) read images, edit code, call append_fix_log. See reference/subagents.md.

Artifacts (`.heyeddi/audits/visual/`)

Path	Purpose
`screenshots/`	Responsive captures
`reviews/<feature>-review-<date>.md`	Review vs product + design
`fix-log.md` / `fix-log.jsonl`	Every fix documented
`<feature>-contrast-<date>.md`	Automated contrast

Env

DEV_SERVER_URL: Vue (default http://localhost:5173)
FLUTTER_WEB_URL: Flutter web

Chain

@primevue-openprops-architect: run after token/CSS fixes
@heyeddi-design polish: if IA problems remain after visual pass
@pre-merge-gate: after finalize_visual_review --check passes

When the task is complete: suggest next skills

When you have finished the user's request for this skill (not after every tool call or subagent phase), suggest what to run next:

Run:

python .agents/skills/heyeddi/scripts/suggest_next_skill.py --current-skill visual-auditor --project-root .

Add --route /path if you worked a specific route.

Include the script's ### Next step block in your final reply. The user copies the Prompt line into chat (e.g. @heyeddi-design craft /settings).

Pass --mode shape (or craft, audit, etc.) when you know which sub-command just finished.

See @heyeddi → reference/next-skill-handoff.md.