AI-powered Storybook story generator for any JavaScript framework and design system

Story UI generates working Storybook stories from natural language. Describe what you want, and the AI writes production-ready story code using your design system's actual components. Works with any framework and any component library.

• Design-System Agnostic: React, Vue, Angular, Svelte, Web Components — bring your own component library
• Multi-Provider AI: Claude, OpenAI, or Gemini with automatic model selection
• Self-Healing Generation: Validates generated code with TypeScript AST parsing and auto-corrects errors through an LLM retry loop
• Voice Canvas: Speak your component ideas and see them rendered live in Storybook
• Storybook MCP Integration: Fetches component docs and story patterns from Storybook's MCP addon for higher-quality output
• Zero Lock-in: Use Mantine, Vuetify, Angular Material, Shoelace, shadcn/ui, or your own components

# Install Story UI
npm install -D @tpitre/story-ui

# Initialize in your project
npx story-ui init

# Start generating stories
npm run story-ui

Story UI will guide you through:

1. Selecting your JavaScript framework
2. Choosing a design system (or using your own)
3. Configuring your preferred AI provider
4. Setting up component discovery

Describe what you want in natural language. Story UI generates complete, working Storybook stories using your design system's components with proper imports, props, and TypeScript types.

When generated code has syntax errors, invalid imports, or forbidden patterns, Story UI automatically:

1. Validates with TypeScript AST parsing and pattern checking
2. Sends errors back to the LLM with correction context
3. Retries up to 3 times, tracking error history to detect stuck loops
4. Selects the best attempt if all retries fail

Every generated story is deterministically validated against an import allowlist: your design system's package (including scoped siblings and subpaths), the framework runtime, Storybook packages, and your configured icon package. The AI cannot introduce Tailwind, shadcn/ui, Radix, or any other library on its own — the only way to permit an additional package is to name it explicitly in story-ui-considerations.md (e.g. "Allowed additional imports: @tabler/icons-react"). Violations are caught before the file is written and routed through self-healing.

A live playground mode where you speak component ideas and see them rendered instantly in Storybook. Uses browser speech recognition with auto-submit, streams generated code into the canvas in real time as the LLM produces it, and renders output through an iframe with react-live. Stories saved from the canvas carry a microphone marker in the panel's story list, so you can tell voice-created stories apart from chat-generated ones.

The panel is a real back-and-forth chat: the AI summarizes what it built, offers follow-up suggestions, and you refine in plain language. Generated stories appear in Storybook's sidebar without a page reload — click Open in Storybook to jump straight to the new story while keeping your conversation intact.

It works in the other direction too: when viewing any generated story, an Edit in Story UI button in Storybook's toolbar takes you back to that story's chat, ready to keep iterating (Storybook 9+).

Attach screenshots or mockups to your prompt. The AI uses them as reference when generating components.

• Edit, delete, and organize generated stories from the panel
• Orphan detection for stories without chat history
• File-based manifest system for tracking generated assets

Reference showcase environments — the combinations we develop and test against, chosen for component breadth so Story UI can compose virtually any layout for any industry (fintech dashboards, e-commerce, marketing pages):

Story UI is not limited to published packages. Components in local project directories (src/components, src/ui, or a configured componentsPath) are discovered automatically — including their prop types, extracted straight from your source — listed to the AI as first-class "custom project components", and imported into generated stories via their real relative paths. Off-the-shelf and custom components compose together in the same story.

npx story-ui init

The installer prompts for:

1. Framework — React, Vue, Angular, Svelte, or Web Components
2. Design System — framework-specific options (Mantine, Vuetify, Angular Material, etc.)
3. AI Provider — Claude (recommended), OpenAI, or Gemini
4. Configuration — paths, ports, and API keys

Create story-ui.config.js in your project root:

module.exports = {
  // Framework: 'react' | 'vue' | 'angular' | 'svelte' | 'web-components'
  componentFramework: 'react',

  // Component library import path
  importPath: '@mantine/core',

  // Generated stories location
  generatedStoriesPath: './src/stories/generated/',

  // LLM provider: 'claude' | 'openai' | 'gemini'
  llmProvider: 'claude',

  // Import style: 'barrel' (default) or 'individual'
  // Use 'individual' for libraries without barrel exports (shadcn/ui, Radix Vue, Angular Material)
  // Use 'barrel' for libraries with index.ts barrel exports (Mantine, Chakra, Vuetify)
  importStyle: 'barrel',

  // Story configuration
  storyPrefix: 'Generated/',
  defaultAuthor: 'Story UI AI',

  // Layout rules for multi-component compositions
  layoutRules: {
    multiColumnWrapper: 'SimpleGrid',
    columnComponent: 'div',
    containerComponent: 'Container',
  },
};

For component libraries with non-standard import paths, use importExamples to teach the AI your patterns:

module.exports = {
  framework: 'web-components',
  importPath: '../../../components',

  importExamples: [
    "import '../../../components/button/button'; // For <my-button>",
    "import '../../../components/card/card'; // For <my-card>",
  ],
};

Start the Story UI server:

npm run story-ui

Open Storybook and navigate to the Story UI panel. Describe what you want:

Create a product card with image, title, price, and add to cart button

Story UI generates a complete .stories.tsx file using your design system's components, writes it to your generated stories directory, and Storybook indexes it live — no page reload. The chat replies with a summary of what was built and an Open in Storybook link that navigates directly to the new story.

Continue the conversation to refine:

Make the button green and add a quantity selector

Story UI modifies only what you requested, preserving the rest of the story.

Coming back later? Open any generated story and click Edit in Story UI in the toolbar — the panel opens with that story's conversation loaded.

Switch to Voice Canvas mode in the panel header. Speak your component ideas and see them rendered live. The canvas uses react-live for instant rendering without page reloads.

Story UI can connect to Storybook MCP (@storybook/addon-mcp) to fetch component documentation, UI building guidelines, and existing story patterns. This enhances generation quality by ensuring output matches your codebase.

1. Install @storybook/addon-mcp and enable experimentalComponentsManifest in .storybook/main.js:

export default {
  features: {
    experimentalComponentsManifest: true,
  },
  addons: [
    '@storybook/addon-mcp',
    // ... other addons
  ],
};

2. Add the Storybook URL to story-ui.config.js:

module.exports = {
  // ... other config
  storybookMcpUrl: 'http://localhost:6006',
  storybookMcpTimeout: 5000,
};

When both Story UI and Storybook are running, context is fetched automatically during generation, resulting in more accurate component usage and consistent code style.

Zero-config option: the panel's "Storybook MCP" toggle sends your Storybook's own URL with each request, so the addon works without setting storybookMcpUrl at all. With experimentalComponentsManifest enabled, Story UI also pulls the components manifest — curated story snippets and extracted props per component — which is the deepest knowledge source available for compiled component libraries.

Story UI includes a Model Context Protocol (MCP) server for direct integration with AI clients like Claude Desktop and Claude Code.

1. Open Claude Desktop > Settings > Connectors
2. Click Add custom connector
3. Enter your deployment URL + /mcp-remote/mcp
4. Restart Claude Desktop

# Production deployment
claude mcp add --transport http story-ui https://your-app.up.railway.app/mcp-remote/mcp

# Local development
claude mcp add --transport http story-ui-local http://localhost:4001/mcp-remote/mcp

Once connected, these tools are available in Claude conversations:

• generate-story — Generate Storybook stories from natural language
• list-components — Discover available components
• list-stories — View existing generated stories
• get-story / update-story / delete-story — Manage stories
• get-component-props — Get component property information
• test-connection — Verify MCP connection

For Claude Desktop local integration without a deployed server:

{
  "mcpServers": {
    "story-ui": {
      "command": "npx",
      "args": ["@tpitre/story-ui", "mcp"]
    }
  }
}

This requires the HTTP server running on port 4001 (npm run story-ui).

Story UI can be deployed as a standalone web application. Railway is recommended for its simplicity.

npm install -g @railway/cli
railway login
railway init
railway up

Environment Variables:

• ANTHROPIC_API_KEY — Required for Claude models
• OPENAI_API_KEY — Optional, for OpenAI models
• GEMINI_API_KEY — Optional, for Gemini models
• STORYBOOK_PROXY_ENABLED — Enable Storybook proxy mode for live demos
• STORYBOOK_PROXY_PORT — Internal Storybook port (default: 6006)

See DEPLOYMENT.md for detailed instructions and troubleshooting.

Story UI reads two knowledge sources before every generation. They serve different purposes:

Create a story-ui-docs/ directory with guidelines, tokens, and component documentation. Story UI ingests Markdown, MDX, JSON, YAML, XML, HTML, and plain text — drop in exported design tokens or docs in whatever format you already have:

story-ui-docs/
├── guidelines/
│   ├── accessibility.md
│   └── responsive-design.md
├── tokens/
│   ├── colors.yaml
│   └── spacing.json
└── components/
    ├── button.md
    └── forms.mdx

Large files are truncated to a per-file budget with a total cap, and the cache invalidates automatically when any nested file changes.

Rules for how the AI must treat your design system: component preferences, prop conventions, things to avoid. This file is also the only mechanism for permitting imports outside your design system — a package mentioned here (e.g. @tabler/icons-react) passes import isolation; anything unmentioned is rejected.

npx story-ui init          # Initialize Story UI in your project
npx story-ui start         # Start the MCP server (default port: 4001)
npx story-ui mcp           # Start STDIO MCP server for Claude Desktop
npx story-ui status        # Check installation status and version
npx story-ui update        # Update Story UI files to latest version

# .env
LLM_PROVIDER=claude
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...         # optional
GEMINI_API_KEY=...            # optional
VITE_STORY_UI_PORT=4001

All endpoints are also available under the /story-ui/ prefix.

{
  prompt: string;           // User's request
  provider?: string;        // 'claude' | 'openai' | 'gemini'
  model?: string;           // Specific model ID
  previousCode?: string;    // For iterations
  history?: Message[];      // Conversation history
  imageData?: string;       // Base64 image for vision
}

We welcome contributions! See our Contributing Guide.

git clone https://github.com/southleft/story-ui.git
cd story-ui
npm install
npm run build

# Test in a consumer project (important: run from the consumer directory)
cd /path/to/your-storybook-project
PORT=4001 node /path/to/story-ui/dist/mcp-server/index.js

MIT - Story UI Contributors

• GitHub Repository
• NPM Package
• Deployment Guide
• MCP Integration Guide
• Issues & Support