Problem
When an agent writes frontend code in this repo, it has no machine-readable way to learn which components exist or how to use them. It falls back to reading component source to guess props and patterns, which burns tokens and produces rework: duplicated components, wrong props, hand-rolled values where tokens belong. Humans review out the damage afterwards.
Our existing tooling covers the verification side (visual-contract harness, CDP-based Storybook smoke, a11y tree audit, file-level Astryx surface inventory). The production side — "what can I reuse and how do I use it" — has no agent-facing interface.
External evidence that closing this gap pays off: BILL's A/B experiment grounding agents in their design system cut token usage 31–63% per task and improved first-pass component fidelity (https://www.bill.com/engineering/how-we-made-our-design-system-bilingual).
Desired outcome
An agent doing UI work queries the design system before writing code: list available components, read props and usage docs, and later run interaction tests on its own stories.
Concretely:
- Install
@storybook/addon-mcp (official, self-hosted: it serves our own Storybook at http://localhost:6006/mcp, no third-party service).
- Register the MCP endpoint in our agent configurations and add usage guidance to
AGENTS.md (query docs before writing frontend code).
- Start with the docs toolset only.
Follow-up, not in scope: the testing toolset (run-story-tests) needs @storybook/addon-vitest; adopt once the MCP feature leaves preview.
Alternatives or workarounds
- Status quo: agents grep source. Works, but this is exactly the expensive path the BILL numbers measure.
- Wrap our own surface-inventory generator as a custom MCP server: same idea, more to build and maintain; the official addon is configuration, not construction.
- Wait until the feature leaves preview: viable; the proposal limits exposure to the docs toolset, and the addon is dev-only tooling that is trivial to remove.
Risk: Storybook's MCP/manifests are in preview; the API may change. Exposure is limited to a dev dependency plus agent config.
中文对照
问题：Agent 写前端时没有机器可读的方式了解有哪些现成组件、怎么用，只能翻源码猜，费 token 且产出需要返工（重复造组件、props 用错、绕过 token 手写样式）。现有工具链只覆盖验证侧（契约 harness、CDP 冒烟、a11y 审计、文件级盘点），生产侧（“能复用什么、怎么用”）没有 Agent 接口。外部证据：BILL 的对照实验显示，给 Agent 接上设计系统后 token 省 31–63%，组件一次用对。
期望结果：Agent 写前端前先查组件清单和用法文档。具体：装官方 @storybook/addon-mcp（自托管，数据全是自己的）；在 agent 配置和 AGENTS.md 里登记使用指引；先只开 docs toolset。testing toolset 依赖 @storybook/addon-vitest，等 preview 稳定后作为后续跟进。
备选方案：维持现状（翻源码，正是被实测为贵的路径）；自研 MCP 包装 inventory 生成器（同理但要多建多养）；等 preview 结束再接（可行，提案已把暴露面限制在 docs toolset，且只是开发依赖，随时可移除）。
风险：Storybook 的 MCP/manifests 处于 preview，API 可能变。
Problem
When an agent writes frontend code in this repo, it has no machine-readable way to learn which components exist or how to use them. It falls back to reading component source to guess props and patterns, which burns tokens and produces rework: duplicated components, wrong props, hand-rolled values where tokens belong. Humans review out the damage afterwards.
Our existing tooling covers the verification side (visual-contract harness, CDP-based Storybook smoke, a11y tree audit, file-level Astryx surface inventory). The production side — "what can I reuse and how do I use it" — has no agent-facing interface.
External evidence that closing this gap pays off: BILL's A/B experiment grounding agents in their design system cut token usage 31–63% per task and improved first-pass component fidelity (https://www.bill.com/engineering/how-we-made-our-design-system-bilingual).
Desired outcome
An agent doing UI work queries the design system before writing code: list available components, read props and usage docs, and later run interaction tests on its own stories.
Concretely:
@storybook/addon-mcp(official, self-hosted: it serves our own Storybook athttp://localhost:6006/mcp, no third-party service).AGENTS.md(query docs before writing frontend code).Follow-up, not in scope: the testing toolset (
run-story-tests) needs@storybook/addon-vitest; adopt once the MCP feature leaves preview.Alternatives or workarounds
Risk: Storybook's MCP/manifests are in preview; the API may change. Exposure is limited to a dev dependency plus agent config.
中文对照
问题：Agent 写前端时没有机器可读的方式了解有哪些现成组件、怎么用，只能翻源码猜，费 token 且产出需要返工（重复造组件、props 用错、绕过 token 手写样式）。现有工具链只覆盖验证侧（契约 harness、CDP 冒烟、a11y 审计、文件级盘点），生产侧（“能复用什么、怎么用”）没有 Agent 接口。外部证据：BILL 的对照实验显示，给 Agent 接上设计系统后 token 省 31–63%，组件一次用对。
期望结果：Agent 写前端前先查组件清单和用法文档。具体：装官方
@storybook/addon-mcp（自托管，数据全是自己的）；在 agent 配置和 AGENTS.md 里登记使用指引；先只开 docs toolset。testing toolset 依赖@storybook/addon-vitest，等 preview 稳定后作为后续跟进。备选方案：维持现状（翻源码，正是被实测为贵的路径）；自研 MCP 包装 inventory 生成器（同理但要多建多养）；等 preview 结束再接（可行，提案已把暴露面限制在 docs toolset，且只是开发依赖，随时可移除）。
风险：Storybook 的 MCP/manifests 处于 preview，API 可能变。