/arn-spark-visual-strategy

name: arn-spark-visual-strategy
description: >-
  This skill should be used when the user says "visual strategy",
  "arn visual strategy", "visual testing", "visual regression",
  "screenshot testing", "compare to prototype", "visual validation",
  "how do I test visuals", "set up visual tests", "baseline images",
  "screenshot comparison", "pixel diff", "visual diff",
  "does it match the prototype",
  or wants to set up visual regression testing for development — creating
  capture scripts, comparison scripts, and baseline images so that feature
  implementations are automatically compared against prototype screenshots
  to catch visual regressions during development.
version: 1.0.0

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