Clickable prototypes designers hand to engineers.
Real screens built from your project's own components, the flow between them, the states each screen can be in, the document that explains the intent, and the designer's comments pinned to the elements they are about. Click through it at the size of a real device, lay every state out on one canvas, walk a client through it with a guided tour, and hand the folder to the engineer. Storybook shows a component. A prototype here shows a decision: what the user clicks, what they see next, and what the engineer has to get right.
Good morning
Dana
Follow-up visit
Dr. Okafor asked to see you two weeks after your last visit. Booking is open through October.
Button #book-follow-upBook a visit1Refill: Lisinopril
Two refills left. Your pharmacy has the request.
View medicationIntake questions
Four questions left from your last visit.
Continue20-choose-time.no-slots.tsx is the empty week.Why a prototype, not a story
Storybook shows a component. A prototype shows a decision.
A story answers "what does the button look like". The engineer building the feature needs "what happens when they click it, what if there are no slots, which timezone are these in, and why is this the only filled button on the page". A prototype folder holds all of that, next to the code, reviewed in the same pull request.
Design mocks Figma, images
- Drawn with components that look like the real ones and drift from them.
- The flow lives in arrows on a canvas; the states live in copies of frames.
- Comments point at pixels. When the frame moves, the thread is orphaned.
- Rules the screens cannot show live in a separate doc, or in someone's head.
A Prototype Lab folder in the repo
- Screens are TSX that import the project's own components and stylesheet, so the prototype is wrong in the ways the design is wrong, not the ways a mock is.
- The flow is found by clicking every control at run time and drawn as arrows on a canvas of every state. A dead link loses its arrow; a typo shows as a red card.
- Comments pin to a semantic id that survives the markup around it changing, and are written to
annotations.jsonfrom the viewer. prototype.mdsits beside the screens: the flow, the rules, the open questions, what is out of scope.
A prototype is a folder
Three things that must agree with each other.
The story, the screens, and the comments. Drop the folder under prototypes/ and the viewer picks it up. There is no registry to edit, and the filename carries the screen id, its state and its order.
prototypes/patient-booking/ prototype.md the story: flow, rules, open questions annotations.json comments pinned to elements by id screens/ 10-home.tsx one screen, one file 20-choose-time.tsx 20-choose-time.no-slots.tsx a state of that screen 30-review.tsx 40-confirmed.tsx prototypes/billing/ a group: no doc, no screens invoice-list/ #/p/billing/invoice-list refunds/partial-refund/ groups nest; the path is the slug
Get a flow on stage in three steps.
Add the package to a React 19 project
The viewer runs on Vite, which comes with the package. Your project does not need to use Vite, and an index.html it already has is left alone.
$ npm install --save-dev vinta-prototype-lab
Add a folder, or ask your agent to
Copy the worked example, or install the build-prototype skill and say "mock up this flow".
$ npx prototype-lab install-skill
Run the viewer
Comments and element names written in the viewer go straight back to the files. build writes a static copy to hand to anyone.
$ npx prototype-lab dev # http://localhost:6007
What you get
Built for the handoff, not the demo.
Everything the viewer shows comes from the folder, and everything you change in the viewer goes back to it.
Real components
Screens import the project's own shadcn/ui folder, design system or a whole feature module, with the project's stylesheet loaded after the viewer's. The chrome even takes on your shadcn tokens.
States of a screen
20-choose-time.no-slots.tsx is the empty week. States group under their screen in the rail, so a designer flips between filled, empty and error without leaving the screen, at whichever device the toolbar has picked.
Links and hotspots
Give a Button goToScreen(), wrap text in a ScreenLink, or drop a Hotspot over something that is not a control. Hotspots stay invisible until the toggle reveals them, so a static mock reads as one.
Comments pinned to the UI
Pick a component, write the comment, and the viewer saves it to annotations.json in the shape a person hand-writes. No anchor() yet? It writes one into the screen file for you.
Component tree and inspect
The rail lists the screen's components from the live DOM, named the way an engineer will type them: Card > CardHeader > CardTitle. Click a row to outline it, or press i and click the screen.
The canvas
Press v and every screen state is a real, full-page frame on one canvas you pan and zoom, laid out in the flow's columns. a draws an arrow from each control to where it leads, found by clicking, not declared.
A link to one component
Every component can be linked to, named or not: by id, by the path down from the nearest id, or from the screen root. Paste it into a ticket and "this button" means one button.
Storybook links
With the project's Storybook running, each component row opens the page documenting it, read from Storybook's own index. A built copy links only to a deployed one.
Never fails to start
A missing default export, a note pointing at a screen that is gone, an entry screen that is not there: the Problems panel lists them, and the rest of the folder still works.
Device toolbar
Beside Mobile / Tablet / Desktop: the current iPhones and iPads, common desktop sizes, or Responsive. Type a width and height, rotate, zoom to Fit, 100, 75 or 50%. The browser remembers the choice.
Resizable frame
Drag the frame's right edge, bottom edge or corner, and the width snaps to 640, 768, 1024 and 1280 on the way. The handles take the arrow keys too, and a double click resets the size.
Present mode
Press p, or open ?present, and only the screen is shown, at the size chosen in the viewer and scaled to fit the window, so a desktop can present a phone in a call. ?present=fill fills a real phone or tablet instead.
The Dev tab
Inspect an element and the Dev tab shows how it is built: component and source line with Open in editor, styles read back to tokens (a stray value is flagged not a token), size, contrast and keyboard reach, a JSX snippet, and Measure (m) to the next element.
Versions
version-v1 lines in prototype.md add a version picker. States and comments take since and until, screens wrap the difference in <Since>, and ?v=v2 shows what ships in V2.
Guided tours
For a client who will not click around: a tours/*.json file of steps, and a cursor clicks through while a panel says what each step is for. prototype-lab player builds them into one HTML file that opens offline, and the header gets a Tours button.
The canvas
Every screen state on one canvas, and which button goes where.
Press v and each screen becomes a section of real, full-page frames, laid out in the flow's columns. Pan, zoom, pick a frame to open that state, or double-click to put it on the stage. The arrows (a) come from the screens: the viewer renders each one out of sight, clicks every control a person could reach, and records where it went.
- One arrow per destination, dashed when it goes back to an earlier column. Controls that call
back()are listed, with no arrow. - Entry, Unreachable and a red card for a screen id no file defines, so a typo in
goToScreen()is caught before review. - Live frames (
L) click through inside the canvas, and Viewports puts every state in two sizes side by side. - Ready for dev marks a state as ready to build, and PNG saves the picked frame at twice its size.
- Drag a section to move it. The layout, the viewports and the marks are saved to
canvas.json; Reset layout puts it back. - Sixty states stay smooth. Only the frames in view are drawn.
// screens/10-home.tsx — the id the comment points at <Button onClick={() => goToScreen('choose-time')} {...anchor('book-follow-up')}> Book a visit </Button> // annotations.json — written by the viewer, reviewed in the PR { "id": "home-primary-action", "screen": "home", "target": "book-follow-up", "kind": "spec", "title": "One filled button per screen", "body": "Every other action is `ghost`, so the next step is clear.", "author": "Ana" }
Comments and links
Ids are the contract.
anchor('book-follow-up') survives the markup around it changing, which is what keeps a comment attached to the thing it is about. A note whose target has left the screen is listed as Target missing rather than dropped, so you find out when a screen moves out from under a comment.
?component=book-follow-upa component with a semantic id?component=follow-up-card/CardContent/Buttonthe path down from the nearest id above it?component=/Card~1/CardHeader/CardTitlefrom the screen root, when no id is aboveFour kinds, four pin colours: spec flow question todo. Resolve a comment and the id stays; the element keeps its name.
The build-prototype agent skill
Say "mock up this flow" and get a folder that agrees with itself.
The skill walks a coding agent through the work in the right order: ask the designer what it cannot infer, write the doc first, build one file per screen state out of the project's own components, link them, pin the comments, check the arrows on the canvas. It runs only when a person asks for it.
- Reads the setup first: the config, where prototypes live, which component library and stylesheet the screens should use.
- Asks in one message only what it cannot infer: the flow start to finish, which states, what is undecided, which rules the screens cannot show.
- Hands a Figma frame or screenshot back as a reading of the flow to confirm, not a request to retype it.
- Works with Claude Code and any agent that reads a
SKILL.mdfolder.
Commands
Run it, build it, hand it over.
Flags cover a project whose screens work with the defaults. When they need more, add a prototype-lab.config.ts: it is a Vite config, and the prototypeLab() plugin works in any Vite config.
$ prototype-lab devRuns the viewer at localhost:6007. Comments and element names written in the viewer go back to the files. The server takes writes only from the viewer it serves.
$ prototype-lab buildWrites a static, read-only copy to prototype-lab-dist/ to deploy anywhere. It shows comments without offering to write them, and links to Storybook only when the config names a deployed one.
$ prototype-lab previewServes that copy.
$ prototype-lab playerBuilds the guided tours into prototype-lab-player/tours.html, one file that opens offline with a double-click. Add #/check to its address to check every step.
$ prototype-lab install-skillCopies the build-prototype and build-guided-tour skills into .claude/skills, or --target wherever your agent reads them.
$ prototype-lab dev --hostServes the viewer on the network. Open ?present=fill on a phone or tablet and the screen fills its window, with no viewer around it.
$ prototype-lab dev --css ./src/styles.css --storybook http://localhost:6006Every command takes --dir, --css, --storybook, --no-storybook, --no-viewport-switcher, --port, --host, --open and --out-dir.
import path from 'node:path' import { defineConfig } from 'vite' import { prototypeLab } from 'vinta-prototype-lab/vite' export default defineConfig({ plugins: [ prototypeLab({ css: './src/styles.css', // the project's stylesheet, loaded after the viewer's storybook: { url: 'http://localhost:6006', marker: 'Design System' }, // or false viewportSwitcher: false, // one form factor: hide Mobile / Tablet / Desktop }), ], resolve: { alias: { '@': path.resolve(import.meta.dirname, 'src') } }, })
Nothing here ships to a product
Prototypes are synthetic. The folder stays as the record of what was agreed.
No real personal data, no network, no API clients, no auth. When a prototype is agreed, the engineer builds the real screen in the app, and the prototype folder is the spec they built it from.