Design.md files and the foundational patterns of AI assisted design

A Design.md file is a portable markdown document that captures your design rules: colours, typography, spacing, and component patterns, all in a format that AI tools can read directly. If you’re working across tools like Google Stitch, Claude Code, or Cursor, a Design.md file gives each tool something concrete to work from instead of guessing at your visual direction.

I’m Fergus Hannant , Senior Product Designer at Fifty Five and Five . I’ve been experimenting with AI assisted design tools across personal projects and client work, and Design.md files are the development I find most interesting right now. Tools like Google Stitch offer useful features like natural language UI generation and responsive layouts, but Design.md is the one that could become a genuine standard: a way to carry design intent across any tool, not just the one you happen to be using.

Figma’s State of the Designer 2026 report found that 72% of designers now use generative AI tools, with 98% increasing their usage over the past year (Figma ). Adoption is clearly accelerating, but the consistency question hasn’t been fully answered yet. Design.md files are one practical step towards closing that gap, by giving AI tools explicit design rules rather than leaving them to infer.

What Stitch introduces and why Design.md matters most

Google Stitch is an AI assisted design tool that does several things well. You can describe an interface in plain text and get a generated UI back. It produces responsive layouts that consider multiple device widths from the start. Both of these are useful, particularly for ideation and early-stage exploration.

But the feature that stands out is the Design.md file. Stitch can extract design rules from any existing website, or you can define them yourself, and save them as a portable markdown document. That file then travels with your project: into a new Stitch canvas, into Claude Code, into Cursor, wherever you’re building. Your colour palette, type scale, spacing system, and component rules aren’t locked to a particular platform any more. They sit in a file that any AI tool can read.

That portability is what makes Design.md different from the other features. Natural language UI generation and responsive layouts are useful within whichever tool you’re using. Design.md is useful across tools. It means your design direction follows the project rather than living inside a specific tool’s format. If other platforms adopt the same format, it could become a genuine standard for how design intent moves between environments.

The concept is still early. But it’s the one worth paying attention to.

Where AI generated UI works and where it falls short

AI design tools are genuinely good at generating simple websites and interfaces. For projects where the main decisions are fonts, colour palettes, and layouts, they produce solid starting points quickly. Think of them as highly customisable templates rather than a complete design solution.

I’ve been using Stitch on personal projects, simple mini apps and basic flows, and the interfaces that come back are generally good. Clean layouts, sensible spacing, and reasonable component choices. But they’re not usable straight away. There’s always refinement needed: tweaking hierarchy, adjusting how elements relate to each other, fixing the small details that make an interface feel considered rather than generated.

The more complex the problem you throw at these tools, the more that gap opens up. A simple landing page? Stitch handles that well. A multi-step form with conditional logic and validation states? The output needs significant reworking. The tools struggle when they’re trying to solve too much at once, when a design requires understanding how different states interact, how a user will navigate through a flow, or what information is most important on a page.

The distinction worth drawing is between generation and design. AI tools are strong at generation: producing layouts, suggesting colour combinations, and arranging components. Design is the bit that requires understanding why a particular hierarchy works, why one layout serves the user’s goal better than another, why a specific interaction pattern feels intuitive in context. That thinking still comes from the designer.

The Design.md file: a lightweight way to carry design intent

A Design.md file is a markdown document that captures your design system’s core rules: colours, typography, spacing, component patterns, and layout principles. It’s written in plain text, which means any AI coding or design tool can read it as context. When you prompt an AI tool to “add a settings page that matches our design system,” the Design.md file gives the tool specific rules to follow rather than leaving it to guess.

The important distinction: a Design.md file does not replace a design system. Design systems are still necessary for any project of real complexity, with proper documentation, component libraries, and usage guidelines. But a Design.md file is a lightweight, portable way to carry design intent across tools without the overhead of maintaining a full system in every environment.

There are three ways to create one. Stitch can extract design rules from any existing website and save them as a Design.md (Google ). You can author one manually in markdown, specifying your own rules with no special syntax required. Or you can export from a design tool that supports the format. The file then travels with your project: into a new Stitch canvas, into Claude Code, into Cursor, wherever you’re building.

This maps directly to something I was already doing before Design.md existed as a format. When I was setting up a design system for Avalara using Claude Code and Figma MCP (Figma’s Model Context Protocol integration, which lets AI tools interact directly with your design files), I gave Claude Code the Avalara website and brand guidelines as reference material. The AI used those guidelines to generate colour and typography variables, then produced form input components that stayed on brand. The result was consistent, reliable output with minimal manual correction.

That process, giving an AI tool explicit design rules to work from, is exactly what a Design.md file formalises. Instead of manually feeding guidelines into each tool separately, a Design.md file carries those rules portably from one environment to the next. If Design.md gains traction as a standard, it could become the design equivalent of a .env file: a small, shareable document that any tool in the workflow can pick up and use.

What this signals about the future of the AI design process

Design.md files point towards a future where design intent is expressed once and carried everywhere. You define your visual direction in one place, and the tools across your workflow pick it up without needing separate configuration for each one.

Figma’s 2026 report found that 96% of designers learned AI through self-teaching: side projects, peer tips, and social media (Figma ). The tools are evolving faster than formal training can keep up with. Experimentation is the learning model, and the designers getting the most from these tools are the ones trying them on real projects and forming their own views.

The role of the designer isn’t shrinking. If anything, it’s expanding. The same shift I wrote about in how designers are building real products with AI coding tools applies here too. Design thinking, user research, information architecture, and interaction design: none of that changes. What changes is the output. A designer who understands these foundational patterns can deliver more, and deliver it faster, without sacrificing the judgement that makes the work good.

At Fifty Five and Five , we approach AI tools with a principle I keep coming back to: it’s not something you default to. It’s something you consider and think about the best way to use. A lot of this stuff is down to experimentation. The tools are moving fast, and the best approach is to try them on real work, build in flexibility for when better options emerge, and probe further even when you think you’ve found a good approach. Not putting your idea before the outcome is what keeps the work honest.

What are Design.md files and how do they fit into AI assisted design?

Design.md files are portable markdown documents that carry your design rules: colours, typography, spacing, and component patterns, across AI tools in a format any tool can read. They’re the most interesting development in AI assisted design right now because they address portability, not just generation.

• Design.md files don’t replace design systems, but they make design intent portable across tools
• AI generated UI works well for simple sites and ideation, but needs design judgement for anything complex
• The tools are evolving fast, and experimentation is the only way to figure out where they genuinely add value
• Design thinking still drives the decisions. AI changes what a designer can deliver, not the process behind it

If you want to start experimenting, try creating a Design.md file for a side project and importing it into Stitch or Claude Code. See how the AI interprets your rules and where the output needs your input. That hands-on experience will tell you more about where AI assisted design is useful than any amount of reading about it. For a broader look at how AI fits into the design process, read the full AI for designers guide.

Frequently asked questions