arn-spark-visual-strategy

Arness Visual Strategy

Set up automated visual regression testing so that during feature development, each implemented screen can be compared pixel-by-pixel against the approved prototype screenshots. The prototype screenshots serve as baseline images — the "gold standard" of what the UI should look like. As features are built, capture scripts take screenshots of the development build and comparison scripts diff them against these baselines, catching layout breaks, color mismatches, and misplaced elements before they reach the user.

This is a conversational skill that runs in normal conversation (NOT plan mode). It uses the arn-spark-visual-test-engineer agent for proof-of-concept validation and script generation.

The primary artifacts are:

• Capture script — takes screenshots of the development build (NOT the prototype)
• Comparison script — diffs development screenshots against prototype baselines
• Baseline images — copied from prototype screenshots, used as the reference standard
• CLAUDE.md configuration — integrates visual testing into the Arness execution pipeline so that /arn-code-execute-plan and /arn-code-execute-task automatically validate UI changes

The core problem this solves: during feature development, visual regressions (button on the wrong side, layout breaks, color mismatches) go undetected until the user manually inspects the application. This skill sets up the tooling so that every UI task automatically compares the development build against the prototype.

Prerequisites

Read the project's CLAUDE.md for a ## Arness section. If no ## Arness section exists or Arness Spark fields are missing, inform the user: "Arness Spark is not configured for this project yet. Run /arn-brainstorming to get started — it will set everything up automatically." Do not proceed without it.

Extract:

• Vision directory (default: .arness/vision)
• Prototypes directory (default: .arness/prototypes)
• Spikes directory (default: .arness/spikes) -- for mini-spike workspaces
• Git / Platform

Check for prototype lock (strongly recommended):

1. Check for ### Prototype Lock in the ## Arness section
2. If found: read the locked directory path and the LOCKED.md manifest
3. If NOT found: warn the user -- "No prototype lock detected. Visual testing compares against the prototype, but the prototype is not currently protected from modification. Consider running /arn-spark-prototype-lock first."

Check for prototype validation evidence:

• [prototypes-dir]/clickable/final-report.md
• [prototypes-dir]/static/final-report.md
• Scan for showcase screenshots: [prototypes-dir]/clickable/v[N]/showcase/screens/, journey screenshots, static showcase screenshots

Check for architecture vision (required for stack analysis):

• Read architecture-vision.md for framework, application type, platform targets

Check for dev-setup document (for environment constraints):

• Read dev-setup.md for development environment type, platforms, and CI configuration

If no architecture vision: "No architecture vision found. Describe your technology stack and target platforms so I can design a visual testing strategy."

If no prototype screenshots: "No prototype screenshots found. Visual testing needs reference images. Either run the prototype skills first, or provide screenshots manually."

Workflow

Step 1: Analyze the Stack and Environment

Load context from architecture vision, dev-setup, and the current environment. Detect the current OS via uname. Build a constraints profile:

"Here is what I understand about your stack and environment:

Application type: [Browser app / Tauri desktop / Electron desktop / etc.] UI framework: [SvelteKit / React / Vue / etc.] Rendering context: [Browser viewport / Webview in native frame / Native window with transparency / etc.] Platform targets: [Linux, macOS, Windows] Development environment: [Native / WSL2 / Dev container / etc.] Current OS: [detected via uname]

Key constraints:

• [Constraint 1: e.g., 'Tauri with transparency -- native window compositing cannot be captured by browser-based tools']
• [Constraint 2: e.g., 'WSL2 development -- no native Windows display server access from WSL2']
• [Constraint 3: e.g., 'Webview content IS accessible via standard HTTP -- Playwright can connect to the dev server']

Is this accurate? Anything to add or correct?"

Wait for user confirmation.

Step 2: Propose Layered Testing Strategy

Based on the constraints profile, propose a multi-layer strategy. Read the strategy layers guide:

Read ${CLAUDE_PLUGIN_ROOT}/skills/arn-spark-visual-strategy/references/strategy-layers-guide.md

Match the project's application type against the Layer Decision Matrix to determine the recommended layers. Present the layered approach:

"Based on your stack, here is a layered visual testing strategy:

Layer 1: [Name] (Recommended first)

• What it captures: [e.g., 'Webview content rendered in a browser via Playwright against the dev server']
• Coverage: [e.g., 'All web UI content -- layouts, components, typography, colors. Does NOT capture native window chrome, transparency, or system-level rendering.']
• Environment: [e.g., 'Runs anywhere Playwright runs -- WSL2, CI, macOS, Linux native']
• Complexity: [Low / Medium / High]
• Trade-off: [e.g., 'Fast and reliable but misses native window integration. A button on the wrong side WILL be caught; transparency blending WILL NOT.']

Layer 2: [Name] (Optional, fills gaps)

• What it captures: [e.g., 'Full native window screenshot including transparency, title bar, system tray integration']
• Coverage: [e.g., 'Everything visible on screen including OS chrome and compositor effects']
• Environment: [e.g., 'Requires the target OS natively -- for Tauri Windows apps, needs a Windows machine or CI runner']
• Complexity: [Medium / High]
• Trade-off: [e.g., 'Comprehensive but requires cross-environment pipeline. Screenshots depend on OS version, display scaling, and compositor.']

[Layer 3 if applicable]

My recommendation: Start with Layer 1. It catches 80-90% of visual regressions (layout, component rendering, color, typography) with minimal infrastructure. Add Layer 2 when you need to validate native integration or transparency.

Ask (using AskUserQuestion):

"Which layers do you want to set up?"

Options (based on the layers presented above, e.g.):

1. Layer 1 only (Recommended) — Start with browser-based capture
2. Layer 1 + Layer 2 — Browser-based capture plus native window capture"

Journey interaction detection (Layer 2 only):

If Layer 2 is selected, check whether journey interaction testing is appropriate:

• Does the prototype have multiple routes or navigation flows?
• Does the implementation include interactive sequences (login, form submission, multi-step wizards)?
• Are there state transitions that static screenshots would miss?

If any of these conditions apply, ask the user:

Inform the user: "Layer 2 can capture static screenshots (current behavior) or walk through the app like a user using journey-based interaction testing (via UI automation APIs). Journey mode captures screenshots at each step of a user flow — login, navigation, form submission, etc."

Ask (using AskUserQuestion):

"Do you want to enable journey interaction for Layer 2?"

Options:

1. Yes — Enable journey-based interaction testing
2. No — Keep static screenshot capture

Record the user's choice:

• If yes: set Interaction: journey for Layer 2
• If no or if none of the conditions apply: set Interaction: static for Layer 2
• If the user is unsure: default to static and note that they can upgrade later via arn-spark-visual-readiness

For each selected layer that cannot be validated in the current environment (e.g., native capture from WSL2, CI-only capture):

"Layer [N] ([Name]) cannot be vali