§ Guides

UI preview pack.

Hand the spec to Lovable, v0, bolt.new, or Base44 to produce a clickable prototype for user testing.

Specgraph specs aren't just for engineering hand-off — they're also a useful input to AI app-builders like Lovable, v0, bolt.new, and Base44. The UI preview pack is a separate composition of the project's spec, framed for a different audience and a different goal: a clickable prototype for user testing, generated from the same source data the BMAD pack draws on.

What it is — and what it isn't #

The UI preview pack is a six-file Markdown bundle plus a one-paragraph implementation prompt. You hand it to an AI builder; the builder produces a frontend-only prototype that real testers can click through to validate the design and flows.

It's a clarity check, not a deliverable. If Lovable produces something coherent from your spec, the spec reads clearly. If the output diverges wildly from your intent, the gap tells you what's vague — feed those gaps back into Specgraph and try again.

A few things it's deliberately not:

Not the production app. Every file ends with a footer telling the builder to mock all data and skip backend wiring. Discard the generated code after the test.
Not the BMAD pack. BMAD is the engineering hand-off — eight planning artifacts, FR-tagged stories, sprint-status, the whole pipeline. The UI preview pack is six smaller files tuned for an LLM that builds UI, not a developer that ships code.
Not backend-aware. Lovable defaults to Supabase; v0 defaults to whatever its templates suggest. The pack tells the builder to ignore all of that — no real auth, no real database, no real email. Otherwise the demo locks you into a stack you may not want for production.

When to reach for it #

You've finished the Vision, Features, Design, and Architecture phases and want to see the spec in motion before locking it.
You're running a moderated user-testing session and want a clickable prototype on a laptop, not a static Figma file.
A teammate or stakeholder isn't grokking the proposed UX from words alone — a 5-minute Lovable build often makes the disagreement obvious.
You're auditioning multiple AI builders and want a fair, identical input to feed each one.

What's in the pack #

Six files, designed to be read in order. Each ends with the same throwaway disclaimer so the builder gets the framing twice — at the start and the end of every file (LLMs drop the middle of long contexts).

File	What it contains
`README.md`	The comprehensive prompt the AI builder reads first. Build phases, hard rules, definition of done.
`OVERVIEW.md`	What the app is, who the testers are, and what the test should reveal.
`FLOWS.md`	The journeys testers will click through end-to-end — the definition of done for the prototype.
`SCREENS.md`	Every screen, in build order, with components and which mock data populates each.
`DESIGN.md`	Palette, typography, component vocabulary, interaction feel — opinionated.
`MOCK-DATA.md`	Realistic seed data so the prototype feels alive. Synthesised from your Architecture phase entities.

The pack regenerates every time you open the panel, so it always reflects the current state of the project — there's no "save" or "publish" step.

Step 1 — Open the panel #

Inside any project, click the wand icon in the right rail (between the BMAD pack and Settings icons). The panel slides in with a file picker at the top, the active file's content in the middle, and two action buttons at the bottom.

Skim the files first. Most importantly:

Does OVERVIEW.md describe the right test audience? If your project's Vision phase is light on personas, the overview will be too.
Does FLOWS.md have at least 3–5 numbered journeys? If it's empty, fill in the Features phase (must-have features) or the Design phase's user journeys.
Does MOCK-DATA.md have entities? If it's empty, fill in the Architecture phase's entities table — the synth heuristic needs field names to produce realistic rows.

If something looks thin, edit the source phase in Specgraph and re-open the panel — the pack recomposes live.

Step 2 — Copy the prompt, attach the files #

The panel has two primary actions, used together:

Copy implementation prompt — copies a tight one-paragraph prompt for the AI builder's chat input. It tells the builder to read README.md first and follow its instructions; everything else flows from that.
Download all 6 files — saves all six markdown files locally. Drop them into the AI builder's repo (Lovable, bolt.new) or attach them as context (v0).

The prompt and files together are the complete handoff — neither alone is enough. The prompt without the files leaves the builder guessing; the files without the prompt sometimes get treated as "reference material" rather than instructions.

Step 3 — Paste in your AI builder #

The panel has clickable logos for Lovable, v0, bolt.new, and Base44 — click any to open the tool in a new tab. Each has a slightly different intake:

— connect a GitHub repo, paste the prompt as your first message, drop the files into the repo root or a docs/ folder. Lovable scans the repo on connect, so the files are picked up automatically.
— paste the prompt into the chat. Drag the files in as attachments (v0 supports multi-file upload). v0 is the most UI-focused of the four; expect very polished components.
— paste the prompt and attach the files. bolt.new spins up a full WebContainer-based dev environment, which means you can run the prototype directly in the browser without exporting.
— paste the prompt into the chat and attach the files. Base44 generates a hosted prototype with built-in mock data, ideal for sharing a clickable preview link with testers without leaving the browser.

In all three, the build typically takes 2–6 minutes. The output is a working web app with mocked data, navigable through the flows in FLOWS.md.

Step 4 — Run your test #

The point of the prototype is what testers see, not what the builder generated. Run the test as you'd run any moderated UX session:

Send the testers the live URL the AI builder gives you (Lovable and bolt.new both offer a hosted preview link; v0 lets you fork to Vercel).
Walk through the flows in FLOWS.md one at a time. Note where testers hesitate, misclick, or ask "what does this do?"
The mock data in MOCK-DATA.md is shared across all testers — you don't need to reset between sessions.

The signal you're looking for is clarity divergence: where the prototype's behaviour doesn't match what testers expect, you've found a gap in the spec. Feed those gaps back into Specgraph (Vision, Features, Design phases) and regenerate the pack for the next round.

Frequently asked #

Can I edit the generated files? Don't. They regenerate from project state every time the panel opens, so any local edits are lost. If you want to change the pack, change the underlying Specgraph phase.

Can I push the pack to GitHub directly from Specgraph? Not yet — manual download for now. A GitHub-App integration is on the roadmap (per-project repo connection, automatic push on phase-lock), but it's a larger piece of work.

The mock data looks weird for my domain. The synth heuristic guesses values from field names (anything matching email becomes an email, anything matching status becomes one of active/draft/in-review/archived, etc.). If your entities use unusual field names, expect the rows to read as generic. The next version of the heuristic will pull from a domain glossary if your project has one.

Why not generate the prototype directly in Specgraph? The builders are good at this; we're not. Specgraph is for the spec, not for the build. The pack is the boundary.

Will Lovable / v0 / bolt / Base44 support the same prompt format forever? No, all four iterate fast. The pack is designed to be tool-agnostic — the prompt and files describe what to build, not how each tool should build it. If a tool changes its conventions, the pack still applies; you just paste it into the new chat shape.

BMAD pack — the engineering hand-off pack, with stable story keys, MCP tooling, and Dev Agent Records. Pair the BMAD pack with a coding agent like Claude Code; pair the UI preview pack with an app-builder like Lovable.
Mid-build amendments — how to feed test findings back into the spec without breaking the BMAD pack's story keys.