git:20260808.9603034 to git:20260808.c24932f

---

name: visual-qa

description: "Run visual QA on lesson pages — exercise interactive components, capture screenshots, report findings. Use after UI changes or feature additions. Trigger: visual qa, check the ui, screenshot all pages, verify components, test the lessons visually, check glossary visuals."

metadata:

type: process

invocation: both

practice: null

---

# Visual QA

Verify that UI components render and behave correctly by exercising them and analyzing the evidence.

## General Check

Run the automated tool to exercise all components across all pages:

```bash

mise run visual-qa

```

This produces `.scratch/visual-qa/manifest.json` + screenshots per page. If it exits 0, all behavioral checks pass (tooltips appear, trays open, quizzes give feedback, SVGs render). If it exits 1, something is broken — read the manifest for which checks failed.

The tool is a *behavioral* check. It answers "does this work?" not "does this look right?"

## Feature-Specific Visual Review

After building or modifying a specific feature, run the tool with `--focus` to scope screenshots, then analyze those screenshots against the feature's design intent.

```bash

python tools/visual-qa.py --serve --focus glossary

```

Then load the screenshots and analyze. The analysis prompt should be tailored to what the feature is supposed to look and feel like.

### Glossary

Capture: `.scratch/visual-qa/*/glossary-hover.png`, `glossary-tray-term.png`, `glossary-tray-list.png`

Analyze for:

- **Hover tooltip**: Dark background, white text, positioned above the term with arrow pointing down. Text is readable (not clipped, not overflowing). Does not obscure the content the learner is reading.

- **Term underlines**: Dotted, muted color, subtle — noticeable but not distracting. Should NOT look like a hyperlink (no solid underline, no blue color on the text itself).

- **Tray (term view)**: Slides from right, 320px wide, shows term name as heading + definition as body text. "← All terms" link visible. × close button in top-right.

- **Tray (list view)**: All defined terms listed, clickable, no visual clutter. Title says "Glossary". Back button hidden.

- **Overall**: Terms blend into the lesson flow. A reader who ignores them sees normal prose. A reader who notices them can get help without context-switching.

### Quiz

Capture: `.scratch/visual-qa/*/quiz-initial.png`, `quiz-answered.png`

Analyze for:

- **Initial state**: Questions bold, options in bordered cards. All options same visual weight — no clue which is correct. Radio buttons visible.

- **After answer**: Selected answer highlighted green (correct) or red (incorrect). Correct answer always highlighted green. Explanation appears below with blue left-border callout. Source links present if specified.

- **Overall**: Clean, not gamified. Looks like a thoughtful knowledge check, not a game show.

### Progressive Reveal

Capture: `.scratch/visual-qa/*/reveal-step-*.png`

Analyze for:

- **Step 1**: Only one element visible. Clear call-to-action (Next button). "Step 1 of N" indicator.

- **Step N**: Each step adds exactly one element to the diagram. Previous elements remain. Arrows/connections appear between steps.

- **Controls**: Prev/Next buttons centered, step counter between them. Prev disabled on step 1.

- **Overall**: Builds the mental model incrementally. No step shows more than 5-9 elements total. Colors follow vocabulary (blue=primary, amber=metadata, green=data).

### Diagrams (SVG)

Capture: `.scratch/visual-qa/*/diagrams.png` or `full-page.png`

Analyze for:

- **Renders at all**: Non-blank, visible shapes and text.

- **Color vocabulary**: Blue for primary/input, amber for processing/metadata, green for output/data, gray for infrastructure. Consistent within the page.

- **Labels**: ON the diagram (inside or immediately adjacent to shapes), not in a separate legend.

- **Scale**: Fits within the lesson column width without horizontal scroll. Text readable at normal zoom.

- **Overall**: Teaches something. If removing it wouldn't hurt understanding, it shouldn't be there (coherence principle).

## When to Run

| Situation | What to do |

|-----------|-----------|

| Changed `assets/*.js` or `assets/*.css` | `mise run visual-qa` (full behavioral check) |

| Just built a new component | `--focus <component>` + analyze screenshots against the section above |

| Ran jargon skill on a lesson | `--focus glossary` + quick check terms aren't overloading the page |

| Before closing a visual ticket | Full check + analyze relevant screenshots |

| Routine health check | `mise run visual-qa` — if green, move on |

## What This Does NOT Do

- No pixel-diff regression (content changes constantly)

- No Lighthouse / accessibility audit (that's ticket 013)

- No cross-browser testing (static HTML, Chromium-only is fine)

- No aesthetic judgment from the tool itself — that's the agent's job when reading screenshots