outclass.design

What is DESIGN.md? A guide with an example file

DESIGN.md is a Markdown file that describes your design system so AI tools design in your style. What to put in it, an example to copy and how to use it.

· 4 min read

DESIGN.md is a plain Markdown file that describes a product's design system: its colors, type, spacing, corner radius, components and the rules that hold them together. You give it to an AI design or coding tool so that what it makes looks like your product instead of a generic template.

Think of it as a style guide written for a reader that takes every word literally. A brand book full of mood boards doesn't help an AI; a short file that says "Primary is #1F6FEB, buttons are 44 pixels tall, never use more than one accent per screen" does.

Why it matters for AI design

Ask any AI tool for "a settings screen" and you get its default taste: often a purple accent, rounded cards with soft shadows and a font you didn't choose. Every screen is fine on its own, and none of them looks like your app.

A DESIGN.md fixes that once. Because it's a single text file, you can keep it in your repository next to the code, review changes to it like any other file, and hand the same rules to every tool your team uses, so a screen designed today matches one designed next month.

What to put in it

Keep it short and specific. The sections that matter most:

  1. Colors, by role: background, text, primary accent, secondary surface, muted text, border. Give exact hex values.
  2. Typography: the heading and body fonts, the type scale (for example 12, 14, 16, 20, 24, 32) and weights.
  3. Shape and spacing: corner radius, the spacing grid (4 or 8 pixels) and standard paddings.
  4. Components: how buttons, inputs, cards, lists and navigation look, including their sizes and states.
  5. Rules: the do's and don'ts that make your product recognizable, like "one primary button per screen" or "no shadows on cards".
  6. Voice: a line or two on how labels and messages are written, if it matters to you.

An example DESIGN.md

Here's a compact file for a calm finance app. Copy it and change the values to yours:

# Ledger design system

## Colors
| Token | Value |
|---|---|
| --background | #FAFAF7 |
| --foreground | #14161A |
| --primary | #1F6F5C |
| --primary-foreground | #FFFFFF |
| --secondary | #EEF1EC |
| --muted-foreground | #5E6670 |
| --border | #DDE2DA |
| --radius | 0.75rem |

## Typography
**Heading Font:** `Geist`
**Body Font:** `Inter`
Scale: 12 / 14 / 16 / 20 / 28 / 40. Headings 600, body 400.
Numbers use tabular figures.

## Components
- Buttons are 44px tall, full radius, one primary button per screen.
- Cards have a 1px border and no shadow.
- Lists use 56px rows with a leading icon in a 36px tinted circle.
- Bottom tab bar with 4 tabs on top-level screens only.

## Rules
- One accent color. Green means money in, never decoration.
- Big numbers lead: the balance is the largest text on the home screen.
- No gradients, no glass effects, no emoji in the interface.
- Write labels in sentence case, short and plain.

How to write a good one

  • Be exact. "#1F6F5C" beats "a calm green"; "44 pixels" beats "comfortable".
  • Name roles, not just colors. An AI needs to know which color is for text and which is for buttons, not just that both exist.
  • Write rules you'd enforce in a review. If you'd send a design back for it, put it in the file.
  • Keep it short. A page or two is plenty. Long files dilute the rules that matter, and some tools, Outclass included, only read the first few thousand characters.
  • Update it when the design changes. A stale DESIGN.md is worse than none: the AI follows it faithfully.

Using DESIGN.md in Outclass

In an Outclass project, open the Theme panel and choose Import design guide. Outclass reads your file and:

  • fills the theme with your colors, fonts and corner radius, so every screen picks them up at once;
  • sends your rules along with every new screen it designs in that project, so new screens follow them too.

The example above uses the format Outclass reads best: a token table with --background, --primary and the other roles, and Heading Font and Body Font lines. Other headings and rules are passed along as written. Screens recreated from a screenshot keep the screenshot's look instead.

Don't have a design system yet? Describe your app in Outclass, adjust the first screens until they feel right, and use what you settled on as the start of your DESIGN.md. For the basics of a consistent mobile design, see our mobile app design guide.

Keep reading