DESIGN.md Is a Good Idea with a Low Ceiling

1.DESIGN.md is a prompt, not a design system

The concept is straightforward: put your colour values, font name, and border-radius rules into a markdown file, drop it in your project root, and AI coding assistants will read it when generating UI. In practice it does improve output. A few concrete token values are better than nothing. The AI gets context it did not have before, and the results are more consistent.

But a markdown file with primary: #133174 is a readable hint, not a token. It has no type system. It cannot express that a colour is a primitive, an alias, or a semantic value. It cannot encode that your button-background references brand-blue-600, which is itself derived from a base hue. That structure is the part that matters in a real design system. DESIGN.md has no way to represent it.

What you get with DESIGN.md is a snapshot of intent at the moment you wrote it. It will drift. It has no validation surface. Nothing tells you when the file and the actual product have diverged. That is fine for a side project where you are the only person who touches both. It is not fine for a team working across Figma, a component library, a marketing site, and a native app simultaneously.

2.Where the structured standard sits, and why it is hard

The W3C Design Token Community Group (DTCG) has been working on a proper standard for exactly this problem. Tokens in DTCG format have a name, a type, a value, and can reference other tokens by alias. The format is machine-readable in a way that markdown is not. A DTCG token file can be consumed by Figma Variables, Style Dictionary, Theo, and any other tool that understands the schema. Write once, render everywhere.

The problem is that DTCG is genuinely hard to get right. The nesting rules are specific. The type system has edge cases. Alias references need to resolve in the correct order. Most teams writing DTCG by hand introduce errors that silently pass until a tool downstream rejects them or produces unexpected output. Validation tooling for this has been sparse.

This is why DESIGN.md exists as a shortcut. The intent behind both formats is the same: give tools a structured understanding of your design decisions. DESIGN.md gets you 60% of the way with 10% of the effort. The remaining 40% is exactly the part that breaks down at scale, and DTCG addresses it. The truth probably sits somewhere between the two: plain-text design intent for lightweight AI context, structured token graphs for production tooling. These are different tools for different jobs and should not be conflated.

3.Where DESIGN.md actually belongs

Solo projects. Prototypes. Greenfield experiments where the entire "design system" is one person's taste and a handful of token values. In those contexts, a markdown file is honest about what it is: a short-lived agreement between you and an AI assistant. Low overhead, immediate results, no pretence of being scalable infrastructure.

The mistake is treating DESIGN.md as a stepping stone toward a real design system. It is not. A markdown file does not migrate cleanly into a structured token graph. The concepts are compatible but the representations are not. If you know you are building something that will grow, start with the structure you will eventually need, even if it means more setup work at the beginning.

4.The Figma Make direction is actually right

There is a different and more compelling vision of how AI should interact with design systems. Rather than AI reading a static description of your system, the system becomes the source of truth and AI generates representations from it. Components, documentation, prototypes, production code. This is what Figma Make points toward: one authoritative design system, many outputs.

This is the correct abstraction because it preserves the hierarchy. The design system does not describe itself to the AI on every prompt. It is the persistent foundation. AI operates within it, constrained by it, deriving outputs from it. The outputs stay consistent because they share a single source, not because a markdown file happened to get included in the context window this time.

DESIGN.md inverts this. The markdown file is a description of the system written for AI consumption, not the system itself. When the two diverge, which they will, the AI works from the description and the humans work from the system and nobody catches the gap until production.

5.What AI does not replace

Even with a well-maintained design system as the foundation, AI generating consistent UI from it is only one part of the problem. The design system still needs an author. Someone has to decide what the system should say: which patterns carry meaning, what the hierarchy of actions is on a given screen, how a brand translates into a product interaction rather than a poster.

That work is service design and business understanding. It requires knowing why a product exists, who uses it, and what they are trying to accomplish. It requires being able to sit with a business stakeholder and identify which surface-level UI problem is actually a structural workflow problem. AI does not have that context and cannot derive it from tokens.

Professional designers remain necessary not because AI cannot generate UI, but because UI is the output of a reasoning process that starts well upstream of visual decisions. The better the tooling gets at the output end, the more value the reasoning at the input end actually carries. A well-maintained design system with clear intent is a better foundation for AI than a poorly maintained one, and building a well-maintained one is still a design problem.

DESIGN.md is a useful idea at the right scale. The honest version of the pitch is: this works for prototypes and solo projects, it will not hold up in a mature design system, and the gap between the two is exactly where the structural standards like DTCG exist. Both formats are trying to solve the same communication problem between design intent and AI tooling. They just sit at very different points on the complexity and fidelity spectrum.

The AI-driven era will produce a large number of tools competing in this space. Most of them will look similar because Dembrandt is MIT licensed and the implementation is there to read. Copying a codebase is straightforward. What is harder to copy is the underlying understanding of what design systems actually are, why token structures matter, and where the real problems in design-to-code translation live. Tools built on top of Dembrandt without that understanding will hit the same ceiling DESIGN.md hits: good enough for demos, not good enough for production design systems at team scale.