How to build an interactive demo in your repo

Open your last interactive demo in one tab and your live product in another. Count the mismatches. If the answer is anything above zero, the problem is not the demo tool. It is that the demo does not live where the product lives. Here is how to build an interactive demo as code in your repo so it moves with every release instead of drifting behind it.

Pick the product flow that will actually sell the demo

The flow buyers need, not the one you like most

The biggest mistake in an interactive demo workflow is picking the flow you are proud of instead of the flow that proves a buying decision. Ask one question: what does the buyer need to see to believe this solves their problem? That is your flow. Everything else is noise.

For a project management tool, the a-ha moment is not the settings page or the custom fields. It is the moment a task moves from "in progress" to "done" and the dashboard updates in real time. That is the proof. That is what gets captured.

Research from Wes Bush's Product-Led Growth framework shows that focused product walkthroughs, ones that guide users to a single activation milestone, outperform full-product tours on engagement metrics. Shorter usually wins here.

The a-ha moments that deserve screen time

Map the exact moments where the prospect's understanding shifts. For a data pipeline tool, that might be: paste in a CSV, see it clean automatically, see the output schema. Three screens. The rest, like account setup, billing, and integrations, gets cut.

If removing a screen does not reduce comprehension, it was filler. Cut it.

Map the interactive demo before you capture a single screen

What to write down before the capture pass

Before you touch any tool, write the flow in plain language. Four lines:

• Start state — what does the user see when the demo opens?
• Key step — what is the one action that moves them toward the proof?
• Proof moment — where does the value become undeniable?
• End state — what does the demo close on, and what does the CTA ask for?

This is the skeleton for how to build an interactive demo as code, the storyboard before any asset gets captured. If you cannot write these four lines cleanly, you do not know the demo yet.

The moments that get cut because they are filler

Login screens. Loading spinners. Navigation menus that exist to orient the user inside the real app but mean nothing to a prospect. Any screen where the only action is "click Next." These are filler. They add time without adding understanding.

The Nielsen Norman Group's research on user attention is clear: users decide whether to continue within seconds. Every filler screen is a second you are burning on nothing. Cut aggressively. A five-screen demo that lands the proof beats a fifteen-screen tour that loses the viewer at screen eight.

Capture the demo screens in a way your repo can use later

What to capture from the product, and what not to

Capture only what the demo storyboard named. For a code-owned demo, you want assets that can be reused and updated independently, not a monolithic recording that has to be replaced wholesale when one button label changes.

Capture each screen as a discrete asset: a screenshot or HTML snapshot of the exact UI state the demo needs. Capture the proof moment separately from the navigation. If a screen has dynamic data, capture it in a representative state, not live data that will look different tomorrow.

The folder structure that keeps the source clean

A maintainable code-owned demo lives in a folder next to the product. Here's a real layout:

The `/screens` folder is the source of truth for what the product looks like. When the product changes, you update the file in `/screens`, not the entire demo.

What stale UI looks like before it becomes a problem

Say your product renames "Projects" to "Workspaces" in the nav. In a hosted recorder, every screen that shows "Projects" is now wrong, and fixing it means re-recording each one individually. In a repo-native setup, you update the screenshot in `/screens/nav.png`, re-run the agent prompt, and the demo reflects the change. The diff is one file. The PR is one line. The demo stays current.

Keeping demo assets versioned next to product code follows the same basic idea as docs-as-code workflows: when the artifact lives in the repo, it gets reviewed, updated, and shipped with the same discipline as the product itself.

Use one prompt to generate the first interactive demo draft

What the prompt should ask the agent to build

The agent needs four inputs to produce a usable first draft:

• Product flow — the four-line storyboard you wrote before capture
• Target user — who this demo is for and what they care about
• Source assets — the folder path to the captured screens and data
• Output shape — clickable HTML demo, embedded iframe, or standalone page

A prompt that works: "Build a clickable interactive demo using the screens in /demo/assets/screens. The flow is: [paste storyboard]. The viewer is a [role] evaluating whether [product] solves [problem]. Output as a single HTML file in /demo/demo.html with click-through navigation between screens."

Why the first draft should be ugly but real

The agent's first output will have rough transitions, placeholder copy, and probably one broken click target. That is fine. The point of the first draft is speed and structure, a working skeleton you can QA and refine, not a polished final asset. Treat it like a PR from a fast junior engineer: the bones are right, the details need a pass.

Agent-based code generation for UI workflows is a documented operating pattern. Stripe's engineering team describes using AI-generated scaffolding as the starting point for production interfaces, with human review before ship. The same principle applies here.

Store the demo in your repo so releases update it automatically

How the demo lives next to the product code

The demo folder sits in the same repo as the product. When a developer opens a PR that touches the nav, the design system, or any screen the demo uses, the PR description includes a note: "Demo screens affected: /demo/assets/screens/nav.png." The demo update is part of the same review cycle.

This is what makes a repo-native interactive demo different from a hosted recording. The demo is a file your team owns, reviews, and ships, not a snapshot frozen in someone else's platform.

The update loop after a UI change lands

• Product change merges to main.
• Developer or PM re-captures the affected screen(s), one file per screen, not a full re-record.
• Re-prompt the agent: "Update /demo/demo.html. The nav screen has changed — new asset is in /demo/assets/screens/nav.png. Keep all other screens and click targets unchanged."
• Agent outputs the updated demo. QA takes one pass. PR merges.

The whole loop is faster than re-recording a single screen in a hosted tool, and it leaves a diff in version control showing exactly what changed and why.

The ownership rule that makes the whole system work

The demo stays accurate because you own the code and the agent can re-author it. There is no sync button, no webhook to configure, no "refresh from live product" feature to depend on. The update happens because someone on the team treats the demo like code, which it is.

Edit, test, and publish the interactive demo without breaking it

What to QA before anyone sees it

Run through the demo as the buyer would. Check:

• Click order — does every hotspot lead to the right next screen?
• Copy — does every label match the live product exactly?
• Broken states — does any screen show a loading state, an error, or a blank?
• Image load — do all assets resolve, including on a slow connection?
• End state — does the CTA actually work and point to the right URL?

One person doing this pass cold, someone who did not build the demo, catches more than the builder ever will.

The responsive pass for mobile and landing pages

The same demo HTML needs to work in a full-page embed, a landing page iframe, and a mobile viewport. Test all three before publishing. The most common failure is a fixed-width layout that clips on mobile. Fix it with `max-width: 100%` on the demo container and a `viewport` meta tag on the HTML file. This is not a separate maintenance burden if the demo is code: one CSS change, one re-test, done.

Add analytics and role-based variants after the demo is stable

What to measure once the demo is live

Track starts, completions, drop-off by screen, and CTA clicks. Drop-off by screen is the most useful signal. If 60% of viewers exit on screen three, screen three is either confusing or filler. Fix the screen or cut it.

Vanity metrics, like total views and time on page, tell you nothing about whether the demo is doing its job. Completion rate and CTA click-through rate are the two numbers that matter.

When to branch the demo by role or segment

Branch only when the data shows a real drop-off that a different flow would fix, or when a specific segment, like enterprise vs. SMB or technical buyer vs. business buyer, has a materially different proof moment. A variant for enterprise buyers might skip the self-serve signup screen and end on the admin controls. A variant for technical buyers might show the API response instead of the UI.

In a repo-native workflow, a variant is a new file in `/demo/variants/`, with the same base assets but different flow JSON and copy. The agent produces it from one prompt: "Create a variant of /demo/demo.html for enterprise buyers. Replace the self-serve CTA with a 'Talk to sales' button. Swap the final screen to /demo/assets/screens/admin-panel.png."

Where Inkly comes in

The structural problem this workflow solves is ownership. Every hosted demo tool — Supademo, Arcade, Storylane — stores the demo inside their platform. When the product changes, you go back into their editor and fix it there. When a new customer needs a tailored version, you rebuild it there. The demo is theirs to host; the update work is yours to repeat.

Inkly is built on the opposite premise: the demo is code you own, and your coding agent (Cursor, Claude, Codex) maintains it through the three-prompt loop — prompt to create, prompt to update, prompt to produce a variant. The Chrome extension gives you the same fast first capture as Supademo. After that, every update is a new prompt against the existing code, not a re-record from scratch. HTML demos are available from the only tier there is, free, so no Growth plan is required.

The one honest tradeoff: you need a coding agent set up. If you are not already working with Cursor or Claude, the bring-your-own-agent path is extra setup. If you are, vibe-code the demo into your repo and stop rebuilding it every release.

FAQ

Q: What is the fastest reliable workflow to build an interactive demo without rebuilding it every release?

Pick one product flow, write the four-line storyboard, capture each screen as a discrete asset in a repo folder, and use an agent prompt to assemble the demo as HTML. When the product changes, update the affected screen file and re-prompt. The demo changes in one PR, not a full re-record.

Q: How do you turn one product flow into a reusable interactive demo template?

The reusable parts are the flow storyboard, a JSON file, the captured screen assets, one file per screen, the agent prompt template stored in the repo README, and the variant folder structure. A new demo for a different product or segment is a new storyboard plus a re-prompt against the same asset folder.

Q: How can a product engineer create an interactive demo that is maintainable as code?

Store the demo HTML and all source assets in a `/demo` folder in the product repo. Review demo changes in the same PR as the product changes they reflect. Use an agent to re-author the demo when screens change. The diff lives in version control, the update is reviewable, and no one has to remember to sync a hosted tool.

Q: How can a solo builder use AI or a single prompt to generate a credible first draft?

Give the agent four inputs: the product flow storyboard, the target user, the folder path to captured screens, and the desired output format. The first draft will need a QA pass, with broken click targets, rough copy, and placeholder states, but the structure is right and the iteration starts from something real rather than from scratch.

Q: What parts of the product should you capture to make the demo feel valuable instead of gimmicky?

Capture the proof moment and the steps that lead directly to it. Skip login screens, loading states, settings pages, and any navigation that only makes sense inside the live app. A demo that shows three screens and lands the value beats one that shows fifteen screens and loses the viewer before the proof arrives.

Conclusion

If the demo and the product do not live in the same repo, they will drift. Not eventually. On the next release. The fix is not a better hosted tool. It is treating the demo like code: one flow, one source folder, one agent-authored draft, and one update path tied to every PR that touches the product. Pick the flow this week, create the folder, and rebuild the first draft as code. Everything after that is a prompt.