design

AI-powered UI mockup CLI. Generate, iterate, diff, and QA production-quality UI mockups from the command line. Pluggable providers — bring your own OpenAI or Gemini key.

Install

brew install juanheyns/tap/design

Quick start

design setup                    # Configure your API key (OpenAI or Gemini)
design generate --brief "Dashboard with metrics cards and a sidebar" --output mockup.png
design check --image mockup.png --brief "Dashboard with metrics cards and a sidebar"

What it does

• generate — Text brief → production-quality PNG mockup via GPT-4o image generation
• variants — Generate N different interpretations of the same brief for exploration
• iterate — Multi-turn refinement with conversation threading ("make the header smaller")
• check — Vision-based QA gate: does the mockup match the brief?
• compare — HTML comparison board for side-by-side variant review
• diff — Visual diff between two PNGs with per-area severity ratings
• evolve — Take a screenshot of your live site + a change brief → new mockup
• design-to-code — Extract structured implementation prompt from an approved mockup
• gallery — HTML timeline of all design explorations for a project

Commands

See SKILL.md for the full command reference with examples and common patterns.

Building from source

git clone https://github.com/juanheyns/gstack-design.git
cd gstack-design
./setup
dist/design --help

Requires bun >= 1.0.0.

Configuration

design setup                          # Interactive: pick OpenAI or Gemini, enter key
export OPENAI_API_KEY=sk-...          # OpenAI via env var
export GEMINI_API_KEY=AIza...         # Or Gemini via env var
export DESIGN_PROVIDER=gemini         # When both keys are set, force one

Config is stored at ~/.config/design/config.json. Generated output defaults to .design/ in the project root.

See docs/providers.md for the full provider matrix (image edit, session threading, JSON mode).

Agent integration

Every command outputs structured JSON to stdout and logs to stderr, making it suitable for use by AI coding agents. The typical agent loop:

generate → check → (iterate if check fails) → compare variants → design-to-code → implement

The evolve + diff pair enables a closed loop: screenshot the live site, evolve it, implement the changes, screenshot again, diff to verify fidelity.

Note for existing gstack users

If you already have gstack installed, the design binary is available via gstack. This standalone package lets you use it independently. Both installations coexist — the standalone config is at ~/.config/design/ while gstack uses ~/.gstack/. The standalone binary reads gstack's OpenAI key as a fallback.

License

MIT