"Expected 404 for missing order, and got 500."
That was the test result Baruch Sadogursky watched fail on stage, moments after doing everything right. He had fed his coding agent a CLAUDE.md stuffed with "everything there is to know" about his project—code samples, all the documentation, best practices, the works. The task was trivial: per the presentation, add error handling to one endpoint. The agent added a try/catch. The test failed anyway.
The reflex in the room was predictable. Bigger model. More context window. Try Claude, try something else. Someone will fix the ceiling.
Patrick Debois cut it off with a question disguised as a diagnosis: "Maybe you stuffed too much in there?"
That is the whole reframe. The system is stateless; every token you load rides along on every request, competing with the system prompt, the conversation, the log file you pasted three turns ago. Abundance isn't neutral. It's noise that pushes the signal off the end of the window.
More context is not better context. The interesting question stops being how much you write and becomes what you write, in what order, and why.
More context is not better context. And once you accept that, the interesting question stops being how much you write and becomes what you write, in what order, and why.
That "why" is the part designers should be watching, because it just became a job.
Consider what an agent reaches for when it has nothing. Ask it for a screen and you get a gray Material button, a shadcn card, a stack of defaults that belong to no brand in particular. Not the agent failing—the agent working from nothing, because your visual identity lives in Figma files, a slide deck, and the heads of three senior designers, none of which a model can read at build time.
The fix that emerged is one plain-text file at the repository root, and its structure is deliberate: machine-readable tokens up top, human-readable rationale below.
Google Labs reportedly open-sourced the format—DESIGN.md—on April 10, 2026, under Apache 2.0. The repository reportedly sits at 27,038 stars. Community collections already ship files aping Stripe, Linear, and Vercel.
But the stars are the least interesting number here. The interesting thing is where the value actually lives.
The tokens are the easy half. Your stylesheet already has your hex values, your type scale, your radii. A JSON token file has carried those for years. Feeding an agent "primary: #855300" is not a design achievement; it is a copy-paste.
The value moved to the other half—the prose that most teams skip. Why the primary is a deep forest green. What "one action per screen" actually means for your buttons. When a designer is allowed to break the grid.
Watch it on a single request. With no file, ask for a primary button and you get a blue-gray rectangle at some default radius—correct and anonymous. With the file, the same request returns your deep forest green at your exact corner radius, because the token supplied the value and the prose supplied the intent.
The tokens tell the agent what. The prose tells it why. For any non-trivial call, it needs both.
This is why authoring the file is a design-system discipline and not a prompt trick. Anyone can list values. Encoding the reasoning that governs when those values bend—the normative-yet-fuzzy layer between a rule and a judgment call—is precisely the thing senior designers carry in their heads and never write down. DESIGN.md forces it onto the page, and the team that writes it well controls output quality across every agent that touches the product.
The format even treats structure as a legal contract. Google's spec is, per one breakdown, unusually strict about what breaks a file: an unknown token is accepted as long as its value is valid, and an unknown section heading is merely preserved—but a duplicate section heading is reportedly an error that rejects the whole file.
Read that carefully. The tokens are permissive and the section order is not. Uniqueness and sequence are load-bearing; the values inside can grow. Structure is the contract; tokens are the normative content within it. When prose and tokens disagree, the tokens win.
There are eight sections, in fixed order, opening with Overview and closing with Do's and Don'ts. The structure is fixed. The personality is not.
That distinction is the entire craft, and Google's own examples prove it. Their Paws & Paths file, per one Medium write-up of Google's example, centers on a "Golden Retriever" orange—#855300—and reads friendly, rounded, professional. Their atmospheric-glass weather app, per the same write-up, fills the identical eight headings with frosted crystalline panels, a 20-pixel blur, and a white palette floating over vibrant gradients.
Same headings. Opposite moods. Swap only the DESIGN.md file and the agent produces a different world. The format carries character, not just numbers—which is exactly why it belongs to designers and not to a config-writing engineer.
So prose is powerful. But it has an edge, and the edge is sharp.
Prose works when it names a specific thing and a specific rule: "the primary color for only the single most important action per screen." That is fuzzy enough to require judgment and concrete enough to enforce. An agent can apply it. A reviewer can check it.
Prose collapses the moment you ask it to encode a value instead of a rule. Take "respect user autonomy"—a sentence any designer would nod at. To a human that phrase carries a career of judgment. To an agent it carries nothing, because it needs explicit rules, not sentiment.
So it expands. One line about autonomy balloons into clauses: cancellation must require no more steps than sign-up; never reset timers when a page reloads; allow account deletion without contacting customer support; present consequences factually without persuasive language.
And that is a fraction of one pillar out of five. Multiply autonomy by transparency, privacy, inclusion, and well-being and your reviewable file metastasizes into a specification covering hundreds of brittle clauses—each of which can conflict, drift, or rot the day a product decision changes.
The lesson for authors is disciplined, not defeatist. Prose encodes what "one action per screen" means. It cannot encode "be ethical." Know which sentences are rules and which are wishes, and keep the wishes out of a file an agent will read literally.
Here is where the tooling earns its place, and where a rulebook becomes infrastructure. The format ships with a linter and a differ: `npx @google/design.md lint` catches broken token references and flags contrast ratios; `diff` compares two versions and reports token-level and prose regressions as structured JSON. Your brand's reasoning is now versionable, diffable, and reviewable in a pull request—which is what turns authored context into design infrastructure rather than a Google Doc nobody reads.
Which brings us to the trap.
Everything above makes DESIGN.md the most defensible artifact a design team can own—the single source of truth for how the brand looks, at build time, for every agent. That is real leverage, and it is portable in principle: plain text at a repository root, no proprietary tool required.
But context architecture is tuned to loading behavior, and loading behavior is vendor-specific. The whole reason the stuffed CLAUDE.md failed is that Claude loads it eagerly, in full, every time. The fix Debois reached for—skills that describe when to load context rather than loading it upfront—is Claude's mechanism, lazy-loaded on trigger words.
Structure your context around one agent's loading rules and you have quietly placed a bet on that ecosystem. A file tuned for eager loading may, arguably, behave differently under lazy loading. The prose that makes you consistent inside Claude may, arguably, not survive a jump to another runtime unchanged.
That is the weld. The same authored context that makes you consistent binds your brand's operating logic to whichever AI reads it.
The defense is to treat DESIGN.md as what it actually is: portable brand infrastructure, versioned and diffable, authored by designers—not one vendor's config file dressed up as a standard. Write the prose so a human could follow it without the agent. Keep the structure clean enough to survive a port. Diff it like code.
The tokens were never the moat. Any stylesheet has those. The moat is the reasoning—and now, for the first time, the reasoning has a filename, a linter, and a place in your commit history.
Author it like it's the most valuable thing you own. Increasingly, it is.