# Visual Companion Guide

Companion guide for using the visual brainstorming server during design sessions.

## When to Offer Visual Companion

The brainstorming orchestrator should offer the visual companion based on these heuristics. Never force -- always present as an option.

**Offer when:**
- The phase involves UI/UX components (layouts, dashboards, forms, navigation)
- The user mentions layout, design, visual preferences, or "what it looks like"
- Comparing approaches that have visual differences (sidebar vs top-nav, card grid vs list)
- Discussing information architecture or page structure
- Wireframing is mentioned or implied

**Do not offer when:**
- The phase is purely backend (APIs, database, CLI tooling)
- Discussion is about algorithms, data flow, or system architecture without visual output
- The user has previously declined visual companion in the same session

**Offer phrasing:** "Would you like me to start the visual companion so I can show mockups in your browser as we brainstorm?"

## How to Use During Brainstorming

### 1. Launch the Server

```bash
bash ${CLAUDE_PLUGIN_ROOT}/scripts/start-brainstorm-server.sh --project-dir .planning/visual/
```

The server starts on port 3333 and opens a browser tab automatically. The landing page shows a card grid of all fragments, refreshing every 3 seconds.

### 2. Push a Wireframe Fragment

Generate HTML for the mockup, then push it to the server:

```bash
curl -s -X POST http://localhost:3333/fragment \
  -H "Content-Type: text/html" \
  -d '<!DOCTYPE html>
<html><head><style>
  body { font-family: sans-serif; padding: 2rem; background: #f5f5f5; }
  .box { border: 2px solid #ccc; padding: 1rem; margin: 0.5rem; background: white; }
</style></head>
<body>
  <h2>Option A: Card Layout</h2>
  <div style="display: grid; grid-template-columns: 1fr 1fr 1fr; gap: 1rem;">
    <div class="box">Card 1</div>
    <div class="box">Card 2</div>
    <div class="box">Card 3</div>
  </div>
</body></html>'
```

Tell the user: "Check your browser -- I pushed a wireframe for Option A."

### 3. Compare Layouts

Push multiple fragments to show different options:

```bash
# Push Option A
curl -s -X POST http://localhost:3333/fragment \
  -H "Content-Type: text/html" \
  -d '<html><body><h2>Option A: Sidebar Nav</h2>...</body></html>'

# Push Option B
curl -s -X POST http://localhost:3333/fragment \
  -H "Content-Type: text/html" \
  -d '<html><body><h2>Option B: Top Nav</h2>...</body></html>'
```

Tell the user: "I pushed two layout options. Compare them in your browser and let me know which direction you prefer."

### 4. Capture the Selection

When the user expresses a preference, record the decision in CONTEXT.md:

```markdown
### Layout Decision
- **Selected:** Option A (sidebar navigation)
- **Rationale:** User preferred persistent navigation visibility
- **Visual reference:** fragment-1712345678901.html
- **Rejected:** Option B (top nav) -- user felt it wasted vertical space
```

## HTML Fragment Patterns

### Wireframe Skeleton

Gray boxes with labels representing page regions. No real content.

```html
<div style="font-family: sans-serif; padding: 1rem;">
  <div style="background: #333; color: white; padding: 1rem; margin-bottom: 4px;">HEADER / NAV</div>
  <div style="display: flex; gap: 4px;">
    <div style="background: #ddd; padding: 2rem; width: 200px;">SIDEBAR</div>
    <div style="background: #eee; padding: 2rem; flex: 1;">
      <div style="background: #ccc; padding: 1rem; margin-bottom: 4px;">CONTENT AREA</div>
      <div style="background: #ccc; padding: 1rem;">SECONDARY CONTENT</div>
    </div>
  </div>
  <div style="background: #333; color: white; padding: 0.5rem; margin-top: 4px;">FOOTER</div>
</div>
```

### Layout Comparison (Side-by-Side)

Two options rendered in a single fragment for direct comparison.

```html
<div style="font-family: sans-serif; padding: 1rem;">
  <h2>Layout Comparison</h2>
  <div style="display: grid; grid-template-columns: 1fr 1fr; gap: 2rem; margin-top: 1rem;">
    <div>
      <h3 style="color: #af5fff;">Option A</h3>
      <div style="border: 2px solid #af5fff; padding: 1rem; min-height: 300px;">
        <!-- Option A layout here -->
      </div>
    </div>
    <div>
      <h3 style="color: #8700ff;">Option B</h3>
      <div style="border: 2px solid #8700ff; padding: 1rem; min-height: 300px;">
        <!-- Option B layout here -->
      </div>
    </div>
  </div>
</div>
```

### Flow Diagram (CSS-only)

Simple flowchart using CSS flexbox and borders. No JavaScript.

```html
<div style="font-family: sans-serif; padding: 1rem; text-align: center;">
  <h2>User Registration Flow</h2>
  <div style="display: flex; flex-direction: column; align-items: center; gap: 0; margin-top: 1rem;">
    <div style="background: #af5fff; color: white; padding: 0.75rem 1.5rem; border-radius: 20px;">Start</div>
    <div style="width: 2px; height: 30px; background: #ccc;"></div>
    <div style="border: 2px solid #af5fff; padding: 0.75rem 1.5rem; border-radius: 8px;">Enter Email</div>
    <div style="width: 2px; height: 30px; background: #ccc;"></div>
    <div style="border: 2px solid #af5fff; padding: 0.75rem 1.5rem; border-radius: 8px; transform: rotate(45deg); margin: 10px;">
      <span style="display: block; transform: rotate(-45deg);">Valid?</span>
    </div>
    <div style="width: 2px; height: 30px; background: #ccc;"></div>
    <div style="border: 2px solid #af5fff; padding: 0.75rem 1.5rem; border-radius: 8px;">Create Account</div>
    <div style="width: 2px; height: 30px; background: #ccc;"></div>
    <div style="background: #af5fff; color: white; padding: 0.75rem 1.5rem; border-radius: 20px;">Done</div>
  </div>
</div>
```

### Component Mockup

Styled with inline CSS, no external dependencies.

```html
<div style="font-family: -apple-system, sans-serif; padding: 2rem; background: #f5f5f5;">
  <h2>Login Component</h2>
  <div style="max-width: 400px; margin: 1rem auto; background: white; border-radius: 12px;
              box-shadow: 0 4px 12px rgba(0,0,0,0.1); padding: 2rem;">
    <h3 style="color: #333; margin-bottom: 1.5rem; text-align: center;">Sign In</h3>
    <div style="margin-bottom: 1rem;">
      <label style="display: block; color: #666; margin-bottom: 4px; font-size: 0.9rem;">Email</label>
      <div style="background: #f0f0f0; border: 1px solid #ddd; border-radius: 6px;
                  padding: 0.75rem; color: #999;">user@example.com</div>
    </div>
    <div style="margin-bottom: 1.5rem;">
      <label style="display: block; color: #666; margin-bottom: 4px; font-size: 0.9rem;">Password</label>
      <div style="background: #f0f0f0; border: 1px solid #ddd; border-radius: 6px;
                  padding: 0.75rem; color: #999;">********</div>
    </div>
    <div style="background: #af5fff; color: white; text-align: center; padding: 0.75rem;
                border-radius: 6px; font-weight: 600; cursor: pointer;">Sign In</div>
    <p style="text-align: center; margin-top: 1rem; color: #888; font-size: 0.85rem;">
      Forgot password? | Create account</p>
  </div>
</div>
```

## Integration with CONTEXT.md

When visual decisions are made during brainstorming, record them in the CONTEXT.md decisions section:

- **What was decided:** The selected visual approach and why
- **Fragment reference:** The filename (e.g., `fragment-1712345678901.html`) for traceability
- **Rejected alternatives:** What was not selected and why
- **Design constraints:** Any visual constraints discovered (brand colors, accessibility, responsive requirements)

Visual companion is a tool, not a deliverable. Fragments are ephemeral -- they exist to support decision-making. The decisions themselves persist in CONTEXT.md.

## Limitations

- **No JavaScript interactivity** beyond basic CSS hover states. Fragments are static HTML.
- **Not a design tool** -- quick sketches for decision-making, not pixel-perfect mockups.
- **Fragments are temporary** -- deleted when the server shuts down (Ctrl+C).
- **No versioning** -- fragments accumulate during a session. For version comparison, push new fragments.
- **Local only** -- server runs on localhost. Cannot share with remote collaborators.
- **No responsive preview** -- fragments render at the browser window size. For responsive testing, resize the browser manually.
