Building an AI-Powered Flow Builder for Storybook

I built a Storybook addon that turns plain-English descriptions into composed, interactive UI flows — rendered with your actual components. Type something like “User logs in, sees an error on bad credentials, then lands on a welcome page” and the addon reads your component library, composes multiple atomic components into realistic screen layouts, and renders live previews you can step through.

Here’s what I learned shipping it.

The idea

Design systems have a gap between individual component stories and real product screens. Storybook is great at showcasing a Button or a TextInput in isolation, but when you want to see how a login form actually looks — with FormField wrapping TextInput, an Alert for errors, and a Button to submit — you’re on your own.

I wanted Claude to bridge that gap: give it a component library and a user journey, and have it compose those atomic pieces into complete screens.

How it works

The addon runs entirely in the browser. No backend. It reads your Storybook story index to discover your component library, sends it to Claude along with your flow description, and gets back a structured JSON plan. Each step in the plan contains a layout tree — a nested structure of your components and HTML wrappers that describes a complete screen.

The layout tree gets rendered as a live preview inside an iframe, using your actual component code served through Vite’s dev server. It’s not a mockup or a screenshot — it’s your real components with real props, composed together.

The default screen of Flow Builder

Generating a flow for the prompt: “User logs in with email and password, sees an error on bad credentials, then sees a welcome page with their avatar”

The output. Composing flows from your existing components.

The interesting AI problems

Getting Claude to compose, not just pick

The first version mapped each flow step to a single existing component. Step 1? That’s a TextInput. Step 2? That’s an Alert. The preview showed one isolated component per step, which wasn’t useful.

The fix was changing the output format from “pick a component” to “compose a layout tree.” Instead of { componentName: "TextInput", storyId: "..." }, Claude now outputs nested trees:

{
  "component": "div",
  "props": { "style": { "padding": 32, "maxWidth": 400 } },
  "children": [
    { "component": "FormField", "props": { "label": "Email" },
      "children": [
        { "component": "TextInput", "props": { "type": "email" } }
      ]
    },
    { "component": "Button", "props": { "label": "Sign In", "primary": true } }
  ]
}

This was a much better abstraction. Each step now looks like a real product screen.

The lazy path problem

Once Claude had access to high-level Page/Header components from Storybook’s boilerplate, it would just wrap everything in <Page> and call it done. Every step rendered the same generic "Pages in Storybook" content.

The fix was two-part: filter out page-level components from the library discovery (anything under Example/ or Configure/), and add explicit rules to the prompt forbidding page shells. Once the only building blocks available were atomic components, Claude had no choice but to compose.

Children vs props

After adding a prompt rule telling Claude to use children for text content (to fix empty Alert components), all the Button components went blank. Button uses a label prop, not children. The rule was too broad.

The lesson: when you’re prompting an LLM to generate structured output against a real component API, you need to be specific about which components use which patterns. A generic rule like “use children for text” will break components that don’t follow that pattern. The fix was spelling out both cases with examples.

Truncated JSON

Layout trees are verbose. A 5-step e-commerce flow with composed screens easily exceeds 4K tokens of JSON. The first version had max_tokens: 4096 which silently truncated the response, producing invalid JSON and a parse error. Bumping to 16K fixed it, but it's a reminder that structured output from LLMs needs headroom.

Prompt engineering as API design

The system prompt for this addon is essentially an API contract. It defines:

• A schema (LayoutNode trees with specific fields)
• Constraints (use exact component names, no page shells, children vs props)
• UX principles (7 named principles that must appear in rationale)
• Worked examples (a complete login flow showing correct output)
• Negative examples (common mistakes to avoid)

Getting this right was iterative. Each generation that produced unexpected output led to a new rule or example in the prompt. The prompt is now ~3K tokens — substantial, but it produces consistent, usable output.

The key insight: treating prompt engineering like API design (with schemas, examples, and error cases) produces much more reliable results than vague instructions.

What’s next

The generated story files include proper imports and render functions, so the flows become permanent fixtures in your Storybook. The obvious next step is generating actual interaction tests (the play functions are currently TODOs) and supporting more complex state management across steps.

The code is open source: github.com/rebeccarich/storybook-addon-flow-builder