> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getloracle.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Storybook addon

> Build and iterate on stories with AI.

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.

<Tip>
  The addon runs on [OpenCode](https://opencode.ai) and connects to your existing AI provider credentials.
</Tip>

![Loracle addon panel in Storybook](https://raw.githubusercontent.com/getloracle/storybook-addon/main/docs-screenshots/final/chat-panel-overview.png)

## Before you begin

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

## Install the addon

<Steps>
  <Step title="Install the package">
    ```bash theme={null}
    npm install @loracle-js/storybook-addon
    ```
  </Step>

  <Step title="Register in your Storybook config">
    ```typescript .storybook/main.ts theme={null}
    const config = {
      addons: [
        // ...other addons
        "@loracle-js/storybook-addon",
      ],
    };
    export default config;
    ```
  </Step>

  <Step title="Start Storybook">
    Launch Storybook and open the **Loracle** tab in the bottom panel.

    ![Loracle panel closeup](https://raw.githubusercontent.com/getloracle/storybook-addon/main/docs-screenshots/final/chat-panel-closeup.png)
  </Step>
</Steps>

## Configure a provider

The addon uses [OpenCode](https://opencode.ai) 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`:

```json .storybook/opencode.json theme={null}
{
  "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:

```bash theme={null}
opencode auth login --provider anthropic
```

See the [OpenCode provider guide](https://opencode.ai/docs/providers) 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](https://opencode.ai/docs) for all available options.

<Tip>
  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.
</Tip>

### 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`:

<Tabs>
  <Tab title="Remote (recommended)">
    ```json .storybook/opencode.json theme={null}
    {
      "provider": "anthropic",
      "model": "claude-sonnet-4-6",
      "mcp": {
        "loracle": {
          "type": "remote",
          "url": "https://mcp.getloracle.com",
          "headers": {
            "Authorization": "Bearer <your-api-key>"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Via npx proxy">
    ```json .storybook/opencode.json theme={null}
    {
      "provider": "anthropic",
      "model": "claude-sonnet-4-6",
      "mcp": {
        "loracle": {
          "type": "local",
          "command": ["npx", "-y", "mcp-remote", "https://mcp.getloracle.com"]
        }
      }
    }
    ```
  </Tab>
</Tabs>

See the [MCP guide](/mcp-server) for more details.

<Tip>
  The addon reads MCP config from `opencode.json` — not `.mcp.json`. This keeps the addon's tool access separate from your coding agents.
</Tip>

## 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](https://raw.githubusercontent.com/getloracle/storybook-addon/main/docs-screenshots/final/chat-prompt-typed.png)

### 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](#connect-loracle-mcp-optional) 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](https://opencode.ai/docs) for permission configuration.

## Guide the AI with AGENTS.md

The addon runs on OpenCode, so it respects standard agent instruction files: [AGENTS.md](https://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

```markdown AGENTS.md theme={null}
# 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](https://opencode.ai/docs/providers) 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`.

## Next steps

<Columns cols={2}>
  <Card title="MCP server" icon="robot" href="/mcp-server">
    Connect your coding agent to the published catalog.
  </Card>

  <Card title="Loracle CLI" icon="upload" href="/cli">
    Publish your design system to make it available via MCP.
  </Card>
</Columns>