Hero image for The Context Budget Manifest: What Your Design System Costs an AI Agent

The Context Budget Manifest: What Your Design System Costs an AI Agent

When teams ask whether an AI agent can “use” their design system, they usually mean capability. The harder question is cost: every byte the agent must read competes for an attention budget that measurably degrades as it fills. This essay treats the design system’s agent-facing surface as a budget problem — measured, tiered, and lintable — because the budget is the part you can actually enforce.

A design system is a context cost before it is anything else

Context is a finite resource that degrades performance as it fills: Chroma’s study of 18 LLMs found that “model performance consistently degrades with increasing input length” across all their experiments, and Anthropic’s context-engineering guidance tells builders to treat context as “a finite resource with diminishing marginal returns” Chroma Research, Anthropic. A design system — token files, component docs, stories, tool schemas — is among the largest things an agent can be asked to hold, so its size is a first-class engineering property, not a documentation detail.

This post owns a specific axis. Earlier pieces here asked whether a design system is AI-readable at all — its structure and signals — and how design systems can act as agent memory across sessions. Those cover findability and persistence. This piece covers cost and order: what the agent spends, in what sequence, and whether you can lint the receipt.

Two measured files set the scale

On 2026-11-19 we measured two artifacts at the byte level: Shopify’s Polaris token package (@shopify/polaris-tokens 9.4.2) ships a dist CSS of 28,240 bytes containing 452 unique --p-* custom-property declarations — all themes combined, roughly 7,060 tokens — and Storybook’s published Button manifest example is 4,658 bytes, or roughly 1,164 tokens, for a single component Storybook manifests. Those are the only token figures in this post, and they are ours, not a benchmark.

Method, stated plainly: the token figures come from dividing bytes by four, following tiktoken’s guidance that “each token corresponds to about 4 bytes” on average in practice tiktoken — not from running a tokenizer. Bytes were measured on files fetched 2026-11-19. That average is an anchor, not a precise count, and it is the method the manifest below declares so no two numbers get compared across methods. The Button entry is a documentation example and may be more verbose than an average component. No published source measures a real design system end to end; these two files are the closest anchored points we have.

Now the compounding part. Storybook’s manifest schema documents per-component entries with id, name, path, stories with snippets, the import statement, jsDocTags, and a reactDocgen block of per-prop types Storybook manifests. Sixty components at the Button entry’s size is 279,480 bytes — roughly 69,870 tokens, about 35% of a 200,000-token window on component metadata alone, before token files, docs pages, tool schemas, or the task itself. (That 200,000 figure is an illustrative window size, not a universal one.) A design system does not need to be huge to crowd the window. It needs only to be complete.

The token side has the same shape. The DTCG Design Tokens Format defines JSON files with $value plus optional $type, $description, $extensions, and $deprecated, with composite tokens nesting child values DTCG Format Module. The spec itself records that “a concern about file size limitations of JSON files was raised by one of the vendors” — and it defines no agent-facing subset, because it is an interchange format, not a context format DTCG Format Module. What a distilled, agent-readable token language looks like is a separate build step.

More input makes agents worse, and distractors make it worse faster

Chroma’s July 2025 “Context Rot” study evaluated 18 LLMs and found performance degrades consistently with input length even when task difficulty is held constant and only input length varies Chroma Research. The familiar needle-in-a-haystack benchmark, they caution, “is a simple lexical retrieval task” that measures a narrow capability and overstates real long-context ability: needle-question pairs with lower semantic similarity degrade faster Chroma Research. Distractors compound the damage — “even a single distractor reduces performance relative to the baseline,” and the effect “amplifies as input length grows across models, including the latest state-of-the-art models” Chroma Research.

The focused-versus-full comparison makes the design-system stakes concrete. In Chroma’s LongMemEval experiments, inputs containing only the relevant parts let models do simple reasoning well; the full 113k-token inputs, which require retrieval plus reasoning, showed “consistent performance degradation with the full inputs” Chroma Research. That is precisely the difference between an agent handed a curated manifest and one handed the entire design system.

Position matters as much as volume. Liu et al. found that performance is often highest when relevant information occurs at the beginning or end of the input, and degrades significantly when models must access relevant information in the middle of long contexts — “even for explicitly long-context models” Liu et al.. Anthropic supplies the mechanism: attention as a budget, where transformers create n² pairwise relationships for n tokens and the capacity to capture them “gets stretched thin”; their principle is “the smallest possible set of high-signal tokens” for the desired outcome Anthropic. One counterintuitive Chroma finding deserves a single sentence: across all 18 models and needle-haystack configurations, models performed better on shuffled haystacks than on logically structured ones, so narrative elegance is not the same thing as attention priority Chroma Research — an argument for curation, not for incoherent docs.

A four-tier load order puts the right bytes in the right place

The load order that fits the evidence has four tiers — a small always-loaded core at the window head, an on-request tier for full detail, a per-component tier paid one component at a time, and a never tier of pure distractors — because retrieval is strongest at the context’s beginning and end Liu et al. and because MCP already scopes context per server connection — each server receives only the contextual information it needs, while full history stays with the host MCP specification.

Tier What enters the window Cost (our measurements, 2026-11-19) Placement and why
Always loaded Core token subset at decision resolution: spacing and type scales, color ramp names with anchor values, radius and elevation; naming conventions; component index (id + one-line purpose, no props, no stories) A deliberate subset under ~4,000 tokens; the base :root + .p-theme-light blocks alone are ≈5,763 tokens Window head — retrieval is strongest at the start Liu et al., and early content survives truncation
On request Full theme blocks (all Polaris themes ≈7,060 tokens), composite typography/shadow/gradient tokens, $extensions, long $description text ≈7,060 tokens for the whole theme set Fetched through a scoped tool; MCP servers “receive only necessary contextual information” MCP specification
Per component One manifest entry (≈1,164 tokens in the Button example), first three stories, reactDocgen props — via the docs-list → docs-show → docs-show-story ladder ≈1,164 per component; see the 60-component arithmetic above Paid one component at a time, late in the window where recency helps Storybook MCP server
Never Raw component source and .stories.tsx, the full 28,240-byte dist CSS, deprecated token groups, expanded literal unions (the nine-object icon union), tool schemas for tools not in use Zero Either retrievable on demand or a pure distractor Chroma Research, Anthropic

The always tier is deliberately small because the base :root plus .p-theme-light blocks together are 23,051 bytes (≈5,763 tokens in our measurement), which would consume a 4,000-token core on its own. The per-component ladder already exists in Storybook’s MCP server: docs-show returns “its props, the first three stories, an index of the remaining stories,” and docs-show-story fills in detail “when docs-show doesn’t provide enough information” Storybook MCP server. Figma’s MCP server applies the same scoping on the design side — you select a frame, and it pulls variables, components, and layout data for that selection Figma MCP server docs. Storybook even ships the exclusion lever: by default every story and docs page carries the manifest tag, and tags: ['!manifest'] removes a story or a whole component from the manifests Storybook manifests.

The never tier is not only about size. Deprecated token groups and unused tool schemas are distractors, and distractor damage grows with length Chroma Research; Anthropic names “bloated tool sets” as a failure mode and recommends just-in-time context — lightweight identifiers like file paths and links, resolved at runtime Anthropic.

The context budget manifest is a lintable contract

A load order holds only if a machine can check it: the manifest below declares the window, the tiers, and the ceilings, and a linter verifies the arithmetic — ceilings, order, presence — against Anthropic’s “smallest possible set of high-signal tokens” principle Anthropic.

{
  "schemaVersion": "1",
  "windowTokens": 200000,
  "estimateMethod": "bytes-div-4",
  "tiers": {
    "always":        { "artifacts": ["dist/agent/core.tokens.json", "dist/agent/component-index.json"], "maxTokens": 4000 },
    "onRequest":     { "maxTokensPerArtifact": 8000, "maxTokensPerSession": 16000 },
    "perComponent":  { "maxTokensPerEntry": 1500, "maxConcurrentEntries": 12 },
    "never":         { "patterns": ["dist/**/*.css", "**/*.stories.tsx", "tokens/deprecated/**"] }
  },
  "loadOrder": ["always", "onRequest", "perComponent"],
  "auditLogPath": ".agent/context-audit.jsonl"
}

Three fields make the counts meaningful. Our rule for schemaVersion: it must match a known version or the lint fails closed, so an unknown contract cannot silently inherit old semantics. windowTokens is required by our contract because every ratio is computed against it; without it, nothing is checkable (the 200,000 above is illustrative for a large-window agent, not a universal figure). estimateMethod is declared because “tokens” is a method, not a fact: bytes-div-4 and a tokenizer run produce different numbers, so our lint refuses to compare counts that came from different methods.

The always tier gets a two-sided check. An artifact that loads but is missing from the list is undeclared context and fails; an artifact listed but absent from the build is a broken core and fails the other way; and if the tier’s estimated tokens exceed maxTokens, the lint fails naming the file. That last check is what catches the 23,051-byte base-plus-light block sitting in the always tier.

Ceilings are policy, checked rather than assumed. Any single on-request artifact above its ceiling fails — a full theme set is ≈7,060 tokens in our measurement, so an 8,000 ceiling admits it while a 4,000 one catches it; either way the decision is explicit. Per component, the ≈1,164-token Button entry is the reference class for maxTokensPerEntry: a 1,500 ceiling admits it and rejects a bloated one. maxConcurrentEntries is checked from the session log so the resident set of per-component entries stays bounded, rather than drifting upward one fetch at a time.

The audit log is the receipt. Any file matching a never-tier glob that appears in .agent/context-audit.jsonl fails, however useful someone found it; perComponent content injected before the always tier is an order violation; and a session with no audit log is unverifiable — non-compliant by default, because an unmeasured budget is indistinguishable from no budget. To be clear about provenance: Storybook already ships the component manifest, and DTCG already defines token interchange DTCG Format Module, Storybook manifests. The contribution here is the budget wrapper — ceilings, order, and receipts.

What we still don’t know

None of the sources this guide reviewed quantifies the problem for design systems specifically: none gives a degradation rate per additional token, none measures a real design system end to end, and none ranks load orders experimentally. The standards are candid about their limits — the DTCG module defines no agent-facing subset DTCG Format Module, and Storybook’s manifest schema “is not yet stable and should not be considered a public API” Storybook manifests. Our two file-level measurements are anchors, not a benchmark.

Frequently asked questions

Doesn’t a bigger context window fix this?

No. Chroma held task difficulty constant and varied only input length across 18 models, and performance still degraded consistently Chroma Research. Anthropic describes attention as a budget stretched by n² pairwise token relationships Anthropic. A larger window changes what fits; it does not change how well a full window is used, and a complete design system fills windows quickly.

Can’t the agent just retrieve what it needs from the full files?

No — retrieval over a bloated corpus imports distractors, and Chroma showed even a single distractor reduces performance, with damage compounding as input grows Chroma Research. In their LongMemEval comparison, focused inputs consistently beat the full 113k-token inputs Chroma Research. Anthropic’s just-in-time pattern — lightweight identifiers resolved at runtime — is the supported middle path Anthropic.

Is Storybook’s manifest format enough on its own?

It solves the hardest tier well: concise, structured JSON per component Storybook manifests, exposed through a docs-list → docs-show → docs-show-story ladder Storybook MCP server, with !manifest tags for curation. But the schema is explicitly not stable or a public API yet Storybook manifests, and it governs component metadata only — token budgets, ceilings, and load order remain your contract to define.

How accurate is the bytes-divided-by-four estimate?

It is a deliberate approximation, not a measurement: tiktoken documents that each token corresponds to about 4 bytes on average in practice tiktoken. Our four-bytes-per-token figure is a rough anchor, not a precise count: we would not gate a release on it without running a real tokenizer, which is why the lint compares counts only within one declared method.

Where do raw design tokens fit?

The DTCG format is an interchange format — JSON with $value and optional $type, $description, $extensions, and $deprecated, and no agent-facing subset defined DTCG Format Module; the spec even records a vendor concern about file size. Build a distilled agent view at build time instead, and keep it synchronized with source tokens so drift between token source and build output is caught in CI, not discovered by an agent.

The Bottom Line

Treat your design system’s agent-facing surface as a linted context budget rather than a documentation dump: the evidence says models degrade as input grows Chroma Research and lose the middle of long contexts Liu et al., and our 2026-11-19 measurements say a naive whole-system load spends roughly 69,870 tokens on component metadata alone at 60 components. The verdict: adopt the four-tier load order, ship the manifest, and fail CI on violations — a design system that fits entirely in the window is one an agent will use badly, while a design system with a declared budget is one it can use well.

How This Guide Was Built

This guide is built from official documentation, published research, and two file-level measurements we ran on 2026-11-19 — no agent, MCP server, tokenizer, or design system was run hands-on. The research base is Chroma’s Context Rot study, Anthropic’s context-engineering guidance, Liu et al.’s position-bias paper, and the MCP specification; the specification base is the DTCG Design Tokens Format Module, Storybook’s manifests and MCP docs, and Figma’s MCP server documentation, each linked inline above. The measurements: the dist/css/styles.css from the @shopify/polaris-tokens 9.4.2 npm tarball (28,240 bytes, 452 declarations; the :root plus .p-theme-light block alone is 23,051 bytes) and Storybook’s published Button components-manifest example with indentation stripped (4,658 bytes). All token figures are bytes ÷ 4 using tiktoken’s “about 4 bytes” average tiktoken, and every figure in this post is scoped to those two artifacts and dated.