Sik.limited Logo

Write a DESIGN.md for consistent AI-generated interfaces

Turn brand decisions into design tokens and guidance AI coding tools can follow.

·

When an AI-generated screen looks different every time, the missing piece may be a shared design reference rather than a better prompt. DESIGN.md puts machine-readable tokens and human-readable design rationale in one file, giving coding agents a consistent visual direction to consult.

This guide follows Google Labs’ open format to build a practical document, and explains where its current limits are.

Design Tokens and Brand Principles

A token such as primary: '#2457D6' gives an agent an exact color. It does not tell the agent whether that blue belongs only on the primary button, whether it can also be used for links and badges, or how it should change on a dark surface. That is why a generated screen can be technically consistent with a value yet still feel wrong.

Google’s DESIGN.md combines YAML tokens with Markdown explanation. Tokens provide reusable values for color, typography, and spacing; prose describes the impression they create and where they belong. For example, explain that a warm paper-colored surface is for long reading and that the accent color should be reserved for one primary action.

Defining the Purpose of DESIGN.md

Give the design system a name in the file’s front matter, then use the first section to describe the product and its users. Be specific about the screen’s purpose. “A modern, polished service” offers little guidance; “an operations console where staff check order status daily, so fast scanning and error prevention matter more than decoration” helps the agent make concrete decisions.

---
name: Northstar Console
colors:
  primary: "#2457D6"
  ink: "#172033"
  surface: "#FFFFFF"
  canvas: "#F4F6FA"
  muted: "#667085"
  border: "#D8DEE9"
typography:
  heading:
    fontFamily: Inter
    fontSize: 1.5rem
    fontWeight: 650
  body:
    fontFamily: Inter
    fontSize: 1rem
    lineHeight: 1.5
rounded:
  control: 8px
  panel: 12px
spacing:
  xs: 4px
  sm: 8px
  md: 16px
  lg: 24px
components:
  button-primary:
    backgroundColor: "{colors.primary}"
    textColor: "#FFFFFF"
    rounded: "{rounded.control}"
    padding: 10px
---

## Overview

An operations console that helps staff find order status quickly and avoid mistakes.
The interface should feel calm and information-dense. Reserve strong color for
primary actions and selected states.

Treat this as a starting point. Use token names and hierarchy that match your team’s vocabulary, and connect them to the CSS variables or component names in your code. If the existing system already uses names such as --color-action or Button/Primary, keep the same meanings in the document.

Color, Typography, and Spacing Tokens

A palette named only by hue, such as blue-500 and gray-100, leaves implementation decisions open. Role-based names such as primary, surface, border, and muted are easier to map to interface elements. Explain each color’s purpose in the prose too, and define the colors needed for success, warning, and error states or for text-on-background pairs.

Do not record only a typeface for typography. Define real hierarchy such as heading, body, and supporting text, with size, weight, and line height. For layout, document the spacing scale and content width. For shape, define the corner radius used by controls and cards. These decisions reduce arbitrary values from screen to screen.

Component Design Rules

Trying to specify every component at once makes the document large quickly. Start with frequently used elements that shape the interface, such as primary buttons, inputs, cards, and navigation. A button rule can define its height, padding, radius, focus indicator, and text color. An input rule can cover its default, error, and disabled states, along with the placement of helper text.

Write rules at a level that can be implemented and checked in code. “Make it feel light” is not enough. “Do not use a shadow on a default card; show a 2px accent border only on the selected card” is observable. At the same time, avoid copying every pixel and exception into DESIGN.md. Link to the actual component API or design-system docs. This file should carry the design context needed for generation and changes, not every implementation detail.

Design Dos and Don’ts

Use a Do’s and Don’ts section to capture recurring mistakes. Examples include “emphasize one primary action per screen,” “do not distinguish disabled states by color alone,” and “do not lower contrast for secondary text in body copy.” Add a short reason where it will help the agent handle an exception.

When a theme refers to an external brand or design system, separate its published guidance from your own observations and adaptations. An official specification, a value observed on a public screen, and a value you adjusted yourself are different kinds of evidence. If the document is an independent interpretation, do not describe it as an official implementation or full compliance.

Applying and Validating DESIGN.md

Put DESIGN.md at the project root and tell the coding agent to read it. Then verify the document with a small task instead of generating the entire app at once. For example, ask: “Implement only the login form’s button and input according to these rules, and tell me which tokens you used.” If color, spacing, or focus behavior is ambiguous, revise the rule.

Google Labs’ CLI can check document structure, unresolved token references, and contrast ratios for some text and background pairs against WCAG AA. Run it with:

npx @google/design.md lint DESIGN.md

This checks the document and selected rules. It does not guarantee that the screen matches the intent, that interactions are accessible, or that every design rule has been followed. Open the actual page and review desktop and mobile layouts, keyboard operation, contrast, and state changes.

Alpha Specification and Maintenance

DESIGN.md can provide agents with concrete visual context and reduce variation between generated screens. However, Google Labs currently labels the format alpha; its specification, token schema, and CLI are under active development. It is too early to call it a formal international standard or assume every coding agent reads it automatically. Check whether your tools load the file, and if needed, point to it from your task prompt, AGENTS.md, or CLAUDE.md.

A useful document is not the one with the most tokens. It gives designers and developers a shared way to explain decisions and lets agents reuse those decisions when building screens. Start with a few important screens and update the document when reviews reveal ambiguity.

References

Latest posts