Communicating Design Rules to AI: Using DESIGN.md for Mobile Apps

When you ask AI to build mobile app screens, a nagging doubt creeps in: Is the AI actually following my design rules? Will the colors match? Are the font sizes consistent? Will the spacing feel right? If you could hand the AI a design guidebook it actually understands, design reviews would take half the time.

That's where DESIGN.md comes in. It's an open-source markdown format Google created specifically for this: writing design specifications in a way that both humans and AI can read and follow.

What is DESIGN.md?

DESIGN.md is a lightweight format (Apache 2.0 licensed, open-source) for documenting design systems in plain markdown. Instead of keeping design rules buried in Figma or Adobe XD, you write them in a file called design.md that tools like Rork can read directly.

The philosophy is simple: Design rules should be machine-readable. When you write "primary color is #2563EB and use it for main action buttons," you're creating a specification that AI can follow, not just something a human designer remembers.

Why It Matters for Mobile Apps

Mobile apps live or die by consistency. When buttons across different screens have different colors, when text sizes vary for no reason, when padding is unpredictable—the app feels unpolished, even if the features work perfectly.

DESIGN.md solves this by letting you define:

• Color tokens: Primary, secondary, error, neutral—with rules for when each applies
• Typography scales: Heading 1, Heading 2, body text, captions—all with consistent sizing
• Spacing system: The distance between elements, padding inside containers, margins between sections
• Component rules: How buttons should look, how cards should behave, how form fields should appear

When Rork generates a new screen, it can reference these rules automatically. Instead of "make a button," you say "make a button following our DESIGN.md," and it stays consistent with screens you built weeks ago.

A Practical Example

Here's what a simple DESIGN.md looks like for a casual app project:

# Design Tokens
colors:
  primary: "#2563EB"
  secondary: "#10B981"
  error: "#EF4444"
  neutral_light: "#F3F4F6"
  neutral_dark: "#1F2937"
 
typography:
  heading_1:
    font_size: "28px"
    line_height: "36px"
    font_weight: "700"
  heading_2:
    font_size: "20px"
    line_height: "28px"
    font_weight: "600"
  body:
    font_size: "16px"
    line_height: "24px"
    font_weight: "400"
 
spacing:
  xs: "4px"
  sm: "8px"
  md: "16px"
  lg: "24px"
  xl: "32px"

Then add human-readable explanations below:

## Colors
 
### Primary (#2563EB)
Use for main action buttons (Create, Save, Continue), active tabs, and primary links.
Never use for errors, disabled states, or secondary information.
 
### Secondary (#10B981)
Success and positive states. Use for checkmarks, confirmation messages, and completed steps.
 
### Error (#EF4444)
Error messages and invalid form fields only.

How AI Tools Read It

When you use Rork or other AI tools, you paste your DESIGN.md into the prompt. The AI then knows the rules and applies them consistently.

Example prompt:

"Create a task management home screen following this DESIGN.md:

[paste DESIGN.md content]

Requirements:
- Large heading 'My Tasks' at the top
- Task list items, each with md (16px) padding
- 'New Task' button in the bottom right using primary color
"

By explicitly referencing DESIGN.md, you're telling the AI "these rules are non-negotiable." The quality jump is significant.

Validation Tools

Google's DESIGN.md ecosystem includes CLI tools for validation and export:

# Check if your design spec is valid
designmd validate design.md
 
# Export to Tailwind CSS
designmd export design.md --format=tailwind
 
# Export to W3C DTCG format
designmd export design.md --format=dtcg

These catch inconsistencies before they become problems.

The Difference It Makes

Without DESIGN.md:

• Button colors are random or unpredictable
• Font sizes vary wildly
• Spacing feels haphazard
• Multiple screens look like they were designed by different people

With DESIGN.md:

• All buttons are the brand color
• Typography is consistent: headings are 28px, body is 16px, every time
• Spacing follows the 16px base grid
• Ten screens generated with Rork still feel like one coherent app

In practice, this cuts design review and rework time by 50% or more.

Getting Started

1. Write down your design rules (colors, fonts, spacing, component rules)
2. Grab Google's official DESIGN.md template and customize it
3. Save it as design.md in your project root
4. Paste it into your Rork prompts
5. Test the generated UI and refine your DESIGN.md as needed

DESIGN.md is a conversation in shared language between you and AI. It takes effort upfront, but the payoff compounds—especially as your app grows and you generate more screens.

Try it on your next Rork project.