| name | design-visual-qa |
| description | Prove the UI of a full-stack Rails 8.1 Hotwire app actually works — system tests that exercise the rendered Turbo/Stimulus flows, visual-regression screenshots to catch unintended visual changes, automated accessibility checks (axe) wired into the suite, and Lookbook-based component review. Menu-driven with a Recommended default per menu (Selenium/headless Chrome driver, built-in screenshot diffing, axe-core a11y assertions). Owns the visual/UX assertions; the test stack itself — framework, driver, CI — is owned by rails-testing, and the a11y rules by design-accessibility. Detects the installed test framework and driver first, then verifies the UI renders, matches its baseline, and is accessible. Apply when testing UI flows, catching visual regressions, or gating a11y in CI. Web apps only. |
| metadata | {"owner":"rails-design","status":"stable"} |
| user-invocable | true |
| argument-hint | [flow-or-component] |
design-visual-qa
Purpose
Owns the visual and UX assertions that keep the design from regressing: Capybara
system tests that drive the real rendered Turbo/Stimulus flows (modals, inline edit,
streams), visual-regression screenshots that flag unintended pixel changes,
accessibility assertions (axe) wired into the suite as a gate, and Lookbook
component review. It sits on top of the test stack that ../rails-testing/ owns (the
framework, driver, fixtures/factories, CI) and the a11y rules that
../design-accessibility/ owns — it adds the visual layer of QA, and routes to those
skills for the parts they own rather than re-documenting them.
When to Apply
Use this skill when the task is:
- Writing system tests for a UI flow (a Turbo Frame/Stream interaction, a form, a modal)
- Setting up visual-regression (screenshot baselines + diffing)
- Gating accessibility in CI (axe assertions on key pages/states)
- Reviewing components in Lookbook as a QA surface
- Catching layout shift / responsive breakage before it ships
Do not use this skill when the task is:
- The test framework / driver / CI setup (Minitest vs RSpec, Selenium vs Cuprite, fixtures/factories) → read
../rails-testing/SKILL.md
- The a11y rules being asserted (WCAG, ARIA, the axe gem setup) → read
../design-accessibility/SKILL.md (this skill gates them; that one defines them)
- Building the components/flows under test → read
../design-components/SKILL.md · ../design-interactions/SKILL.md
- Model/request (non-UI) tests → read
../rails-testing/SKILL.md
- An API-only app — no visual UI to QA
Detect Before You Generate
grep -nE "api_only" config/application.rb
ls spec/system test/system 2>/dev/null
grep -E "capybara|selenium-webdriver|cuprite|axe-core|percy|capybara-screenshot|lookbook" Gemfile.lock 2>/dev/null
grep -rnE "driven_by|Capybara.javascript_driver" test/application_system_test_case.rb spec/ 2>/dev/null
ls test/components spec/components 2>/dev/null
ls tmp/screenshots doc/screenshots spec/**/__snapshots__ 2>/dev/null
grep -E "tailwindcss|cssbundling" Gemfile.lock 2>/dev/null
- Use the framework and driver already configured (
../rails-testing/). spec/system
→ RSpec; test/system → Minitest. A JS driver (Selenium/Cuprite) is required —
Turbo/Stimulus and axe don't run under rack_test.
- If
axe-core-* is installed, extend the existing a11y assertions
(../design-accessibility/references/axe-system-tests.md owns the setup).
- Detect existing screenshot baselines before adding a regression tool.
Menu
Three menus via AskUserQuestion; defaults marked Recommended. Defer to
../rails-testing/ if the driver is already chosen.
System-test driver (usually already set by ../rails-testing/)
| Option | One-line trade-off | Deep dive |
|---|
| Selenium + Chrome (headless) (Recommended) | Rails default driver; real browser, exercises Turbo/Stimulus + axe; broad compatibility. | system-tests-ui.md |
| Cuprite (CDP) | Drives headless Chrome over CDP — no Selenium binaries, fast, great screenshots. | system-tests-ui.md |
Visual regression
| Option | One-line trade-off | Deep dive |
|---|
| Built-in screenshot diffing (Recommended) | Capybara save_screenshot / capybara-screenshot baselines diffed in CI; free, in-repo, you own the noise. | visual-regression.md |
| Percy / Chromatic (SaaS) | Hosted diffing with review UI + cross-browser; polished, paid, external dependency. | visual-regression.md |
| None | Rely on system tests + manual review; lightest, misses silent visual drift. | visual-regression.md |
Accessibility automation
| Option | One-line trade-off | Deep dive |
|---|
| axe-core in system tests (Recommended) | Assert zero axe violations on key pages/states as part of the suite; fails CI on regressions. | accessibility-tests.md |
| None | Manual a11y only; no automated guardrail (not advised). | accessibility-tests.md |
Decision Flow
- Driver: use whatever
../rails-testing/ configured — Selenium by default,
Cuprite if the app wants speed/no-driver-binaries. Either runs Turbo, axe, and
screenshots; rack_test does not.
- System tests first. The highest-value QA is a handful of system tests over the
critical journeys (sign-up, the core task, an inline edit, a modal flow). Keep the
pyramid: a few high-value UI tests, not hundreds of brittle ones.
- Visual regression: start with built-in screenshot diffing for key
pages/components — it's free and in-repo; tame flakiness by masking dynamic regions and
pinning viewport/fonts. Move to Percy/Chromatic when you need a review UI and
cross-browser coverage and will pay for it. None is acceptable for small apps that
rely on manual review — but say so.
- A11y gate: wire axe-core assertions into the suite (setup owned by
../design-accessibility/) and drive the UI into each state (modal open, form invalid)
before asserting — that's where regressions hide.
- Lookbook is the manual review surface: scan every component's states in one place;
pair it with screenshot diffing of the previews (lookbook-review.md).
Problem → Reference
Verify
Visual QA is "set up" once the suite drives the real UI, matches its baseline, and gates
a11y — all green in CI:
bin/rails test test/system 2>/dev/null || bundle exec rspec spec/system
ls tmp/screenshots 2>/dev/null && echo "✓ screenshots captured"
Run the suite in CI via ../rails-testing/ so visual + a11y regressions block merges.
Route to ../design-accessibility/ for the axe setup and ../design-components/ for the
Lookbook previews this skill reviews.
