DESIGN.md Is Having Its Moment. Anthropic Thinks It Might Not Last.

I recently spent an evening trying to understand why the screens Claude Code generated never quite matched the ones I designed. Same tokens. Same components. Same variants. The output was technically correct and still felt wrong: spacing that drifted, hierarchy that flattened, two primary buttons sitting side by side.

My fix was everyone's fix right now. I wrote a longer instruction file. Rules for spacing, rules for type scale, a list of patterns the agent should never use. It helped. It also grew every week.

I'm not the only one doing this. An October roundup on Mean CEO calls DESIGN.md "standard workflow, not a niche trick" and predicts that by 2027, teams shipping with AI will look careless without one. And this week, someone who builds Claude Code at Anthropic suggested that this whole category of files might not survive.

Two signals pointing in opposite directions

The first signal is adoption. DESIGN.md is a plain Markdown file that describes a product's visual system (tokens, type, spacing, components, forbidden patterns) so an AI agent can read it before it generates a screen. It started near Google Stitch and is now everywhere: generators, GitHub collections, agency packages. Violetta Bonenkamp's October piece captures the mood well. She calls it "infrastructure for taste" and argues that with a proper file, "almost anyone can become an OK designer."

The second signal came from inside the tooling. In a recent interview, Thariq Shihipar from the Claude Code team said CLAUDE.md might eventually disappear. His reasoning, as summarized by The Neuron: stronger models can get over-constrained by giant hand-written context files. He expects prompting to remain a high-skill lever, while generated interfaces, mutable harnesses and subagents reshape how the tool works.

CLAUDE.md and DESIGN.md are the same kind of object. Both are static, hand-written rules for a model to obey. If the people building the models think that kind of file becomes a ceiling, designers should pay attention before we turn our design systems into one.

We've written this file before

I've been in design long enough to see the same artifact change format four times. First it was the brand manual, a printed or PDF bible with logo clear space and approved colors. Then the style guide website. Then the Figma library with its documentation pages. Now it's a Markdown file in the repo root.

Each format promised the same thing: write the rules down once and consistency follows. Each one partly delivered. And each one hit the same wall. The document captured what we decided and almost never why. When a case appeared that the rules didn't cover, people (and now models) either froze or improvised from the average.

That's the part of the DESIGN.md conversation that worries me. Bonenkamp writes that "a file will not replace judgment, but it protects the memory of the system." I agree with the second half. But a list of tokens and forbidden patterns doesn't hold memory of the system. It holds the system's outputs. The memory lives in the reasoning: why our error states are blunt, why the dashboard is dense, why we broke the grid on the onboarding screen and nowhere else.

When I led a UX team at Transbank, the hardest work on our payment terminal redesign wasn't choosing the components. It was deciding which mistakes the interface would refuse to let a cashier make. That work took error rates from 12% to 2.5%, and none of it would fit in a token file. It was a set of trade-offs we argued about until we could defend them.

What survives when the file goes away

If Shihipar is right, the future isn't "no rules." It's fewer rules written as commands and more context written as intent. A stronger model doesn't need to be told the button radius 40 times. It needs to understand what the product is for, who it's for, and which trade-offs the team already made, so it can make the next one the same way.

That shifts what a design system team actually owns. Four things hold up no matter what format wins next year:

• Rationale. The reason behind each decision, written so someone who wasn't in the room could extend it. "Destructive actions always need a second step because our users run payroll for other people" generalizes. "Use the red button variant" doesn't.
• Principles with a cost attached. A principle that never forces you to give something up is decoration. "We choose density over whitespace on operational screens" tells a model what to do when the rules run out.
• Evaluation. The ability to look at a generated screen and say why it's wrong. This is where taste stops being a vibe and becomes a review checklist, a set of reference screens, a test.
• Ownership of exceptions. Every system has places where it breaks on purpose. Someone has to decide those, and that person can't be a file.

Notice that a model can't generate any of these. It can only consume them. That's the work that stays human, and it's the part most DESIGN.md templates leave out because it's harder to write than a hex code.

This is also where I part ways with the "anyone can be an OK designer" framing. It's true for the first 80% of a screen. Tokens and component rules get you there. The last 20% is the part users notice, and it comes from judgment the file can only point at.

What I'd do this quarter

I'm not telling anyone to delete their DESIGN.md. Mine is still in the repo, and it still prevents real mistakes today. The point is to write it so it survives a model that no longer needs the rules spelled out.

1. Add a "why" line to every rule. If you can't write one, the rule might be a preference, not a decision. Cut it or argue about it.
2. Split constraints from intent. Keep a short block of hard limits (accessibility minimums, legal copy, brand non-negotiables). Everything else becomes intent: what the product should feel like for this user, in this context, and what you'd trade to get there.
3. Write down your exceptions. List the places where you broke your own system on purpose and why. That list teaches a model more about your judgment than the rules do.
4. Build an eval set, not just a spec. Collect 10 to 20 screens you consider right and a few you consider wrong, with a sentence on each. Use them to review generated output. This is the piece that still matters when the instruction file is gone.
5. Watch the length. If your file grows every week, treat that as a signal. Each new rule is usually a patch over a missing principle.

The file was never the system

Formats change every few years. The brand manual became a website, the website became a Figma library, the library became a Markdown file, and the Markdown file may become something a model infers on its own. The decisions behind it are the only part that carried over each time.

So write the file. Just don't confuse it with the work.

I'm curious how other teams are handling this. Is your DESIGN.md getting longer or shorter? And has anyone tried writing one that's mostly rationale instead of rules?

Sources

• Design.md News, October 2026, Violetta Bonenkamp, Mean CEO

• Thariq Shihipar interview (YouTube)

• Everything That Happened in AI Today, September 30, 2026, The Neuron