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

​
Before you begin

  • Storybook 8 or higher
  • OpenCode installed locally

​
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 runs on OpenCode. 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": "local",
      "command": ["npx", "-y", "mcp-remote", "https://mcp.getloracle.com"]
    }
  }
}
FieldWhy you’d set it
providerChoose your AI provider — anthropic, amazon-bedrock, openai, or google.
modelPick a specific model (e.g. claude-sonnet-4-6, us.anthropic.claude-sonnet-4-6, 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 set 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, 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
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 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

MCP server

Connect your coding agent to the published catalog.

Loracle CLI

Publish your design system to make it available via MCP.