> ## 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.

After installing the addon, you can generate and refine story files with AI directly inside Storybook.

## Before you begin

* Storybook 8 or higher
* [OpenCode](https://opencode.ai) installed locally

## 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** panel at the bottom of the screen.
  </Step>
</Steps>

## Configure with opencode.json

The addon runs on [OpenCode](https://opencode.ai). Use `opencode.json` to choose your AI provider and model, and to connect the addon to your published component catalog via MCP.

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

| 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`).                                                                        |
| `mcp.loracle` | Give the AI access to your published component catalog so it can look up real components, props, and usage examples when writing stories. See the [MCP guide](/mcp). |

Authenticate your provider after saving:

```bash theme={null}
opencode auth set anthropic
```

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 reads MCP config from `opencode.json` — not `.mcp.json`. This keeps the addon's tool access separate from your coding agents.
</Tip>

## 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, so you don't repeat yourself in every prompt.

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 required.

## Use the chat panel

Open any story and switch to the **Loracle** panel. Describe what you want — the AI edits the story file and Storybook hot-reloads with the result.

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"

## Attach an image

Click the image button in the chat input to attach a screenshot or design mockup. The AI uses it as visual context when generating code. Supported formats: PNG, JPEG, WebP.

## Revert a change

Every AI response snapshots your story file. Hover over any past message to reveal the **Restore** button — clicking it rolls the file back to that point and reloads the page.

## Next steps

<Columns cols={2}>
  <Card title="MCP server" icon="robot" href="/mcp">
    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>