iterative:design-exploration

What this skill does

# Design Exploration

Generate a single self-contained HTML file presenting distinct design variations (scaled to scope — see Step 2) with per-variation interactive controls, a rating/feedback system, and structured export. The goal is divergent thinking: explore fundamentally different approaches to a design problem before converging on a direction. "Different" means different on the right axis — usually different interaction models, not different visual themes.

## When to Use

- Before brainstorming, to anchor a greenfield discussion with visual options
- After brainstorming, to explore how requirements could look/feel before tech planning
- Standalone, when someone wants to see design options for any page, component, or feature
- When iterating on a previous round of explorations (user pastes feedback from export)

## Key Principles

1. **Diverge before converging** — The point is to explore fundamentally different approaches. But "different" must be on the right axis: different interaction models for functional problems, different visual identities for aesthetic problems. A neon terminal and a boutique card layout that have identical form flows are NOT different where it matters.
2. **Multiple rounds are normal** — The first round is broad exploration. Subsequent rounds refine based on feedback. The skill supports this loop natively.
3. **The direction doc is the durable output** — HTML galleries are working artifacts. The design direction document captures what was chosen and why.
4. **Standalone or in-workflow** — Works independently or as part of the brainstorming → tech-planning pipeline. Adapts handoff based on context.

## Process

1. **Detect context (always first)** — check for existing explorations before responding. Resume, iterate, or fresh start.
2. **Understand the request** — only for fresh explorations. What is being designed, for whom, divergence axis, constraint level
3. **Plan the variations** — variations across families, count scaled to scope, divergent on the right axis
4. **Generate the HTML file** — gallery with variations, controls, ratings, metadata, export
5. **Conclude** — when the user converges, capture the design direction

## File Structure

All artifacts for an exploration live in a dated topic directory:

```
docs/design-explorations/YYYY-MM-DD-<topic>/
  v1.html          ← first round
  v2.html          ← refined round
  v3.html          ← further refinement

docs/design-directions/
  YYYY-MM-DD-<topic>-design-direction.md    ← written at conclude
```

---

## Step 0: Detect Context (MANDATORY — runs first, before ANY response to the user)

**Your very first action must be detection — before any Q&A, scoping questions, or even acknowledging the request.** Do NOT skip to Step 1 without completing the checks below.

### 0a. Check for feedback input

If the user's message contains structured feedback (ratings, reference to a previous exploration file), this is an iteration round. Extract the `Source:` path from the feedback, then read the metadata from that HTML file (see "Reading prior metadata" in Step 3). This gives you the families, variations, and round number. Proceed to Step 2 with both the feedback and the metadata as context.

### 0b. Check for existing explorations

**Before responding to the user**, check what's in `docs/design-explorations/`. If any existing exploration looks relevant to the user's request, tell them you found it and ask whether to iterate or start fresh. If iterating, read the previous round's metadata (see Step 3). Proceed to Step 2 — **skip Step 1 entirely**. If nothing relevant exists, proceed to Step 1.

---

## Step 1: Understand the Request

Input can range from a single sentence ("explore designs for a notification system") to a full PRD. The goal of this step is to gather enough context that the approach-based divergence planning in Step 2 produces meaningfully different directions — not random ones.

**This step only runs for fresh explorations** (no feedback input, no existing exploration to iterate on). If Step 0 found a previous round to iterate on, skip this step — the metadata provides the context.

### Adaptive scoping

Ask 0-2 scoping questions based on how much ambiguity exists. When a PRD or detailed requirements already exist (e.g., from `iterative:brainstorming`), the problem space is already mapped — determine the divergence axis from the existing context and proceed to Step 2. The PRD informs the exploration but doesn't constrain the creative surface; the whole point is to discover visual and interaction possibilities the requirements alone can't express.

When input is lighter (a sentence or brief description), component prompts tend to describe the full problem; larger scopes tend to leave more genuinely open. The right questions inform the exploration — the wrong ones constrain it. The test: does knowing the answer change *which approaches you'd explore*, or does it just eliminate options the user should see? If it eliminates options, don't ask — let the exploration show them.

### Scope surfacing

When input covers **multiple distinct UI surfaces** (e.g., a PRD describing a dashboard, an upload flow, a settings page, and an image grid), identify the surfaces and ask the user what to explore. Present options including exploring everything (full scope) as a first-class choice, plus focused options for individual surfaces or natural groupings. Frame it as "I see these surfaces — want to explore all of them, or focus on a subset?" — not "pick exactly one." Keep it to a single question.

When input is already narrow (a single component, one screen, one flow), skip this — there's nothing to scope.

### What you need to know before proceeding (infer from context when possible)

- **Divergence axis** — interaction, visual, or both? (see below — usually obvious from context)
- **The goal** — what problem is being solved
- **Who** — audience and their context (obvious for components, worth asking for full pages)
- **Constraint level** — greenfield or fitting into an existing app?

### Divergence Axis

The divergence axis determines WHAT varies between families. This is the most important decision — getting it wrong produces explorations that are visually impressive but practically useless.

**Interaction divergence (DEFAULT)** — Families explore different ways the thing WORKS. Different behavior, flow, information architecture, progressive disclosure, state handling. All variations share a clean, professional visual treatment — a realistic neutral UI that looks like it belongs in a real product. The user is comparing interaction models, not color palettes.

- Default for: components, features, anything inside an existing app, anything with a clear functional problem to solve
- Example: "price input with sale toggle" → one family uses inline toggle that reveals fields, another uses side-by-side comparison, another uses a stepped wizard, another shows a live storefront preview. All look like a professional admin panel.
- Example: "notification center" → drawer vs popover vs inline expansion vs full-page view. All share the same visual language.

**Visual divergence** — Families explore different ways the thing LOOKS. Same functional structure (or a simple reference structure), different aesthetics, typography, spatial composition, atmosphere. Useful for establishing visual identity when there IS no existing design language.

- Use for: landing pages, brand exploration, design system foundations, or when the user explicitly asks to explore visual styles
- Example: "landing page for a new product" → one family is brutalist editorial, another is luxury minimal, another is playful illustrated
- This mode triggers the full creative typography, color, and atmosphere treatment

**Both** — Families differ in both visual identity AND interaction model. Only appropriate when the entire page or app is open — no existing design system, no existing interaction patterns, full greenf