The missing token table

Date: 2026-11-08. Context: building the design-system MCP server (feat/ds-mcp).

What happenedCopy Anchor Link

Before writing our own MCP server, we called Storybook's on the same design system, to know what the "standard MCP" column of the benchmark actually gives an agent.

The tokens page in Storybook shows a table of every semantic color with its light and dark swatch and what it is for. It is the most important page for following the design system. Through the MCP, docs-show with id: "tokens--docs" returned the raw MDX:

import { SemanticTokenTable, TokenTable } from "./token-table";
…
<SemanticTokenTable />

The table is a React component that reads panda.config.ts at render time. A person sees a table. An agent sees a tag. Apart from the few names used in prose examples (bg.surface, fg.muted), no token name reaches the agent. The same page ends with "Adding a token: add it to panda.config.ts", which on a benchmark task is exactly the edit the protected-files grader penalizes.

Two more things showed up in the same session:

• The Card example uses css() but does not import it, and it imports 14 components where it uses 7. Pasted into an app, it does not compile.
• The tool list is 17,852 characters for 7 tools, and it travels with every request to the model. Four of the tools (stories-preview, stories-changed, …) are for editing stories, not for using components.

Our server reads the same sources and sends 1,399 characters of tool definitions, every token with both theme values and its job, examples with their imports, and the rules without the maintainer sections.

What we learnedCopy Anchor Link

A docs page has two readers, and we had only checked one. The token table was built live from the config so it could never go stale for people, and that same choice made it invisible to agents. "Generated from the source" is not enough: the generated thing has to exist in the format the reader gets.

Advice is also audience-specific. "Add a token" is right for a maintainer and wrong for an agent doing a task. A context source that does not know who is reading will give both.

What it means for VektosCopy Anchor Link

1. The standard MCP column is weaker than it looks. A team that installs the Storybook addon and expects agents to follow its tokens is giving them no tokens. That is a result in itself, and the benchmark should show it in numbers once the runner exists.

2. Context cost is a fixed tax. Tool definitions are sent on every turn. At 17.8k characters (around 4–5k tokens) against 1.4k, the standard MCP costs more per request before the agent asks anything. The cost metric must count it.

3. Examples should pass the graders. If agents copy examples, the examples are part of the score. The ds-mcp tests grade every example and expect zero violations.

Follow-upsCopy Anchor Link

• Done: ds-mcp with semantic tokens, rewritten examples and filtered guidelines (guide 07).
• Check whether @storybook/addon-mcp can limit toolsets to the docs tools, and benchmark both configurations. The fair "standard" column is the one a team would set up.
• Consider rendering the token tables as static Markdown in the MDX, so Storybook's MCP sees them too. Not done now: it would make the standard column better on purpose, and the benchmark should measure the default setup first.