| name | visual-acceptance-review |
| description | This skill should be used after spec-compliance-review and before
visual-diff-fix. It captures or analyzes actual browser screenshots and
compares them against the reference design, responsive spec, visual tokens,
layout spec, component tree, UI type, layout paradigm, and asset strategy.
It outputs structured visual diff reports and fix-tasks without modifying code.
|
| argument-hint | [dev-server-url-or-actual-screenshot] |
Version: 2.0.0
visual-acceptance-review
Validate real browser rendering against the approved visual contract.
This skill performs screenshot-based visual acceptance and produces structured fix tasks.
It does not modify code.
It does not redesign UI.
It does not replace spec-compliance-review.
Trigger Conditions
Use this skill when:
- implementation exists
- spec-compliance-review has passed or user requests diagnostic-only review
- a dev server URL is available
- Playwright or screenshot capability is available
- user asks to compare implementation against reference image
- user asks for visual acceptance report or visual diff tasks
Required Inputs
reference.png- dev server URL or actual screenshot
- UI workflow files under
ui/03_visual_spec/
- visual spec review files under
ui/04_visual_spec_review/
- design system files under
ui/05_design_system/
Recommended:
- spec compliance outputs under
ui/06_spec_review/
package.jsonplaywright.config.*
Preflight Gates
Stop if:
ui/04_visual_spec_review/spec-review-report.md says Failui/06_spec_review/compliance-report.md says Fail, unless user explicitly requests diagnostic-only mode- no screenshot capability exists and no actual screenshot is provided
Source of Truth
reference.png- actual browser screenshot
visual-analysis.md / UI Type Classificationlayout-spec.md / Layout Paradigmimplementation-risks.md / Asset Strategycomponent-tree.mdtokens.jsonresponsive-spec.md05_design_system/- browser health logs
Main Workflow
- Run preflight gates.
- Capture or load screenshots.
- Compare overall visual match.
- Validate UI Type, Layout Paradigm, and Asset Strategy.
- Compare regions using layout-spec.md.
- Compare components using component-tree.md.
- Compare colors, typography, spacing, and density.
- Validate responsive screenshots against responsive-spec.md.
- Capture browser health issues.
- Generate reports and
fix-tasks.json.
Hard Rules
- Do not modify code.
- Do not modify visual spec files.
- Do not modify design system files.
- Do not modify OpenSpec files.
- Do not redesign UI.
- Do not claim pixel-precision if no script-backed comparison exists.
- Do not compare mobile/tablet directly against desktop reference.png.
- Do not allow actual rendering to change UI Type, Layout Paradigm, or Asset Strategy.
- Do not treat passing tests as visual acceptance.
- Do not treat internal spec consistency as visual acceptance.
- If a photorealistic/panorama/scene-led main visual is missing or redrawn with CSS/SVG/chart/map, mark as Fail.
Output
Write:
07_validation/visual_acceptance/
screenshots/
reference.png
actual-desktop-hd.png
actual-desktop.png
actual-tablet.png
actual-mobile.png
comparison-report.md
acceptance-summary.md
fix-tasks.json
region-diffs/
overview.md
layout.md
components.md
colors.md
typography.md
spacing.md
responsive.md
asset-strategy.md
browser-health.md
console-errors.log
network-errors.log
blocked-report.md
blocked-report.md is only required when preflight blocks the review.
Supporting Files
Read these references directly:
references/acceptance-workflow.mdreferences/preflight-gates.mdreferences/screenshot-rules.mdreferences/comparison-rules.mdreferences/ui-type-asset-validation.mdreferences/confidence-rules.mdreferences/fix-task-schema.mdreferences/external-reviewer-usage.mdreferences/output-files.md
Examples:
examples/acceptance-summary.example.mdexamples/comparison-report.example.mdexamples/region-diff.example.mdexamples/fix-tasks.example.jsonexamples/blocked-report.example.md
