Demos as code

Every team that ships UI more than once a quarter has the same problem: their product video goes stale the moment a feature lands. The dashboard gets a redesign and the onboarding tour points at buttons that don't exist. The release notes carry a screenshot from two redesigns ago. The sales team is using a Loom from a year ago that lives on a former employee's laptop. Every team handles this differently. None of them handle it well.

The fix is structural. Demos shouldn't be a one-off recording. They should be a script under version control that compiles to a polished video on demand. Same source, new build, new video. That's the thesis behind demos as code.

What "as code" actually buys you

When demos live as YAML next to your application code, three things change:

1. Code review. A demo change goes through PR review like any other code. Renamed a button? One-line diff. Removed a feature? The demo's assertVisible step fails CI before the PR merges.
2. Branchability. Working on a feature branch? The demo can branch with the feature. Reverted? The demo reverts. The video and the code travel together.
3. Regeneration. Schedule a re-render against main on a cron, on a tag, on a deploy webhook. Demo content lives in your Git history; the latest video is always one re-run away.

Why a YAML and not a wizard

Hosted demo tools store your demos in their database, behind a hosted WYSIWYG editor. That's a fine UX for a marketer authoring a one-off clip. It's a structural mismatch for a team that wants demos to track their codebase.

A YAML in your repo gives you everything Git already gives you: history, blame, branches, code review, signed commits. We didn't want to reinvent any of those badly.

The compromise

The compromise is that authoring a YAML by hand isn't a great experience. So we layered a Chrome extension that records flows and emits a YAML, plus a typed timeline editor that renders each step as the right form. You author with whatever feels best — a recorder for the first draft, a hand-edit for tightening, an agent for the boilerplate — and the artifact is always a YAML that lives in your repo.

What it looks like

# demos/onboarding.yaml
title: Acme onboarding
preset: iris
aspect: "16:9"
steps:
  - goto: https://app.acme.com
  - click: { role: "button", name: "Get started" }
    caption: "First, click Get started"
  - type: { label: "Workspace name", text: "Acme HQ" }
  - click: { role: "button", name: "Create" }
  - assertVisible: { text: "Welcome to Acme" }

Run it, get an MP4. Re-run it after a redesign, get the new MP4. The cursor finds the right buttons even if their position moved, because targets are semantic, not coordinates.

That's the whole pitch. Demos under version control, regenerating themselves on every UI change. If your team ships UI weekly, this is leverage you don't have today.