One of the biggest risks when building with AI is “visual drift.” Without a central source of truth, an AI agent will treat every new component as an isolated task. It might give you rounded buttons on the login page and sharp corners on the dashboard, or slightly different shades of blue across five different files. Traditionally, we solved this with Figma files or brand PDFs, but those are invisible to an AI coding agent.
The DESIGN.md file is the solution. It is a plain-text design system that both humans and agents can read, edit, and enforce. It turns your visual identity into a set of machine-readable instructions. With this file in your context folder, the AI no longer guesses; it executes according to a strict visual logic.
The pillars of a text-based design system
To get the most out of this file, I break it down into specific sections that define the boundaries of the UI. This structure allows me to be detailed enough for precision, yet simple enough for the AI to parse instantly.
Visual overview
I start with a high-level description of the “vibe.” For my current projects, I might specify a “high-density, minimal dark interface for enterprise monitoring.” This sets the psychological tone for the AI, helping it choose between a playful, airy layout or a professional, data-heavy one.
The colour palette
I list hex codes with specific functional roles. I do not just list colours; I define their intent. For example, I specify which hex code is for “Primary CTA,” “Surface Background,” or “Destructive Actions.” This ensures the AI uses the error red only when something is actually breaking.
Typography and hierarchy
This section defines the scale. I specify font families (usually Inter for its clean, professional feel), weights, and specific pixel ranges for body copy versus headlines. I also include rules for labels, such as “12px, medium weight, uppercase,” to ensure section headers remain consistent across the app.
Component specifications
This is where we define the physical attributes of our UI elements. I set rules for corner radii (e.g., “8px rounding for all containers”), border widths, and elevation. By telling the AI to rely on “border and background contrast” rather than shadows, I can maintain a modern, flat aesthetic without the AI adding unnecessary CSS bloat.
Enforcing the rules: Do’s and Don’ts
The most critical part of the DESIGN.md file is the “Do’s and Don’ts” section. This acts as the final guardrail. I include explicit instructions such as “Do maintain a 4:1 contrast ratio” or “Don’t mix different border radii in the same view.” These simple logic gates are incredibly effective at preventing the AI from making creative choices that clash with the established brand.
A living, evolving artefact
The DESIGN.md file is not a static configuration; it is a living artefact. As I iterate on a project, I might decide a certain primary blue is too vibrating, or that we need a new card style for data visualisation. I simply update the markdown file, and the AI immediately applies those new rules to every subsequent component it builds.
By keeping the design system in the repository, I have removed the friction of design handoff. I am no longer a middleman between a design tool and a code editor. Instead, I am the curator of a system that allows the AI to build with a level of visual polish that used to require a full design team. Up next, we look at ARCHITECTURE.md and how to structure the invisible logic of your app.
