SKILL.md
When to Use
Use the browser when the content itself is visual:
- UI mockups and wireframes — layouts, navigation, component placement
- Architecture diagrams — system components, data flow, relationship maps
- Side-by-side visual comparisons — comparing two layouts or design directions
- Design polish — look and feel, spacing, visual hierarchy
- Spatial relationships — state machines, flowcharts, entity relationships
Use the chat when the content is text or tabular:
- Requirements questions, tradeoff lists, conceptual A/B choices
- Technical decisions (API design, data modeling)
- Clarifying questions where the answer is words, not visuals
A question about a UI topic is not automatically visual. "What kind of wizard?" is conceptual. "Which wizard layout feels right?" is visual.
Quick Start
# Start server (project files persist under .superpowers/visual-mockups/)
scripts/start-server.sh --project-dir /path/to/projectReturns JSON with URL, screendir, and statedir. Tell the user to open the URL.
Different platforms may need different flags:
- macOS/Linux (Claude Code): Default mode works — script backgrounds itself
- Windows (Git Bash): Use
--foregroundsince Windows reaps background processes - Remote/containerized: Pass
--host 0.0.0.0 --url-host localhostfor external browser access - Codex: Auto-detected, runs in foreground automatically
- Gemini CLI: Use
--foreground
If the URL is unreachable, bind to 0.0.0.0 and expose via --url-host.
Content Fragments vs Full Documents
Write content fragments by default — just the HTML inside the page:
<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>The server auto-wraps fragments in the frame template (header, CSS theme, selection indicator, interactive JS). Only write full <html> documents when you need complete control — rare.
Interaction Loop
- Check server is alive, then write HTML to a new file in
screen_dir:
- Check $STATE_DIR/server-info exists (if not, server shut down — restart) - Use semantic filenames: layout.html, visual-style.html - Never reuse filenames — each screen gets a fresh filename
- Tell user to look and respond in the chat:
- Remind them of the URL - Brief text summary of what's on screen - "Take a look and let me know what you think."
- On next turn, read
$STATE_DIR/eventsfor browser interactions, merge with chat response. The chat message is primary feedback; events provide structured data (clicks, selections).
- Iterate or advance — if feedback changes the current screen, write a new file (e.g.,
layout-v2.html).
- Unload when returning to chat — push a waiting screen to clear stale content:
``html <div style="display:flex;align-items:center;justify-content:center;min-height:60vh"> <p class="subtitle">Continuing in chat...</p> </div> ``
- Repeat until done.
CSS Classes Available
The frame template provides these styles for your content fragments:
Options (A/B/C choices)
<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>Add data-multiselect to the container for multi-select.
Cards (visual designs)
<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, Split view, Pros/Cons
<div class="mockup"><div class="mockup-header">Preview</div><div class="mockup-body"><!-- content --></div></div>
<div class="split"><div class="mockup"><!-- left --></div><div class="mockup"><!-- right --></div></div>
<div class="pros-cons"><div class="pros"><h4>Pros</h4><ul><li>X</li></ul></div><div class="cons"><h4>Cons</h4><ul><li>Y</li></ul></div></div>Wireframe building blocks
<div class="mock-nav">Logo | Home | About</div>
<div class="mock-sidebar">Navigation</div>
<div class="mock-content">Main content</div>
<button class="mock-button">Action</button>
<input class="mock-input" placeholder="Input">
<div class="placeholder">Placeholder area</div>Typography
h2 = page title, h3 = section heading, .subtitle = secondary text, .section = content block, .label = small uppercase label.
Design Tips
- Scale fidelity to the question — wireframes for layout, polish for look-and-feel questions
- 2-4 options max per screen
- Use real content when it matters (Unsplash for images, real text for copy)
- Explain the question on each page — "Which layout feels more professional?" not just "Pick one"
- Keep mockups simple — focus on structure, not pixel-perfect design
Cleaning Up
scripts/stop-server.sh $SESSION_DIRIf the session used --project-dir, mockup files persist in .superpowers/visual-mockups/ for later reference. Only /tmp sessions are deleted on stop.
Browser Events
When the user clicks options, interactions are recorded to $STATE_DIR/events as JSON lines:
{"type":"click","choice":"a","text":"Option A - Simple Layout","timestamp":1706000101}
{"type":"click","choice":"b","text":"Option B - Hybrid","timestamp":1706000115}The full event stream shows the user's exploration path. Last choice is typically the final selection. If $STATE_DIR/events doesn't exist, the user didn't interact with the browser — use only their chat text. The file is cleared when you push a new screen.
Related Skills
brainstorming— The primary context for visual mockups. Use during the spec-creation phase when UI questions arise.idea-sharpening— If you're still exploring what to build, do that first before reaching for mockups.