Bmad qa visual review

QA Visual Review Workflow

Goal: Verify the implemented UI matches its design intent by driving a real browser into the running app, capturing the screen, and grading it against the mockup — layout, components, hierarchy, labels/i18n, and responsive behaviour.

Your Role: You are a QA engineer doing visual / UX acceptance. You do NOT write feature code here. You capture, compare, and report. Code fixes are handed back to bmad-dev-story; automated test generation is bmad-qa-generate-e2e-tests; adversarial code review is bmad-code-review.

This skill complements them: it is the only QA layer that looks at the rendered pixels, not the source.

Conventions

• Bare paths (e.g. checklist.md) resolve from the skill root.
• {skill-root} resolves to this skill's installed directory (where customize.toml lives).
• {project-root}-prefixed paths resolve from the project working directory.
• {skill-name} resolves to the skill directory's basename.

On Activation

Step 1: Resolve the Workflow Block

Run: python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow

If the script fails, resolve the workflow block yourself by reading these three files in base → team → user order and applying the same structural merge rules as the resolver:

1. {skill-root}/customize.toml — defaults
2. {project-root}/_bmad/custom/{skill-name}.toml — team overrides
3. {project-root}/_bmad/custom/{skill-name}.user.toml — personal overrides

Any missing file is skipped. Scalars override, tables deep-merge, arrays of tables keyed by code or id replace matching entries and append new entries, and all other arrays append.

Step 2: Execute Prepend Steps

Execute each entry in {workflow.activation_steps_prepend} in order before proceeding.

Step 3: Load Persistent Facts

Treat every entry in {workflow.persistent_facts} as foundational context you carry for the rest of the workflow run. Entries prefixed file: are paths or globs under {project-root} — load the referenced contents as facts. All other entries are facts verbatim.

Step 4: Load Config

Load config from {project-root}/_bmad/bmm/config.yaml and resolve:

• project_name, user_name
• communication_language, document_output_language
• implementation_artifacts
• project_knowledge (where docs/mockups/ lives)
• date as system-generated current datetime
• YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config {communication_language}

Also load the Visual QC environment defaults from {project-root}/_bmad/scripts/visualqc/visual-qc.config.json (base_url, db, login, viewports). These can be overridden per run.

Step 5: Greet the User

Greet {user_name}, speaking in {communication_language}.

Step 6: Execute Append Steps

Execute each entry in {workflow.activation_steps_append} in order.

Activation is complete. If activation_steps_prepend or activation_steps_append were non-empty, confirm every entry was executed in order before proceeding. Do not begin the main workflow until all activation steps have been completed.

Paths

• engine = {project-root}/_bmad/scripts/visualqc/capture.cjs
• config_template = {project-root}/_bmad/scripts/visualqc/visual-qc.config.json
• mockups_dir = {project_knowledge}/mockups
• default_output_dir = {implementation_artifacts}/visual-qc/{feature-slug}
• default_output_file = {default_output_dir}/visual-qc-report.md

Execution

Step 0: Pre-flight — environment is reachable

1. Confirm the app is up: the base_url from the config responds (e.g. curl -s -o /dev/null -w "%{http_code}" {base_url}/web/login → 200). If not, tell the user to start the stack (docker compose up -d) and stop.
2. Confirm {engine} exists and its node_modules/puppeteer-core is present. If node_modules is missing, run npm install once inside {project-root}/_bmad/scripts/visualqc.
3. Access rights: the capture user must belong to the feature's security groups, or the live page will render an Access Error dialog instead of the feature. If you expect that risk, note it; the captured screenshot will make it obvious.

Step 1: Scope the Feature & Locate the Mockup

Ask the user (or infer from the active story / docs/epics.md):

• Which feature/screen is under QC (e.g. "Warranty Claim form").
• Which mockup is the source of truth. List candidates in {mockups_dir}; match by name. If no mockup exists, ask whether to grade against the UX spec (docs/ux.md) / SRS instead, or to stop.
• Which screens to capture: list view, new (blank) form, a saved record, kanban, etc.

Step 2: Resolve Target URLs

Odoo screens are reached by action. Build each path as /odoo/action-<id-or-xmlid> with an optional suffix:

• list/default → /odoo/action-<ref>
• blank create form → /odoo/action-<ref>/new
• a specific record → /odoo/action-<ref>/<res_id>

Find the action's xmlid by grepping the module's views for ir.actions.act_window (e.g. grep -rn "act_window" addons/<module>/views). Prefer the xmlid form (module.action_name) — it is stable across rebuilds. To screenshot a saved record, pick a real res_id (query the DB or open the list first).

Step 3: Write the Capture Job & Run the Engine

Write a job JSON (copy {config_template}) to {default_output_dir}/job.json describing the targets, then run:

node {engine} --config {default_output_dir}/job.json

For a single quick screen you may skip the file and pass inline flags: node {engine} --base <url> --db <db> --login <user> --password <pw> --out <dir> --name <slug> --path <odoo-path> --mockup <mockup.html>

The engine authenticates, captures each target at every viewport (default desktop 1440×900 + mobile 390×844), renders the mockup to PNG, and writes manifest.json + a side-by-side compare.html into the output dir.

Step 4: Look at the Screens

For each target, Read the produced PNGs — *__app__*.png (actual) and *__mockup__*.png (expected). You can see images via the Read tool. Examine them side by side. Also re-read the mockup HTML and the UX spec for any intent the static image doesn't convey (interactions, states, conditional fields).

Step 5: Grade Against the Rubric

For every screen, evaluate each dimension and mark Match / Minor / Major / Missing:

1. Layout & structure — overall regions present and in the right place (statusbar, smart buttons, sheet, group columns, tabs/notebook, chatter).
2. Components present — every field, button, badge, tab from the mockup exists on screen (account for fields that are conditional/computed and only appear after save — verify on the saved-record capture, not the blank form).
3. Visual hierarchy — title prominence, field grouping (left/right columns), tab grouping, emphasis match the mockup.
4. Labels & i18n — field labels, button text, menu names match the mockup and are correctly translated per {document_output_language}. Flag English leaking into a Vietnamese UI (or vice-versa).
5. States — status bar stages, badges (e.g. "In Warranty"), required-field markers render as designed.
6. Responsive — the mobile capture is usable: no overflow, columns collapse sensibly, nothing clipped.
7. Polish — alignment, spacing, obvious broken styling, error dialogs, empty smart buttons that should be hidden.

Distinguish legitimate differences (a blank new form naturally lacks computed fields, smart buttons, and the record name) from real defects. Do not report expected-empty-state diffs as bugs.

Step 6: Write the Report

Save a markdown report to {default_output_file} in {communication_language}:

# Visual QC Report — <Feature>

**Date:** <date> · **App:** <base_url> · **Mockup:** <mockup file>
**Screens captured:** <list> · **Artifacts:** ./compare.html, ./manifest.json

## Verdict
<PASS / PASS WITH NITS / FAIL> — one-line summary.

## Screen: <name> (<viewport>)
| Dimension | Status | Notes |
|---|---|---|
| Layout & structure | Match | |
| Components present | Major | `SLA Deadline` field missing from form |
| Visual hierarchy | Minor | right column starts lower than mockup |
| Labels & i18n | Match | |
| States | Match | |
| Responsive | Minor | tab labels wrap on mobile |
| Polish | Match | |

**Screenshots:** `<name>__app__desktop.png` vs `<name>__mockup__desktop.png`

## Findings (actionable)
1. **[Major]** <what is wrong> — expected (mockup) vs actual (app). Suggested owner: dev-story.
2. **[Minor]** ...

## Out-of-scope / expected differences
- Blank `new` form lacks computed `In Warranty` badge and smart buttons (appear after save) — not a defect.

Reference each finding to a screenshot so the reader can verify.

Keep It Simple

Do:

• Capture the real rendered page; never grade from source code alone.
• Compare against the mockup that is the agreed source of truth.
• Separate real defects from expected empty-state differences.
• Keep findings actionable and tied to a screenshot.

Avoid:

• Pixel-perfect nitpicking of anti-aliasing or 1px shifts.
• Re-reviewing business logic / code (that's bmad-code-review).
• Inventing requirements the mockup/SRS doesn't state.

Output

Save report to: {default_output_file}. Leave compare.html, manifest.json, and all PNGs alongside it.

Done! Validate against ./checklist.md, then summarise the verdict and top findings to the user in {communication_language}.

On Complete

Run: python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow.on_complete

If the resolved workflow.on_complete is non-empty, follow it as the final terminal instruction before exiting.