arn-spark-visual-sketch

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:
5. Look for src/routes/ (SvelteKit)
6. Look for app/ with layout.tsx/page.tsx (Next.js app router)
7. Look for pages/ with index.tsx (Next.js pages router) or index.vue (Nuxt)
8. 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 configuration options']

These screens cover the main user interactions and will show how each visual direction handles different content types (data grids, lists, forms).

Adjust the screen list, add screens, or confirm to proceed."

Screen selection criteria:

• Choose screens that represent distinct content types (dashboard, list, detail, form)
• Prefer screens the user will see most frequently
• Include at least one data-heavy screen and one navigation-heavy screen
• Keep the total to 2-4 screens — enough to show the direction, not so many that generation takes too long

Wait for user confirmation before proceeding.

Step 3: Define Exploration Dimensions

Propose which design aspects should vary between proposals:

"Which aspects of the design should differ between proposals? I suggest exploring:

1. Layout structure — sidebar vs. top navigation, card grids vs. lists, split-panel vs. full-width
2. Color mood — dark vs. light, warm vs. cool, neutral vs. vibrant
3. Typography feel — serif vs. sans-serif headings, compact vs. airy line-height, heavy vs. light weight
4. Density — spacious with generous padding vs. compact with dense information
5. Component style — rounded with shadows vs. sharp with borders vs. pill-shaped minimal
6. Animation approach — static vs. subtle transitions vs. expressive motion vs. scroll-driven narrative

All of these, or focus on specific ones?"

The user's choices guide how the direction briefs (Step 4) differ from each other. If the user wants all dimensions to vary, each proposal will be maximally distinct. If they focus on 1-2 dimensions, proposals share a base but diverge on those aspects.

Step 4: Compose Direction Briefs

Read the aesthetic philosophy reference for tone palette and design vocabulary:

Read ${CLAUDE_PLUGIN_ROOT}/skills/arn-spark-visual-sketch/references/aesthetic-philosophy.md

Use the tone palette (Section 1), anti-generic rules (Section 2), and design dimension guidance (Section 3) to inform brief composition. Each brief should be informed by these principles but written in the skill's own voice — do not copy-paste from the reference.

Based on the user's exploration preferences, compose N direction briefs. Ask the user how many proposals to generate (default 3).

"How many proposals would you like? (Default: 3)"

After the user specifies a count, compose the briefs:

"I'll generate [N] proposals:

Proposal A — [Short Name] [Full paragraph describing the visual direction. Be specific about colors, typography, layout, density, and compon