Mockup Gallery
A local design review tool for browsing, rating, and selecting HTML mockups. Works with any project — auto-detects Next.js routes, SwiftUI views, Python endpoints, and static pages.
Quick Start
# From your project directory (must have a mockups/ folder with .html files)
npx mockup-gallery
# Or point to a specific project
npx mockup-gallery --project /path/to/project --dir mockups
The gallery opens at http://localhost:8787 (auto-increments if busy). Each project gets a stable port based on its path, so multiple galleries can run simultaneously.
Features
- Rate mockups — Yay/Nay with notes. Rated items stay in Active with color-coded dots.
- Select for build — Assign mockups to specific pages/screens. Auto-detects project routes.
- Save for later — Bookmark mockups without assigning them.
- Component tracking — Tag individual components within mockups.
- Archive — Move reviewed mockups out of the active flow.
- Auto-placement — Fuzzy-matches mockup filenames to detected routes and pre-selects.
- Implementation tracking — Track which components have been built.
- Multi-project — Run separate galleries for different projects simultaneously.
- Wireframe-first toggle — A sidebar toggle (default ON) that drives the host coding agent to begin new review batches with a lo-fi wireframe before hi-fi HTML variants. Persisted per-project at
.mockup-gallery/state.json#preferences.wireframeFirst. Flip OFF to allow hi-fi directly.
- Two implementation-handoff artifacts — A project-root
DESIGN.md in Google's design-system format for visual identity (colors, typography, spacing, elevation, shape), AND per-route .mockup-gallery/handoff/<slug>.md files emitted on /selected for interaction / data / state / connector contracts. Scaffold the design system via POST /design-system/scaffold.
Sidebar Layout
SELECTED Top — mockups assigned to pages/screens
ACTIVE Middle — all current mockups (yay/nay just marked, not moved)
SAVED Below active — bookmarked for later reference
ARCHIVE Bottom — reviewed and set aside
Project Detection
The gallery auto-detects your project type and available pages/screens:
| Project Type | Detection | Route Source |
|---|
| Next.js App Router | app/ dir with page.tsx | File-system routes |
| Next.js Pages | pages/ dir | File-system routes |
| SwiftUI | *View.swift files | View names + platform tags |
| Python (Flask/FastAPI) | @app.route decorators | Decorated endpoints |
| Static | HTML files in public/ | Filenames |
CLI Options
--project <path> Project root (default: cwd)
--dir <path> Mockups directory (default: auto-detect mockups/, docs/mockups/, .claude/mockups/)
--port <number> Starting port (default: stable hash of project path in 8787-8886 range)
Claude Code Plugin
Install as a Claude Code plugin for session-start status and slash commands:
claude plugin add /path/to/mockup-gallery
Or add to .claude/plugins.json:
{
"plugins": [
{ "path": "/path/to/mockup-gallery" }
]
}
Plugin Features
- SessionStart hook — Shows design review status (ratings, pending items, implementation progress)
/mockup-gallery — Single Claude Code entry point for launch, status, feedback, sessions, selected-build handoff, implementation guidance, and sync checks- Implementation handoff guidance — Before coding selected UI, Claude can use
/mockup-gallery implement or /mockup-gallery handoff to map changed UI elements to static/dynamic data, actions, connectors, visualizations, and unresolved questions
Data Storage
All data lives in .mockup-gallery/ inside the project root:
.mockup-gallery/
state.json Top-level: schema version, currentSession, preferences (wireframeFirst, ...)
selections.json Ratings + notes (legacy flat layout)
selected.json Selected build (pages, components, saved) (legacy flat layout)
implemented.json Implementation tracking
accepted-designs.json Approved design patterns
handoff/ Per-route implementation handoff specs (Markdown) — written on /selected
sessions/<slug>/ Sessions-mode equivalents of selections/selected/handoff
The project-root DESIGN.md (Google design-system format) lives alongside package.json, not under .mockup-gallery/ — it is the visual-identity source of truth shared by mockup-gallery, ad-hoc design tools, and AI coding agents.
Add .mockup-gallery/ to .gitignore if you don't want to track review state in version control.
Mockup Directory Structure
mockups/
01-homepage.html Active mockups
02-settings-page.html
archive/ Archived mockups (moved via gallery UI)
old-version.html
