Mockup Gallery

Install

claude plugin marketplace add tyroneross/RossLabs-AI-Toolkit
claude plugin install mockup-gallery@rosslabs-ai-toolkit

The Problem

Mockup review is a folder of HTML files and a chat thread. Which version did the designer rate yay? Which component inside that mockup is the one to ship? Which route does it map to? Three weeks later nobody remembers and the build ships against the wrong reference.

What I Built

npx mockup-gallery opens a local UI at http://localhost:8787 that browses every HTML mockup in your project, captures ratings and notes, assigns winners to specific pages or screens, and emits two implementation-handoff artifacts when you commit to a build. Auto-detects Next.js routes, SwiftUI views, Python endpoints, and static pages.

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

Each project gets a stable port derived from its path, so multiple galleries run at once without collisions. Implementation tracking flags which components have already shipped, so review sessions do not re-debate settled UI. Auto-save to file means the rating database is a plain text artifact you can diff, commit, or hand to another reviewer.

Wireframe-First Toggle

A sidebar toggle (default ON) drives the host coding agent to begin new review batches with a lo-fi wireframe before hi-fi HTML variants. Flip OFF when you want hi-fi directly. The preference persists per-project at .mockup-gallery/state.json#preferences.wireframeFirst. This catches the “the agent jumped to visuals before we agreed on structure” problem before it happens.

Two Handoff Artifacts

When a mockup gets selected for a build, the gallery emits two artifacts the coding agent then reads:

• Project-root DESIGN.md in Google’s design-system format — the visual identity (colors, typography, spacing, elevation, shape) shared by mockup-gallery, ad-hoc design tools, and any AI coding agent working the repo. Scaffold via POST /design-system/scaffold.
• Per-route .mockup-gallery/handoff/<slug>.md — emitted on /selected. Carries the interaction, data, state, and connector contracts for that specific route. The agent reads it before writing the component.

Project Detection

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

Filenames fuzzy-match to routes for pre-selection. Component tagging works inside each mockup for finer-grained tracking.

Claude Code Plugin

Installed as a Claude Code plugin, the gallery adds:

• SessionStart hook — shows design-review status (ratings, pending items, implementation progress)
• /mockup-gallery — single entry point for launch, status, feedback, sessions, selected-build handoff, implementation guidance, and sync checks. Before coding selected UI, the agent uses /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: state.json (schema version, current session, preferences), selections.json (ratings + notes), selected.json (build assignments), implemented.json (tracking), accepted-designs.json (approved patterns), handoff/ (per-route specs), and sessions/<slug>/ for multi-session work. The project-root DESIGN.md lives alongside package.json — it is the visual-identity source of truth, not a per-tool artifact. Add .mockup-gallery/ to .gitignore to keep review state out of version control.