Storybook addon

Chat with AI about your components without leaving Storybook. Describe what you want, the AI edits the story file, and Storybook hot-reloads with the result.

The addon runs on OpenCode and connects to your existing AI provider credentials.

Before you begin

Storybook 8 or higher
Node.js 22+
An AI provider subscription (Anthropic, OpenAI, Google, or Amazon Bedrock)

Install the addon

Install the package

npm install @loracle-js/storybook-addon

.storybook/main.ts

const config = {
  addons: [
    // ...other addons
    "@loracle-js/storybook-addon",
  ],
};
export default config;

Start Storybook

Launch Storybook and open the Loracle tab in the bottom panel. Loracle panel closeup

Configure a provider

The addon uses OpenCode to connect to your existing AI provider credentials. If you already have OpenCode configured, the addon picks up your provider automatically — no extra setup needed. To configure a specific provider, create .storybook/opencode.json:

.storybook/opencode.json

{
  "provider": "anthropic",
  "model": "claude-sonnet-4-6"
}

Field	Why you’d set it
`provider`	Choose your AI provider — `anthropic`, `amazon-bedrock`, `openai`, or `google`.
`model`	Pick a specific model (e.g. `claude-sonnet-4-6`, `us.anthropic.claude-sonnet-4-6`, `gpt-4o`, `gemini-2.5-pro`).

Authenticate your provider after saving:

opencode auth login --provider anthropic

See the OpenCode provider guide for authentication setup for all supported providers. Without a config file the addon falls back to the provider already connected in OpenCode. See the OpenCode documentation for all available options.

The addon also reads opencode.json from your project root and merges it with .storybook/opencode.json. The .storybook config takes priority for provider, model, and MCP settings.

Connect Loracle MCP (optional)

Give the AI access to your published component catalog so it can look up real components, props, and usage examples when writing stories. Add MCP config to your .storybook/opencode.json:

Remote (recommended)
Via npx proxy

.storybook/opencode.json

{
  "provider": "anthropic",
  "model": "claude-sonnet-4-6",
  "mcp": {
    "loracle": {
      "type": "remote",
      "url": "https://mcp.getloracle.com",
      "headers": {
        "Authorization": "Bearer <your-api-key>"
      }
    }
  }
}

.storybook/opencode.json

{
  "provider": "anthropic",
  "model": "claude-sonnet-4-6",
  "mcp": {
    "loracle": {
      "type": "local",
      "command": ["npx", "-y", "mcp-remote", "https://mcp.getloracle.com"]
    }
  }
}

See the MCP guide for more details.

The addon reads MCP config from opencode.json — not .mcp.json. This keeps the addon’s tool access separate from your coding agents.

Using the chat panel

Open any story and switch to the Loracle tab. The status bar shows a green Connected indicator and the current story path. Typing a prompt in the chat panel

Example prompts

“Add a disabled state to this button story”
“Create variants for small, medium, and large sizes”
“Style this to match our brand colors”
“Add an interactive form with validation”
“Make this component responsive”

Attach an image

Click the + button in the chat input to pick an image, or paste directly from your clipboard. A thumbnail preview appears before you send. This is one of the most powerful features of the addon — you can turn any visual into a working story built with your design system:

Screenshot to story — paste a screenshot of an existing UI and ask the AI to recreate it as a story using your components
Visual iteration — screenshot a rendered story and ask “make the spacing tighter” or “match this layout instead”

When Loracle MCP is connected, the AI can look up your actual published components, props, and usage examples — so the generated stories use real components from your design system, not generic HTML. Supported formats: PNG, JPEG, WebP, and other browser-supported image types. One image per message. Large images are automatically resized for faster processing.

Revert a change

Every time you send a message, the addon snapshots your story file before the AI responds. Hover over any of your messages to reveal the Restore button — clicking it rolls the file back to that point, removes all subsequent messages from the conversation, and reloads the page.

Safety

The addon applies secure defaults to protect your codebase:

Writes restricted to story files — the AI can only edit *.stories.* files
Bash, web fetch, and web search disabled — prevents unintended side effects
No destructive tools — patch and other filesystem tools are blocked

You can override these defaults by adding a permission field to your .storybook/opencode.json. See the OpenCode documentation for permission configuration.

Guide the AI with AGENTS.md

The addon runs on OpenCode, so it respects standard agent instruction files: AGENTS.md, CLAUDE.md, and others. Use them to set persistent rules for how the AI writes stories. Useful things to include:

Import paths: Where your components live, so the agent doesn’t guess
Story structure: Naming conventions, required exports, file layout
Styling rules: Design tokens over raw CSS, or a specific styling approach
Forbidden patterns: No inline styles, no hardcoded strings, no deprecated APIs

AGENTS.md

# Story guidelines

- Import components from `@acme/ui`, never from internal paths
- Use the `variant` prop for visual styles, not custom CSS
- Every story file must have a default export with `title` and `component`
- Group stories to match the component folder structure (e.g. `Forms/TextInput`)
- Use design tokens from `@acme/theme` for colors and spacing
- Never hardcode text: use descriptive placeholder content

Changes take effect on the next prompt. No restart is required.

Troubleshooting

”Setup required” onboarding screen

The addon couldn’t detect an AI provider. Either:

Create .storybook/opencode.json with your provider and model
Or authenticate via OpenCode: opencode auth login --provider anthropic
See the OpenCode provider guide for all supported providers

Addon panel not showing

Verify the addon is registered in your .storybook/main.ts addons array and restart Storybook.

”Error: fetch failed”

The AI provider couldn’t be reached. Check that:

Your provider credentials are valid — run opencode auth login --provider <provider>
Your API key has available credits
You’re not behind a proxy that blocks the provider’s API

AI can’t edit my files

By default the addon only allows edits to *.stories.* files. If you need broader access, add a custom permission field to your .storybook/opencode.json.

Get started

Products

Storybook addon

Before you begin

Install the addon

Configure a provider

Connect Loracle MCP (optional)

Using the chat panel

Example prompts

Attach an image

Revert a change

Safety

Guide the AI with AGENTS.md

Troubleshooting

”Setup required” onboarding screen

Addon panel not showing

”Error: fetch failed”

AI can’t edit my files

Next steps

MCP server

Loracle CLI

​Before you begin

​Install the addon

​Configure a provider

​Connect Loracle MCP (optional)

​Using the chat panel

​Example prompts

​Attach an image

​Revert a change

​Safety

​Guide the AI with AGENTS.md

​Troubleshooting

​”Setup required” onboarding screen

​Addon panel not showing

​”Error: fetch failed”

​AI can’t edit my files

​Next steps

MCP server

Loracle CLI

Before you begin

Install the addon

Configure a provider

Connect Loracle MCP (optional)

Using the chat panel

Example prompts

Attach an image

Revert a change

Safety

Guide the AI with AGENTS.md

Troubleshooting

”Setup required” onboarding screen

Addon panel not showing

”Error: fetch failed”

AI can’t edit my files

Next steps