What is a DESIGN.md file and why would a business want one?
A DESIGN.md file is a small plain-text document that records a brand's visual rules — colour roles, type hierarchy, component shapes and do/don't instructions. Any AI tool or person can read it, so generated documents, decks and builds use the same brand language. The file sits in the project repository rather than a closed brand centre, which keeps the rules next to the work.
What belongs inside a DESIGN.md file?
A useful DESIGN.md file is short but specific. It names the decisions a designer would otherwise make by eye, so a tool does not have to guess.
The four things that matter most are colour roles, type hierarchy, component shapes and do/don't rules. Each can be written as plain lines that any AI tool can parse.
- Colour roles — primary, secondary, surface, text and border colours, with exact values
- Type hierarchy — heading and body sizes, weights, line height and pairing
- Component shapes — corner radius, border width and spacing for buttons, cards and inputs
- Do/don't rules — instructions such as avoid em-dashes, filler verbs and stock purple gradients
- File paths — where logos, fonts or images live, if they are used
How does a DESIGN.md file steer an AI build?
Without a DESIGN.md file, a build tool receives a prompt like 'make it look professional'. The model then fills the gaps from its training data, which is why so many generated pages share the same look.
When the file is present, the tool reads exact values before it writes the first component. It is the difference between asking for 'a clean blue' and telling the system the precise primary colour, the text colour it must sit on, and the corner radius every button must use.
GROX Code can generate a DESIGN.md from a project's Brand Kit, make it downloadable, and then apply it to builds alongside a rulebook that checks for the telltale patterns of AI-generated pages.
| Without DESIGN.md | With DESIGN.md | Result |
|---|---|---|
| A prompt says 'make it look professional' | Exact primary, secondary and surface colours are named | Fewer arbitrary colour choices |
| Type is described as 'clean' | Heading and body size, weight, line height and pairing are set | Text hierarchy stays the same across outputs |
| No component guidance | Buttons, cards and inputs have defined corner radius and spacing | Interfaces repeat the same shapes |
| The model fills gaps from training data | Do/don't rules block common AI patterns | Less stock feel |
Why does a plain-text file beat a locked-in brand centre?
A brand centre is fine for humans who can log in, browse and copy values. The problem is that most AI tools cannot log into a proprietary portal. They can read files from a repository, but they cannot click a button inside a web app.
A DESIGN.md file works because it is portable. Put it in the same folder as the project and every tool — a code generator, a slide builder, a new starter — reads the same rules. There is no export step, no API key and no lock-in to a platform.
A plain-text file also fits normal version control. When the brand changes, the file changes in the same commit as the work it affects, and the history shows who changed what and why.
- Portability
- The file moves with the project and can be read by any tool that accepts plain text
- Versioning
- Brand changes sit in the same diffs and history as the work they govern
- Low ceremony
- No login, no export, no proprietary format between the rules and the reader
- Human-readable
- A person can open the file and understand the rules without special software
What should a first DESIGN.md file contain?
Start small. A first file can be under a page: one heading, a colour block with four or five roles, two type levels, one button and one card rule, and five do/don't lines.
Write the rules as instructions, not adjectives. Instead of 'modern', say 'buttons use a 6px corner radius and a 2px border'. Instead of 'warm', give the exact background and text colours.
The point is not completeness on day one. It is that every future build or deck starts from the same written decisions instead of a new guess.
Common questions
What is a DESIGN.md file?
A DESIGN.md file is a plain-text document that describes a brand's visual rules: colour roles, type hierarchy, component shapes and do/don't instructions. It is stored in a project repository so that any AI tool or person can read and apply the same rules. It replaces vague adjectives with exact values, which helps generated pages, decks and apps stay consistent.
Do I need a design tool to create a DESIGN.md file?
No. You need a text editor. The file is plain text, so it can be written by hand, copied from an existing style guide, or generated from a project's brand kit where that feature is available. The important part is using exact values — colour codes, pixel sizes and spacing — rather than descriptive words.
Can a DESIGN.md file work with any AI tool?
Yes, if the tool can read files from the project. Because the file is plain text, there is no proprietary format to support. The tool simply reads the instructions and applies them. If a tool cannot read files, you can paste the DESIGN.md content into the prompt as plain text.
How is a DESIGN.md file different from a brand guidelines PDF?
A PDF is made for people to read and is hard for a machine to parse reliably. A DESIGN.md file is plain text, so it can be read by an AI tool in the same way it reads code or documents. It is also easier to version, diff and keep next to the work.
You can generate a DESIGN.md from a project's Brand Kit in GROX Code and keep every build on the same rules.