Aestheria vs DESIGN.md
A rules file is the right instinct: design context belongs in the repository, read at generation time, not looked up by a person. Aestheria, the design context layer, is the system those rules point at. Run both.
What a rules file gets right.
Atlassian published DESIGN.md in 2025 on a premise worth agreeing with: design context should be portable and read at generation time rather than looked up by a person who then translates it. A markdown file in the repository is readable by every agent, diffable in review, and costs nothing to adopt. If you have one, keep it.
The instinct is right and the ceiling is low, for a reason that has nothing to do with markdown. A rules file is prose about a system. It is not the system.
Where prose stops being enough.
Take a rule any team would write: "use our semantic colour tokens, never raw hex." An agent reading that still has to answer the questions the sentence does not contain.
- Which tokens exist? The file rarely lists them, and when it does the list goes stale the week after it is written.
- Which one applies here? A border on a card, a divider between rows, and an outline on a focused input are three different tokens in a well-built system and one word ("border") in prose.
- What does this component already ship? If a table exists with sorting, row actions, and an empty state, the agent needs the component, not a sentence describing the concept of tables.
- What does good look like when the rule is silent? Whether a destructive action needs a confirm step, whether a dense record set belongs in a table or a card grid, whether this decision deserves a side panel instead of a modal. These are the calls agents get wrong most often, and they are judgment rather than syntax.
So the agent invents answers, consistently and confidently, and differently in each session. The rule was followed. The product still drifted. That gap is not a failure of the file, it is the difference between an instruction and an inventory.
DESIGN.md tells your agent the rules. Aestheria is what they resolve to.
Neither column is a criticism of the other. The left is a pointer; the right is what a pointer needs.
Run both, in about a minute.
Keep the rules file. Point it at the system, so the agent reading your rules can resolve them instead of interpreting them:
## Design system
This product is built on Aestheria, the design context layer.
- Tokens, components, patterns and templates: query the MCP at
https://mcp.aestheria.design/mcp (list_tokens, get_component,
list_templates, get_skill, validate_snippet).
- Never hardcode a colour, radius, or spacing value. Resolve it to a
semantic token.
- Before building a page, read the matching template and the Aria skill.
- Before delivering, run validate_snippet on every file you touched.The rules stay yours and stay in prose, which is what they are good at. What changes is that every one of them now terminates in something an agent can read, and the verification step is a tool call rather than a hope.
| DESIGN.md | Aestheria | |
|---|---|---|
| What it is | A markdown file of rules and principles | A machine-readable library the rules resolve to |
| Colour | Prose: use semantic tokens | 407 tokens with the rule for each, across 6 themes in light and dark |
| Components | Described, if at all | 41 components with their variants and states, plus 22 patterns |
| Pages | Not covered | 63 page templates, each a working screen to build against |
| Judgment | Whatever the author wrote down | Six skills: layout, tokens, motion, usability, accessibility, routing |
| Verification | Review, by a person | validate_snippet returns the specific violations, before the diff |
| Delivery | A file in the repository | MCP endpoint, repo files, or CDN import. Same content |
| Starting cost | Write it yourself | Ships complete, and every part is yours to edit |
| Staleness | Drifts from the code the day the code changes | Generated from the system it describes |
- 407 tokens
- 6 themes
- 41 components
- 27 charts
- 63 templates
Questions
Is Aestheria a DESIGN.md competitor?
No. A rules file is a pointer and Aestheria is what it points at. The two do different jobs, and the combination is stronger than either: keep the prose your team wrote, and give it a system to resolve against.
Do I have to choose between them?
No. Keep your `DESIGN.md` and add a short section naming the MCP endpoint and the tools. Agents that read the file get the rules, and agents that call the server get the inventory those rules refer to.
What does Aestheria add over a rules file?
An inventory an agent can query rather than interpret: 407 tokens with usage rules, 41 components with their states, 22 patterns, 63 page templates, six skills carrying the judgment between them, and a validation tool that catches violations before review.
Why does my rules file stop working as the product grows?
Because prose describes a system it cannot enforce or enumerate. The day someone adds a token or changes a component, the file is out of date and nothing fails. A generated library cannot drift from itself in the same way.
What if I do not have a design system to point at?
That is the common case, and it is the case Aestheria was built for. The kit ships a complete starter system, so the rules file has a destination on day one instead of after a quarter of design work.