---
name: creating-mockups
description: Browser-based visual brainstorming companion for UI mockups, wireframes, and layout comparisons. Invoke only when user needs to see visual options — not for text/conceptual choices.
---

# Visual Mockups Companion

Browser-based visual brainstorming for showing mockups, diagrams, and options.

## When to Use

Decide per-question. Test: **would the user understand this better by seeing it than reading it?**

**Use browser** when content is visual:
- UI mockups — wireframes, layouts, navigation structures, component designs
- Architecture diagrams — system components, data flow, relationship maps
- Side-by-side visual comparisons — layouts, color schemes, design directions
- Design polish — look and feel, spacing, visual hierarchy
- Spatial relationships — state machines, flowcharts, entity relationships

**Use terminal** when content is text/tabular:
- Requirements and scope questions
- Conceptual A/B/C choices described in words
- Tradeoff lists — pros/cons, comparison tables
- Technical decisions — API design, data modeling
- Clarifying questions — answers are words, not visual preferences

A question *about* a UI topic is not automatically visual. "What kind of wizard?" = conceptual → terminal. "Which wizard layout feels right?" = visual → browser.

## How It Works

Server watches a directory for HTML files, serves newest to browser. Write HTML to `screen_dir`, user sees it and clicks to select options. Selections recorded to `state_dir/events`.

**Content fragments vs full docs:** If HTML starts with `<!DOCTYPE` or `<html`, served as-is (injects helper script). Otherwise server wraps in frame template automatically. **Write content fragments by default.**

## Starting a Session

```bash
# Start server (mockups saved to /tmp, ephemeral)
scripts/start-server.sh

# Start server with persistence
scripts/start-server.sh --project-dir /path/to/project
```

Returns JSON:
```json
{"type":"server-started","port":52341,"url":"http://localhost:52341",
 "screen_dir":"/tmp/brainstorm-12345/content",
 "state_dir":"/tmp/brainstorm-12345/state"}
```

Save `screen_dir` and `state_dir`. Tell user to open URL.

**Platform notes:**

**Claude Code (macOS/Linux):** Default mode works — script backgrounds server itself.

**Claude Code (Windows):** Set `run_in_background: true` on Bash tool call. Read `$STATE_DIR/server-info` next turn.

**Codex:** Script auto-detects `CODEX_CI`, switches to foreground. Run normally.

**Gemini CLI:** Use `--foreground` with `is_background: true` on shell tool call.

**Remote/containerized** (URL unreachable from browser):
```bash
scripts/start-server.sh --host 0.0.0.0 --url-host localhost
```

## The Loop

1. **Write HTML** to new file in `screen_dir`:
   - Check `$STATE_DIR/server-info` exists first. Missing (or `server-stopped` exists) → restart server.
   - Semantic filenames: `platform.html`, `layout.html` — **never reuse filenames**
   - Use Write tool — never cat/heredoc
   - Server serves newest file automatically

2. **Tell user** what's on screen, remind them of URL, ask for response in terminal.

3. **Next turn** — read `$STATE_DIR/events` if exists (browser clicks as JSON lines). Merge with terminal text.

4. **Iterate or advance** — feedback changes current screen → write new file (`layout-v2.html`). Move on only when step validated.

5. **Unload when returning to terminal** — push waiting screen:
   ```html
   <div style="display:flex;align-items:center;justify-content:center;min-height:60vh">
     <p class="subtitle">Continuing in terminal...</p>
   </div>
   ```

## Writing Content Fragments

```html
<h2>Which layout works better?</h2>
<p class="subtitle">Consider readability and visual hierarchy</p>

<div class="options">
  <div class="option" data-choice="a" onclick="toggleSelect(this)">
    <div class="letter">A</div>
    <div class="content">
      <h3>Single Column</h3>
      <p>Clean, focused reading experience</p>
    </div>
  </div>
  <div class="option" data-choice="b" onclick="toggleSelect(this)">
    <div class="letter">B</div>
    <div class="content">
      <h3>Two Column</h3>
      <p>Sidebar navigation with main content</p>
    </div>
  </div>
</div>
```

No `<html>`, no CSS, no `<script>` needed. Server provides all.

## CSS Classes

### Options (A/B/C)
```html
<div class="options">
  <div class="option" data-choice="a" onclick="toggleSelect(this)">
    <div class="letter">A</div>
    <div class="content"><h3>Title</h3><p>Description</p></div>
  </div>
</div>
```

**Multi-select:** Add `data-multiselect` to container.

### Cards (visual designs)
```html
<div class="cards">
  <div class="card" data-choice="design1" onclick="toggleSelect(this)">
    <div class="card-image"><!-- mockup content --></div>
    <div class="card-body"><h3>Name</h3><p>Description</p></div>
  </div>
</div>
```

### Mockup container
```html
<div class="mockup">
  <div class="mockup-header">Preview: Dashboard Layout</div>
  <div class="mockup-body"><!-- mockup HTML --></div>
</div>
```

### Split view
```html
<div class="split">
  <div class="mockup"><!-- left --></div>
  <div class="mockup"><!-- right --></div>
</div>
```

### Pros/Cons
```html
<div class="pros-cons">
  <div class="pros"><h4>Pros</h4><ul><li>Benefit</li></ul></div>
  <div class="cons"><h4>Cons</h4><ul><li>Drawback</li></ul></div>
</div>
```

### Mock elements (wireframe blocks)
```html
<div class="mock-nav">Logo | Home | About | Contact</div>
<div style="display:flex;">
  <div class="mock-sidebar">Navigation</div>
  <div class="mock-content">Main content area</div>
</div>
<button class="mock-button">Action Button</button>
<input class="mock-input" placeholder="Input field">
<div class="placeholder">Placeholder area</div>
```

### Typography
- `h2` — page title
- `h3` — section heading
- `.subtitle` — secondary text
- `.section` — content block with bottom margin
- `.label` — small uppercase label

## Browser Events Format

```jsonl
{"type":"click","choice":"a","text":"Option A - Simple Layout","timestamp":1706000101}
{"type":"click","choice":"b","text":"Option B - Hybrid","timestamp":1706000115}
```

Last `choice` event = final selection. Click pattern reveals hesitation.

No `$STATE_DIR/events` → user didn't interact with browser — use terminal text only.

## Design Tips

- Scale fidelity to question — wireframes for layout, polish for polish questions
- Explain question on each page — "Which feels more professional?" not just "Pick one"
- Iterate before advancing
- 2-4 options max per screen
- Use real content when it matters (Unsplash for photo portfolios)
- Keep mockups simple — layout/structure, not pixel-perfect

## File Naming

- Semantic names: `platform.html`, `layout.html`
- Never reuse — each screen = new file
- Iterations: `layout-v2.html`, `layout-v3.html`
- Server serves newest by modification time

## Cleanup

```bash
scripts/stop-server.sh $SESSION_DIR
```

## Reference

- Frame template (CSS): `scripts/frame-template.html`
- Helper script (client-side): `scripts/helper.js`