A single DESIGN.md works beautifully when you have one brand, one team, and one product.

Then reality arrives.

A second brand. A new theme. A dark mode request. A segment that needs its own colour story but shares the same components.

And suddenly your clean, single file starts showing cracks.

Not because the concept is broken.

Because the system grew. And the file didn't.

This piece is about what happens when your design system gets complex and how to scale DESIGN.md without losing the thing that made it work in the first place.

Want more like this? Subscribe to get my free UX prompt guide for designing with AI and join the exploration.

When a design system scales, it scales in two directions at once.

Horizontally: more brands, more themes, more segments. The same components, different visual languages.

Vertically: more contributors, more teams, more opinions about what the rules should be.

Both are real problems. And they need different solutions.

Most teams try to solve both with one file.

That's where it breaks.

One design system. Multiple brands.

Most common B2B scenario for instance, Enterprise gets red. Wholesale gets Black. SME gets their own branding colour. Dark mode gets its own layer entirely.

The components are the same. The tokens are not.

If your DESIGN.md only documents one set of token values, the AI agent has no way of knowing which brand it's building for.

It will pick one. And it will be consistent about the wrong choice.

This is the multi-brand trap.

You don't need four separate files.

You need one file with clear theme boundaries.

Here's what that looks like in practice:

Why this works:

The agent now knows four themes exist. It knows the default. It knows mixing is not allowed. And it knows exactly which token to reach for per theme without guessing.

The "always declare the active theme" instruction is the most important line. It turns theme selection from an assumption into a deliberate instruction every time.

Multiple teams contributing to the same design system is a different kind of complexity.

It's not a token problem. It's a trust problem.

When one designer owns the system, the rules are clear. When five designers contribute to it, the rules become negotiable.

Someone adds a new button variant without documenting it. Someone updates a token value without updating the changelog. Someone writes a component rule that contradicts an existing one.

And the DESIGN.md becomes unreliable.

An unreliable DESIGN.md is worse than no DESIGN.md.

The agent will follow it confidently and generate inconsistent UI with full conviction.

The file needs to say who owns it and how it gets updated.

Not just for humans. For the agent too.

Why this works:

Contribution rules aren't just governance for humans. They're instructions for the agent about which version of the file to trust.

The "if you are working from a branch stop" line is one most designers never think to include. But an agent working from an unreviewed draft will generate UI based on rules that haven't been approved yet.

One line prevents that entirely.

There's a threshold where a single DESIGN.md becomes too large to be useful.

When it takes more than five minutes to find a specific component rule, the file has outgrown itself.

At that point, split it.

Not randomly. With intention.

The master DESIGN.md becomes the index. It tells the agent where to find everything else.

Here's what most designers miss when their system gets complex.

The problem isn't documentation volume.

It's documentation trust.

An AI agent will follow your DESIGN.md confidently regardless of whether it's accurate. It doesn't know if the file is outdated. It doesn't know if a rule was overridden last sprint. It doesn't know if a theme token was renamed and nobody updated the reference.

It just follows.

Which means the real job of scaling DESIGN.md isn't writing more rules.

It's keeping the rules you have accurate.

One outdated rule in a complex system causes more damage than ten missing ones. Because the agent follows it at scale across every component, every theme, every team's output until someone notices.

And by then, three sprints have passed.

This is the part nobody warns you about.

Scaling a design system isn't a documentation problem. It's a maintenance discipline.

The file doesn't keep itself updated.

Someone has to own it. Someone has to update it every time a token changes. Every time a rule gets refined. Every time a new theme gets introduced.

That someone is you.

Not because the tools aren't good enough.

Because the design system is only as reliable as the person maintaining it.

And when you maintain it well, the AI agent becomes an extension of your judgment, not a replacement for it.

That's the whole point.

Before adding complexity, check what exists.

Ask these questions:

Is every token in my DESIGN.md still accurate?
Does every component rule reflect how the system actually works today?
Is the changelog up to date?
Does the agent know which theme to default to?
Does it know where to go when it doesn't know?

If the answer to any of these is no, fix that first.

A clean simple file scales better than a complex broken one.

Every time.

Next in this series: Part 5: Here's the System I Built. And Here's How You Can Use It.

Subscribe to Design x Machine for more on UX, intelligent systems, and the future of design practice.

👉 designxmachine.beehiiv.com