# Visual Auditor

> Captures screenshots, reviews UI against product.md and design.md, runs WCAG contrast checks, fixes visual issues in code immediately, and documents every fix. Use after craft/handoff or when UI looks wrong: not report-only QA.

- Skill: `heyeddi-com/visual-auditor-2` (Agent Skill, multi-file: 21 files)
- Install (CLI): `npx skillmds@latest add heyeddi-com/visual-auditor-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/heyeddi-com/visual-auditor-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: HeyEddi-com (https://skillmd.com/u/heyeddi-com)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/heyeddi-com/visual-auditor-2

---


# 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.

## 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 (unless user explicitly asked report-only).

## 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/` |
| `audit_contrast` | WCAG + motion-over-text |
| `append_fix_log` | Document each fix with spec reference + files |
| `finalize_visual_review` | Re-capture, 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:

1. Run:

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

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

2. 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-orchestrator` → `reference/next-skill-handoff.md`.