# explore-design

Produce ONE standalone `.html` file that lays out several visual directions side-by-side so the user can pick a direction. The output is for visual comparison — it is not production code.

Two phases:
1. **Explore** (this file) — generate the side-by-side comparison.
2. **Implement** — when the user picks a variant or asks to build a mock, read `references/implement.md` in this skill's directory and follow it.

## When to use this skill

- "Explore directions" / "show me a few options" / "brainstorm designs" / "concept this" / "what could this look like"
- "Implement option C" / "build this exploration" / "make the implementation match the mock" (→ phase 2)
- "Init" / "rebrand the explorations" (→ re-run brand init)

## When NOT to use this skill

- Production components wanted directly, with no exploration step and no mock to match → build in the codebase
- An approved direction from outside this skill, no mock to hold parity against → normal implementation
- A tiny styling tweak to shipped code → just edit it

## Workflow

1. **Run the brand scan — always, before anything else:**
   ```
   bash <skill-dir>/scripts/scan-brand.sh <repo-root>
   ```
   Its first section is the init gate:
   - `STATUS: TEMPLATE_FOUND` → tell the user you're reusing their branded template; continue to step 2.
   - `STATUS: NO_TEMPLATE` → read `references/brand-init.md` and complete brand init BEFORE writing any exploration HTML. **No exceptions.** The source mock/wireframe being styled differently is never a reason to skip init — init styles the document chrome only; the mock contributes content, not brand. Init must end with `design-explorations/_template.html` and `_brand.md` on disk.
2. Read the source spec/brief. Identify the **specific surface** being explored (a hero, a card, a page, a flow). If the spec is large, narrow to the highest-leverage surface and say what you scoped to.
3. **Optional — Landingfolio inspiration.** If the Landingfolio MCP is connected (tools named `mcp__landingfolio__*`), pull 3–5 real examples of the surface type being explored (hero, pricing, testimonials, …) and let them inform the variant theses in the next step. If it is NOT installed, never block and never ask — tell the user in one line that you're passing on it, e.g. "Landingfolio MCP not installed — skipping the inspiration pull. Install it at landingfolio.com/mcp if you want reference designs informing the variants." Then continue as normal.
4. Brainstorm 4 distinctly different directions (range 3–6), each with a one-sentence thesis. **Announce them before writing** — "Building 4 directions: A) social-proof-led, B) calculator-led, …" — this is the last message before the longest silent stretch.
5. If the surface renders a data record, sample a real record first (see "Ground variants in real data").
6. Copy `design-explorations/_template.html` to `design-explorations/<short-name>.html` and fill in the page header + variant sections. Use real copy from the spec/codebase.
7. If a data record is involved, emit `<short-name>.manifest.md` (see below).
8. Open the file in the default browser: `open` (macOS) / `xdg-open` (Linux) / `start` (Windows); skip if headless and just report the path.
9. Report: the variants with their one-line tradeoffs, the file path, the manifest path if emitted, and any Aspirational elements to flag.
10. When the user picks a variant (now or later), read `references/implement.md` and follow it.

**Narrate as you go:** the generation stretch runs minutes with no visible output. One-line status at each checkpoint — after the scan (what it found), after scoping, before writing (the variant theses), after writing (the path). A 3-minute silence must never be the first sign of progress.

## Output location

`design-explorations/<short-name>.html` at the repo root (create the directory if missing; mention it may want gitignoring). If the repo has a conventional scratch location, prefer an `explorations/` folder there — the scan script finds templates in either place.

## Structure of the output file

The template gives you the skeleton:

1. **Page header** — title, one-line subtitle, meta strip (date, source spec, surface name)
2. **Variants** — each a section with: letter label + name · a one-line **tradeoff** (what it optimizes for AND gives up) · the live preview (mobile-width ~440px or full-width as fits) · a short **analysis** (≤3 sentences: what works, what risks, when to pick)
3. **Decision row** — "If you want X → pick A. If Y → pick B…"

## Variant design rules

- **Make them actually distinct.** Differing button colors is a wasted format — push on layout, hierarchy, density, tone, and what gets prioritized. If you can't write distinct one-sentence theses, you don't have distinct variants.
- **Each variant names its tradeoff out loud** ("Most confident, least social-proof") so the user picks on tradeoff, not vibes.
- **Use real copy from the spec/codebase.** Lorem ipsum kills the exercise.
- **Var

…