/arn-spark-visual-sketch

name: arn-spark-visual-sketch
description: >-
  This skill should be used when the user says "visual sketch", "arn visual sketch",
  "sketch directions", "explore visuals", "visual proposals", "try different looks",
  "design directions", "sketch the UI", "visual exploration", "compare styles",
  "show me options", "what could this look like", or wants to generate multiple
  visual direction proposals as real HTML/CSS running on the scaffolded project's
  dev server, iteratively selecting and refining until a final visual direction
  is chosen.
version: 1.0.0

Arness Spark Visual Sketch

Generate visual direction proposals as real HTML/CSS in the scaffolded project, compare them side by side in the browser, and iteratively refine until a direction is selected. This is a conversational skill that runs in normal conversation (NOT plan mode). The primary artifacts are a **visual-direction.md** document in the Vision directory and **screenshot captures** of the selected direction in the visual grounding directory.

This skill sits between `/arn-spark-scaffold` and `/arn-spark-style-explore` in the greenfield pipeline. It produces a visual-direction.md that style-explore uses as primary input for detailed design token specification. The user sees what the product could look like before committing to a full design system.

The iterative process works in rounds: 1. **Round 1:** N proposals with distinct visual directions (default 3) 2. **Round 2+:** N expansions of the selected proposal with user-guided refinements 3. **Final:** The selected direction is captured and documented

Each proposal runs on the scaffold's actual dev server using the project's real CSS framework and component library.

Prerequisites

The following artifacts inform the sketch generation. Check in order:

Determine the output directories: 1. Read the project's `CLAUDE.md` and check for a `## Arness` section 2. If found, extract the configured Vision directory path and Visual grounding directory path 3. 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. 4. Create directories if they do not exist

> All references to "Vision directory" and "visual grounding directory" in this skill refer to the configured directories determined above.

**Scaffold (required):** 1. Check the Vision directory for `scaffold-summary.md` 2. If no `## Arness` section found, check `.arness/vision/scaffold-summary.md` at the project root 3. Also check for `package.json` at the project root

**If a scaffold-summary is found:** Read it to extract the full technology stack — UI framework, CSS framework, component library, icon library, dev server command, build command.

**If no scaffold-summary is found:** Inform the user: "The project must be scaffolded before visual sketching. The sketch needs a real CSS framework and component library to generate proposals. Run `/arn-spark-scaffold` first." Do not proceed.

**Architecture vision (required for fallback context):** 1. Check the Vision directory for `architecture-vision.md` 2. If no `## Arness` section found, check `.arness/vision/architecture-vision.md`

**If found:** Read it for UI framework and platform context. The scaffold-summary is the primary source, but the architecture vision provides additional context (platform type, product category).

**If not found:** Proceed if scaffold-summary exists — the scaffold-summary contains enough technical context.

**Product concept (recommended):** 1. Check the Vision directory for `product-concept.md` 2. If no `## Arness` section found, check `.arness/vision/product-concept.md`

**If found:** Read it to identify screens, understand target users, and derive realistic content for sketches.

**If not found:** Ask the user to describe the product briefly. Screen identification and content will be based on the user's description. Note the limitation.

**Dev server verification:** 1. Extract the dev server command from scaffold-summary.md (the "How to Run" section) 2. Verify the project builds without errors by running the build command

If the build fails, do not proceed with sketch generation. Report the error and suggest the user fix the scaffold first.

Workflow

Step 1: Load Context

Read available documents and present a summary:

1. Read `product-concept.md` → extract target users, core experience, product pillars 2. Read `architecture-vision.md` → extract UI framework, platform type 3. Read `scaffold-summary.md` → extract CSS framework, component library, icon library, dev commands 4. Detect framework routing conventions by examining the project source directory:

• Look for `src/routes/` (SvelteKit)
• Look for `app/` with `layout.tsx`/`page.tsx` (Next.js app router)
• Look for `pages/` with `index.tsx` (Next.js pages router) or `index.vue` (Nuxt)
• Fall back to generic approach if none match

Present the context:

"Your project uses **[UI framework]** with **[CSS framework]** and **[component library]** on **[platform]**. The product targets [target users] and focuses on [core experience].

I will create visual direction proposals as real pages in your project, running on your dev server. Each proposal applies a distinct visual approach to the same set of product screens.

Let's start by identifying which screens to sketch."

Step 2: Identify Screens to Sketch

From the product concept (or user description), propose 2-4 key screens that represent the core experience:

"Based on your product concept, I suggest sketching these screens:

1. **[Screen Name]** — [What it shows, e.g., 'Main dashboard with device status grid and connection indicators'] 2. **[Screen Name]** — [What it shows, e.g., 'List view with filterable items and status badges'] 3. **[Screen Name]** — [What it shows, e.g., 'Settings panel with grouped configu