React 19 · any bundler, Vite comes along · MIT

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.

Read the README
Prototype Lab Book a follow-up visit· In review MobileTabletDesktop Mobile default 390844 Fit Canvas v Inspect i Hotspots h Comments c Tours
390 × 844 · Mobile default · 82%

Good morning

Dana

2 tasks2
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 visit1
Refill: Lisinopril

Two refills left. Your pharmacy has the request.

View medication
Intake questions

Four questions left from your last visit.

Continue
#/p/patient-booking/home?component=book-follow-up
3things in a folder: the doc, the screens, the comments. Add the folder and the viewer picks it up.
1file per screen state. 20-choose-time.no-slots.tsx is the empty week.
0registry to edit, mocks to maintain, or fake components. Screens import the real ones.
∞deep links: every screen, state and component has a URL to paste into a ticket.

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.json from the viewer.
  • prototype.md sits 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
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.

01 · INSTALL

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
02 · WRITE

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
03 · CLICK THROUGH

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.

c comments h hotspots i inspect v canvas a arrows f canvas with arrows m measure p present [ ] close either side Esc clear the pick, stop presenting

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.
Canvaspatient-booking · 5 states · 62%Arrows aLiveViewportsReady for devPNGReset layout
EntryHomeBook a visit → Choose time
Choose timedefault9:00 AM, 9:30 AM +4 → Review
Choose timeno-slotsCall the clinic → Review
Ready for devReviewConfirm → Confirmed · Previous screen
ConfirmedReschedule → Choose time · Back to home
Missingcalenderno file defines it
annotations.json · screens/10-home.tsx
// 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 above

Four 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.md folder.
zsh

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 dev

Runs 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 build

Writes 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 preview

Serves that copy.

$ prototype-lab player

Builds 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-skill

Copies the build-prototype and build-guided-tour skills into .claude/skills, or --target wherever your agent reads them.

$ prototype-lab dev --host

Serves 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:6006

Every command takes --dir, --css, --storybook, --no-storybook, --no-viewport-switcher, --port, --host, --open and --out-dir.

prototype-lab.config.ts
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.

Open the worked example Read the skill