But the more I looked into it, the more I realised it wasn’t really a developer thing at all. It’s actually a design systems thing. And it might be one of the most practical shifts happening right now at the intersection of design and AI-assisted development.

So I did what I usually do…I experimented with it. I brought it to my team, tested it in a real workflow, and it worked. We’re now running it in v1.0.

Once I saw it hold up, I introduced it to the team and invited everyone to give it a try. And that’s where it got interesting because from that first try, we didn’t stop. We started building more on top of it. Iterating. Expanding. Making it ours.

What started as curiosity became a foundation.

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

We spend months building design systems.

Colors. Typography. Spacing. Components. Tokens.

We document it in Figma. We publish the library. We write guidelines.

And then an AI coding agent Cursor, Claude Code, Copilot that generates a UI that looks nothing like it.

Not because the AI is bad at its job.

But because the AI has no idea your design system exists.

It’s working blind.

DESIGN.md is how you fix that.

It’s a single markdown file that lives inside your codebase.

One file that captures your brand’s visual language: colors, typography, spacing, component rules, motion in a format that AI coding agents can actually read and follow.

Not a Figma link. Not a Notion doc. Not a Storybook URL.

A plain text file. Right there in the repo. Always accessible.

When an AI agent generates UI, it reads DESIGN.md first.

And suddenly, instead of generic beige interfaces, it builds something that actually looks like your product.

Think of it like this.

Your design system is the system.

DESIGN.md is the briefing document you hand to the machine.

AI coding agents are no longer experimental.

Teams are shipping real features with Cursor, Claude Code, and Copilot every day.

But most of them are generating UI without any design context.

The result is inconsistency. Drift. Components that don’t follow the system.

Developers aren’t ignoring the design system on purpose.

The tools they’re using simply don’t have access to it.

DESIGN.md closes that gap.

It makes your design system legible to machines.

And once the machine understands your system, the AI-generated output starts to reflect actual design intent not just technical correctness.

A good DESIGN.md typically covers:

Color tokens: your palette, semantic colors, and how they’re used

Typography: font families, size scale, weights, line heights

Spacing and layout: your grid, spacing scale, component density

Component rules: when to use what, and what variants exist

Motion: easing, duration, what should and shouldn’t animate

Voice: tone, writing style, how the product speaks

It doesn’t need to be exhaustive on day one.

Even a lean DESIGN.md with just your color tokens and typography scale is already better than nothing.

The AI goes from guessing to following.

You don’t have to write it manually.

There are a few tools that can generate DESIGN.md directly from your Figma design system.

The DESIGN.md Generator plugin on Figma Community extracts your local styles and variables: colors, typography, spacing, effects and produces an editable markdown file you can drop straight into your repo.

If you prefer a browser-based approach, figmadesignmd.com does the same thing. Paste your Figma URL and access token, and it generates the file in seconds.

Once it’s generated, review it. Edit it. Make it yours.

It’s a living document, not a one-time export.

Here’s where it gets interesting.

DESIGN.md sits in the codebase. But it’s written for the machine by the designer.

Which means the designer is now authoring something that directly shapes how AI generates UI.

Not through a Figma file.

Not through a handoff note.

Through a file that lives in the same repository as production code.

That’s a meaningful shift.

It means design intent doesn’t stop at the component library.

It travels into the AI’s context and influences every screen it generates from that point forward.

The honest truth is: DESIGN.md doesn’t auto-sync with Figma.

When your design system evolves, the file needs to evolve with it.

The practical approach is to treat it like a release note.

Every time you publish a design system update: new tokens, updated components, deprecated patterns and you update DESIGN.md alongside it.

It takes maybe fifteen minutes per update.

And it’s worth it, because an outdated DESIGN.md is worse than no DESIGN.md.

Stale guidance actively misleads the AI.

For a long time, the gap between design systems and AI-generated code felt invisible.

Designers built systems. Developers used AI tools. The two didn’t connect.

DESIGN.md is a small file.

But it does something important.

It gives the machine a design language to work with.

And it gives designers a direct line into how AI shapes the product, not through prompts or reviews after the fact, but through a clear, structured brief that travels with the code.

That’s the shift worth paying attention to.

Not just what the AI builds.

But what designers give it to work with.

If you found this useful, subscribe to Design x Machine where I write about UX, intelligent systems, and the future of design practice.

👉 designxmachine.beehiiv.com