design-visual-qa

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               # api_only=true → no UI to QA; stop
ls spec/system test/system 2>/dev/null                  # where UI tests live (framework: spec/=RSpec, test/=Minitest)
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  # current driver
ls test/components spec/components 2>/dev/null          # component tests present
ls tmp/screenshots doc/screenshots spec/**/__snapshots__ 2>/dev/null   # existing screenshot baselines
grep -E "tailwindcss|cssbundling" Gemfile.lock 2>/dev/null   # CSS stack — visual baselines inherit fonts/theme from ../design-foundations/

• 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

Task	Read
System tests for Turbo/Stimulus UI flows (frames, streams, modals, forms)	references/system-tests-ui.md
Visual regression: screenshot baselines, diffing, taming flakiness	references/visual-regression.md
Gating accessibility (axe) in the suite / CI	references/accessibility-tests.md
Reviewing components in Lookbook + screenshotting previews	references/lookbook-review.md

Verify

Visual QA is "set up" once the suite drives the real UI, matches its baseline, and gates a11y — all green in CI:

# The UI/system suite runs green (Turbo flows + axe assertions):
bin/rails test test/system 2>/dev/null || bundle exec rspec spec/system
# Screenshots/baselines exist and diff (built-in or SaaS):
ls tmp/screenshots 2>/dev/null && echo "✓ screenshots captured"
# Prove the gates bite: break a page (drop a label / shift a layout) → the axe assertion
# or the screenshot diff should FAIL. A guardrail you haven't seen fail isn't a guardrail.

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.