UI Demo Scenarios

Storybook add-on style runner for documenting UI flows as standalone HTML pages with a bundled React scenario view.

Install

npm install -D ui-demo-scenarios

The project must already have React and Storybook. The exporter uses Storybook output as the delivery folder, imports .storybook/preview.*, bundles the scenario component, and keeps the preview screen as React while actions are animated.

For AI agents

The package ships a self-contained skill that explains the whole workflow. After install, print it (or save it where your agent looks for context):

npx ui-demo-scenarios skill                          # print to stdout
npx ui-demo-scenarios skill --out .claude/skills      # save as a file

Scenario Structure

Create scenarios near the screen they document. A scenario needs just two files: the scenario itself and a tiny Storybook stories wrapper.

src/pages/payment/__ui_demo_scenarios__/happy-payment/
  payment.demo.scenario.tsx        # config + flow + renderNode, all in one
  payment.demo.scenario.stories.tsx # ~8 lines, only used by Storybook dev

Everything that describes the scenario — id/title/viewports, the flow graph, and how a node renders — lives in one *.demo.scenario.tsx file:

import { defineFlow, type DefineUiDemoScenarioInput } from "ui-demo-scenarios/storybook";
import { PaymentPage } from "../PaymentPage";

type PaymentScenarioState = { amount: string; status: string };

export default {
  id: "happy-payment",
  title: "UI Demo Scenarios/Payment",
  viewports: [{ id: "mobile", title: "Mobile", width: 390, height: 760 }],

  // Transitions live on the node they start from (`on`), keyed by action name.
  // `from` is implied, and `to`/`initialNode` are checked against the real node
  // ids — a typo fails to compile. `interaction` states how it animates.
  flow: defineFlow({
    initialNode: "empty",
    nodes: {
      empty: {
        title: "Empty",
        state: { amount: "", status: "idle" },
        on: {
          submit: { to: "paid", interaction: "click", label: "Pay", path: "happy", target: ".primary" },
        },
      },
      paid: { title: "Paid", state: { amount: "100", status: "done" } },
    },
  }),

  renderNode: ({ node }) => <PaymentPage state={node.state} />,
} satisfies DefineUiDemoScenarioInput<PaymentScenarioState>;

interaction says explicitly how a transition is animated, so behaviour never depends on how you happened to name the action:

• "type" — animate typing/selecting into form fields (diffed from state)
• "click" — move the pointer to target and press it
• "system" — a system/server response, no user interaction

If you omit interaction, the runner falls back to guessing from the action name (type* → typing, resolve*/system* → system, otherwise click). Setting it explicitly is recommended.

A transition only needs to; everything else has a default:

• label defaults to the action name, path defaults to "case".
• One field for the click target (target) and one for behaviour (interaction) — there is no nested demo object to keep in sync.

Each node passes its state explicitly.

initialNode, every transition to, and every flat edge.from/edge.to are type-checked against the real node ids — a mistyped screen name fails to compile and your editor suggests the valid ids.

Splitting config.ts / flows.ts out is optional — do it only when a scenario grows large. The single file above is the recommended default.

Prefer node-centric on, but defineFlow also accepts an explicit flat edge list — defineFlow({ nodes, edges: [{ from, to, action, ... }] }) — with the same node-id checking. Both compile to the same runner manifest.

Describing flows as paths

If you think in user journeys rather than individual arrows, use definePaths. You declare the nodes once and then list whole paths; each path's kind colours all of its steps, from chains through the sequence, and a step shared by two paths is emitted once (keeping the first path's kind):

import { definePaths } from "ui-demo-scenarios/storybook";

flow: definePaths({
  nodes: {
    empty: { title: "Empty", state: paymentFixtures.empty },
    paid: { title: "Paid", state: paymentFixtures.paid },
    failed: { title: "Failed", state: paymentFixtures.failed },
  },
  paths: [
    { kind: "happy", from: "empty", steps: [
      { to: "paid", action: "submit", interaction: "click", label: "Pay", target: ".primary" },
    ] },
    { kind: "error", from: "empty", steps: [
      { to: "failed", action: "decline", interaction: "system", label: "Card declined" },
      { to: "paid", action: "retry", interaction: "click", label: "Retry", target: ".primary" },
    ] },
  ],
});

definePaths compiles to the same flat UiDemoScenarioFlow, so it is a drop-in alternative to defineFlow. from, to, and initialNode are node-id checked the same way.

The stories file is unavoidable Storybook boilerplate (Storybook requires a *.stories.* file, and the exporter ignores it). Keep it minimal:

payment.demo.scenario.stories.tsx:

import { defineUiDemoScenario } from "ui-demo-scenarios/storybook";
import scenarioInput from "./payment.demo.scenario";

export default {
  title: "UI Demo Scenarios/Payment",
  parameters: { layout: "fullscreen" },
};

export const Flow = defineUiDemoScenario(scenarioInput);

Scripts

{
  "scripts": {
    "build-storybook": "storybook build",
    "build-ui-demo-scenarios": "npm run build-storybook && ui-demo-scenarios export"
  }
}

The exported pages are written to:

storybook-static/ui-demo-scenarios/<scenario-id>/index.html

Open that file directly in a browser, no server required.

The standalone page is still a single HTML artifact, but the screen under the runner is rendered through the scenario renderNode function. During generated input/select animations the runner updates intermediate node.state, so derived UI such as card previews, summaries, badges, and validation panels can update like normal React output.

Options

ui-demo-scenarios export \
  --scenarios "src,packages/app/**/*.demo.scenario.tsx" \
  --out storybook-static/ui-demo-scenarios \
  --storybook-preview .storybook/preview.ts

Use --no-storybook-preview if importing your Storybook preview file is not desirable.

Git Ignore

Add these if they are not already ignored:

storybook-static/
.ui-demo-scenario-build/
test-results/
playwright-report/

Current Constraints

Scenario files are imported by the exporter in Node through tsx to read flow metadata, and then bundled by Vite for the standalone React view. Keep browser-only APIs, Next router hooks, network calls, and app providers mocked inside the scenario wrapper, just like you would do for Storybook.