How to write a DESIGN.md file Claude can actually use

Your DESIGN.md should tell a story of your product

Have DESIGN.md files been all over your feed lately, too?

I made the mistake of properly going down the rabbit hole. I analysed a stack of them, built one from scratch for a real product, and then — because apparently that still wasn’t enough — built a Claude skill to encode the whole process.

What started as a small curiosity turned into something much more useful: a clearer understanding of why some DESIGN.md files produce strong output and others quietly fall apart.

If you haven’t come across them yet, DESIGN.md files are plain-text documents that give AI coding tools like Claude Code and Cursor the design system context they need to generate interfaces more consistently. In theory, they should help models produce UI that actually reflects the product. In practice, most of them are missing the part that matters most.

Stage 1: Analysing what’s already out there

The first thing I did was pull apart a range of existing files — both carefully written ones and the scraped collections floating around GitHub. Some were genuinely thoughtful. Others were… less convincing.