Skip to main content
After installing the addon, you can generate and refine story files with AI directly inside Storybook.
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

1

Install the package

npm install @loracle-js/storybook-addon
2

Register in your Storybook config

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

Start Storybook

Launch Storybook and open the Loracle panel at the bottom of the screen.

​
Configure with opencode.json

The addon uses OpenCode to connect to your provider. Use opencode.json to choose your AI provider and model, and to connect the addon to your published component catalog via MCP.
opencode.json
{
  "provider": "anthropic",
  "model": "claude-sonnet-4-6",
  "mcp": {
    "loracle": {
      "type": "remote",
      "url": "https://mcp.getloracle.com",
      "headers": {
        "Authorization": "Bearer <your-api-key>"
      }
    }
  }
}
FieldWhy you’d set it
providerChoose your AI provider: anthropic, amazon-bedrock, openai, or google.
modelPick a specific model, such as claude-sonnet-4-6, us.anthropic.claude-sonnet-4-6, or gpt-4o.
mcp.loracleGive 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.
Authenticate your provider after saving: 
opencode auth login --provider anthropic
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 reads MCP config from opencode.json, not .mcp.json. This keeps the addon’s tool access separate from your coding agents.

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

​
Use the chat panel

Open any story and switch to the Loracle panel. Describe what you want, and the AI edits the story file while 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, and 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.

​
Troubleshooting

​
”Setup required” onboarding screen

The addon couldn’t detect an AI provider. Either:
  • Create 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

​
”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 opencode.json.

​
Next steps

MCP server

Connect your coding agent to the published catalog.

Loracle CLI

Publish your design system to make it available via MCP.