AI-powered Storybook story generator for any JavaScript framework

Story UI revolutionizes component documentation by automatically generating Storybook stories through AI-powered conversations. Works with any framework (React, Vue, Angular, Svelte, Web Components) and any LLM provider (Claude, OpenAI, Gemini).

• Framework Agnostic: Works with React, Vue, Angular, Svelte, and Web Components
• Multi-Provider AI: Choose between Claude, OpenAI, or Google Gemini - always using the latest models
• Design System Aware: Learns your component library and generates appropriate code
• Production Ready: Deploy as a standalone web app with full MCP integration
• Zero Lock-in: Use any component library - Mantine, Vuetify, Angular Material, Shoelace, or your own

# 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

• AI-Powered Story Generation: Describe what you want in natural language
• Intelligent Iteration: Modify existing stories without losing your work
• Real-time Preview: See generated stories instantly in Storybook
• TypeScript Support: Full type-aware story generation
• Vision Support: Attach screenshots for visual component requests

• Edit Existing Stories: Modify any generated story through conversation
• Delete Stories: Remove stories directly from the Story UI panel
• Orphan Detection: Find and clean up stories without associated chat history
• Full MCP Integration: Manage stories via Claude Desktop or any MCP-compatible client

• Railway: Node.js backend with file-based story persistence
• MCP Integration: Connect AI clients directly to production

npx story-ui init

The interactive installer will ask:

1. Framework Selection

   ? Which JavaScript framework are you using?
     > React
       Vue
       Angular
       Svelte
       Web Components
   

2. Design System Selection (varies by framework)

   # For React:
   ? Choose a design system:
     > Mantine - Most Popular
       Chakra UI
       Material UI
       Custom
   
   # For Vue:
   ? Choose a design system:
     > Vuetify - Most Popular
       Custom
   
   # For Angular:
   ? Choose a design system:
     > Angular Material - Most Popular
       Custom
   

3. AI Provider Selection

   ? Which AI provider do you prefer?
     > Claude (Anthropic) - Recommended
       OpenAI
       Google Gemini
   
   ? Enter your API key:
   

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

export default {
  // Framework: 'react' | 'vue' | 'angular' | 'svelte' | 'web-components'
  framework: 'react',

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

  // Path to custom components
  componentsPath: './src/components',

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

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

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

For component libraries with non-standard import paths (especially Web Components with local imports), use importExamples to teach the AI your import patterns:

export default {
  framework: 'web-components',
  importPath: '../../../components',

  // Teach the AI your library's import structure
  importExamples: [
    "import '../../../components/button/button'; // For <my-button>",
    "import '../../../components/card/card'; // For <my-card>",
    "import '../../../components/icon/icons/check'; // For <my-icon-check>",
  ],

  // ... other config
};

The AI uses these examples to understand your component library's folder structure and generate correct imports.

Start the Story UI server:

npm run story-ui

Then describe what you want:

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

Story UI generates:

export const ProductCard = {
  render: () => (
    <Card shadow="sm" padding="lg" radius="md" withBorder>
      <Card.Section>
        <Image src="https://example.com/product.jpg" height={160} alt="Product" />
      </Card.Section>
      <Group justify="space-between" mt="md" mb="xs">
        <Text fw={500}>Product Name</Text>
        <Badge color="pink">On Sale</Badge>
      </Group>
      <Text size="sm" c="dimmed">$29.99</Text>
      <Button color="blue" fullWidth mt="md" radius="md">
        Add to Cart
      </Button>
    </Card>
  )
};

Continue the conversation to refine:

You: "Make the button green and add a quantity selector"

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

Vue Example:

You: "Create a user profile card with avatar, name, and edit button"

Generates Vue template:

<template>
  <v-card class="mx-auto" max-width="400">
    <v-card-item>
      <v-avatar size="80">
        <v-img src="https://example.com/avatar.jpg" alt="User" />
      </v-avatar>
      <v-card-title>John Doe</v-card-title>
      <v-card-subtitle>Software Engineer</v-card-subtitle>
    </v-card-item>
    <v-card-actions>
      <v-btn color="primary" variant="outlined">Edit Profile</v-btn>
    </v-card-actions>
  </v-card>
</template>

Angular Example:

You: "Create a data table with sorting and pagination"

Generates Angular component:

@Component({
  selector: 'app-data-table',
  template: `
    <mat-table [dataSource]="dataSource" matSort>
      <ng-container matColumnDef="name">
        <mat-header-cell *matHeaderCellDef mat-sort-header>Name</mat-header-cell>
        <mat-cell *matCellDef="let element">{{element.name}}</mat-cell>
      </ng-container>
      <!-- Additional columns -->
    </mat-table>
    <mat-paginator [pageSizeOptions]="[5, 10, 25]" showFirstLastButtons />
  `
})
export class DataTableComponent { }

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

The easiest way to connect is via Claude Desktop's built-in connector UI:

1. Open Claude Desktop
2. Go to Settings → Connectors
3. Click "Add custom connector"
4. Enter:
   • Name: Story UI React (or any descriptive name)
   • URL: Your deployed Railway URL + /mcp-remote/mcp
     • Example: https://your-app-name.up.railway.app/mcp-remote/mcp
5. Click Add
6. Restart Claude Desktop

Note: The URL will be your own Railway deployment URL. See Production Deployment to set up your instance.

Multiple Projects: If you have multiple Storybook projects, add a separate connector for each:

• Story UI React → https://my-react-app.up.railway.app/mcp-remote/mcp
• Story UI Vue → https://my-vue-app.up.railway.app/mcp-remote/mcp

Once connected, you'll have access to all Story UI tools directly in your Claude conversations:

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

Connect via Claude Code's built-in MCP support:

# Add your production Railway deployment
claude mcp add --transport http story-ui-react https://your-react-app.up.railway.app/mcp-remote/mcp

# Add another project (if needed)
claude mcp add --transport http story-ui-vue https://your-vue-app.up.railway.app/mcp-remote/mcp

# For local development (default port is 4001)
claude mcp add --transport http story-ui-local http://localhost:4001/mcp-remote/mcp

For running multiple local Story UI instances with different ports, configure your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "story-ui-react": {
      "command": "npx",
      "args": ["@tpitre/story-ui", "start", "--port", "4001"]
    },
    "story-ui-vue": {
      "command": "npx",
      "args": ["@tpitre/story-ui", "start", "--port", "4002"]
    },
    "story-ui-angular": {
      "command": "npx",
      "args": ["@tpitre/story-ui", "start", "--port", "4003"]
    }
  }
}

Note: When using Claude Desktop, API keys are managed through your Anthropic account - no need to configure them in the MCP server.

# Start with default port (4001)
npx story-ui start

# Or specify a custom port
npx story-ui start --port 4002

This starts the Story UI HTTP server with MCP endpoint at http://localhost:<port>/mcp-remote/mcp.

Once connected, you can use these commands in Claude Desktop:

• "Use Story UI to create a hero section with a CTA button"
• "List all available components in Story UI"
• "Generate a dashboard layout with sidebar navigation"
• "Show me the stories I've generated"

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

When Story UI detects a running Storybook instance with the MCP addon, it automatically fetches:

• Component Documentation: Props, descriptions, and usage examples for all components
• UI Building Instructions: Storybook-specific guidelines for writing stories
• Story Patterns: Existing story examples to match code style and conventions

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

export default {
  // ... other config options

  // Storybook MCP integration
  storybookMcpUrl: 'http://localhost:6006',  // Your Storybook URL
  storybookMcpTimeout: 5000,                  // Timeout in ms (default: 5000)
};

1. Storybook 8.4+ with @storybook/addon-mcp installed
2. experimentalComponentsManifest: true enabled in .storybook/main.js:

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

When both Story UI and Storybook are running, context is fetched automatically during story generation:

🔗 Fetching context from Storybook MCP: http://localhost:6006
✅ Storybook MCP context fetched in 2226ms
   - Component docs: 43 components
   - UI building instructions: available
   - Story patterns: 10 examples

This context is injected into the AI prompt, resulting in:

• More accurate component prop usage
• Consistent code style with existing stories
• Proper import statements matching your project

Story UI can be deployed as a standalone web application accessible from anywhere. We recommend Railway for its ease of use, but any Node.js hosting platform will work.

┌─────────────────────────────────────────────────────────────┐
│                    Your Deployment (e.g., Railway)           │
│  ┌─────────────────────────────────────────────────────────┐│
│  │              Express MCP Server (Node.js)                ││
│  │  - Serves Storybook with Story UI addon                  ││
│  │  - API routes for story generation                       ││
│  │  - Multi-provider LLM support (Claude, OpenAI, Gemini)   ││
│  │  - File-based story persistence                          ││
│  └─────────────────────────────────────────────────────────┘│
└──────────────────────────────────────────────────────────────┘

Railway provides a straightforward deployment experience with automatic HTTPS and file-based story persistence.

Quick Start:

# Install Railway CLI
npm install -g @railway/cli
railway login

# Initialize and deploy from your Storybook project
railway init
railway up

Environment Variables (set in Railway Dashboard):

• ANTHROPIC_API_KEY - Required for Claude models
• OPENAI_API_KEY - Optional, for OpenAI models
• GEMINI_API_KEY - Optional, for Gemini models

After Deployment:

Your Railway app will have a URL like https://your-app-name.up.railway.app. Use this URL to connect MCP clients:

# In Claude Code
claude mcp add --transport http story-ui https://your-app-name.up.railway.app/mcp-remote/mcp

Or add it to Claude Desktop via Settings → Connectors → Add custom connector.

Important for Storybook Live Mode Deployments:

If deploying Storybook with Story UI integrated (where users can generate stories in the deployed app), ensure the StoryUI panel files are committed to git:

# Check if StoryUI is incorrectly gitignored
grep "StoryUI" .gitignore

# If found, remove from .gitignore and commit the panel
git add src/stories/StoryUI/
git commit -m "Add StoryUI panel for production"

Note: Story UI versions prior to 4.10.0 incorrectly added src/stories/StoryUI/ to .gitignore. See DEPLOYMENT.md for full instructions.

See DEPLOYMENT.md for detailed deployment instructions and troubleshooting.

Story UI can learn your design system conventions to generate better stories.

Create a story-ui-docs/ directory:

story-ui-docs/
├── README.md                    # Overview
├── guidelines/
│   ├── accessibility.md         # A11y guidelines
│   ├── responsive-design.md     # Responsive rules
│   └── brand-guidelines.md      # Brand usage
├── tokens/
│   ├── colors.json             # Color tokens
│   ├── spacing.md              # Spacing system
│   └── typography.json         # Typography
├── components/
│   ├── button.md               # Button documentation
│   └── forms.md                # Form patterns
└── patterns/
    ├── layouts.md              # Layout patterns
    └── data-tables.md          # Table patterns

For simpler setups, use story-ui-considerations.md:

# Design System Considerations

## Color Usage
- Primary actions: blue.6
- Destructive actions: red.6
- Success states: green.6

## Component Preferences
- Use Button with variant="filled" for primary actions
- Use Card with shadow="sm" for content containers

For libraries where components have specific requirements (like attributes needed for visibility), document these behaviors:

# Component-Specific Behaviors

## Alert Component (`<my-alert>`)
**IMPORTANT**: The alert requires `is-active` attribute to be visible.

<!-- WRONG - will not render -->
<my-alert variant="success">Message</my-alert>

<!-- CORRECT -->
<my-alert variant="success" is-active>Message</my-alert>

## Import Patterns
Components are in individual folders:
- import '../../../components/alert/alert';
- import '../../../components/icon/icons/check';

The AI reads this file before every story generation, ensuring component-specific rules are followed.

# Initialize Story UI in your project
npx story-ui init

# Start the MCP server (default port: 4001)
npx story-ui start
npx story-ui start --port 4002  # Custom port

# Run MCP STDIO server (for Claude Desktop local integration)
npx story-ui mcp

# Check installation status and version
npx story-ui status

# Update Story UI files to latest version
npx story-ui update

To completely remove Story UI from your project and start fresh:

# Remove Story UI configuration and panel files
rm -f story-ui.config.js
rm -f story-ui-considerations.md
rm -rf story-ui-docs/
rm -rf src/stories/StoryUI/
rm -rf src/stories/generated/

# Remove package.json script entries (manual)
# Delete "story-ui" and "storybook-with-ui" from scripts

# Optionally remove the package
npm uninstall @tpitre/story-ui

# Optionally clean .env (remove VITE_STORY_UI_PORT, API keys)

After removal, run npx story-ui init to start fresh with a clean installation.

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

Story UI v4 is backwards compatible with previous configurations. However, to take advantage of new features:

1. Multi-Provider Support: Add llmProvider to your config
2. Framework Detection: Add framework to your config for non-React projects
3. Production Deployment: Use npx story-ui deploy for one-command deployment

No breaking changes - existing stories and configurations will continue to work.

We welcome contributions! See our Contributing Guide.

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

# Test in a project
cd your-project
npm link @tpitre/story-ui

MIT © Story UI Contributors

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

Story UI - Making component documentation delightful, one conversation at a time.