Skip to main content

AI Design.md File

What keeps an AI design agent from inventing taste while it builds?

A DESIGN.md file is portable design memory for agents.

It tells the agent what already exists, what must stay consistent, what taste means here, and how to avoid generic AI design.

Use it when AI will create, edit, review, or translate a visual surface: product UI, article page, deck, mobile mock, landing page, prompt deck, or component library.

Purpose​

AI does not own taste. The design system owns taste.

DESIGN.md gives the agent:

  • machine-readable tokens;
  • human-readable rationale;
  • component rules;
  • layout constraints;
  • accessibility gates;
  • anti-slop failure tests.

The goal is not a prettier first draft. The goal is consistent judgment across tools, agents, and iterations.

Core Rule​

Human first. AI second.

The human defines the job, hierarchy, brand feel, evidence, and constraints. AI accelerates generation inside that system. If the agent invents the system while it builds the page, slop wins.

Minimum File​

Use two layers.

  1. Tokens block. YAML front matter with colors, type, spacing, radii, elevation, and component recipes.
  2. Guidance body. Markdown that explains the design intent, usage rules, interaction patterns, accessibility gates, and do-not-do list.

The token block is for machines. The body is for judgment.

---
version: alpha
name: product-name
description: One sentence that names the design job.
colors:
  primary: "#111827"
  accent: "#b91c1c"
typography:
  body:
    fontFamily: Inter
    fontSize: 1rem
    fontWeight: 400
    lineHeight: 1.6
spacing:
  rhythm-base: 1.5rem
rounded:
  md: 8px
components:
  primary-button:
    backgroundColor: "{colors.primary}"
    textColor: "#ffffff"
    typography: "{typography.body}"
---

# Design

## Overview

[What this design must make people feel, understand, and do.]

Section Order​

Follow the repo standard from Design System Standards.

Use this order:

  1. Overview
  2. Colors
  3. Typography
  4. Layout
  5. Elevation and Depth
  6. Shapes
  7. Components
  8. Do's and Don'ts

Omit sections only when they truly do not apply. Do not invent duplicate headings with different names.

Start From Reality​

Do not write an aspirational design system first.

Start from what is real:

  • shipped screens;
  • live CSS tokens;
  • component library;
  • screenshots of strong pages;
  • current typography and spacing;
  • known accessibility constraints;
  • product-specific mood and audience.

Then curate. Keep what is working. Remove accidental patterns. Name the decisions that should survive the next generation.

Anti-Slop​

Use these as hard rules.

  • Structure before decoration. Wireframe the sections, hierarchy, and flow before color, shadow, gradients, or motion.
  • System over one-offs. Use one spacing scale, one type scale, one component grammar, and one token source.
  • References beat vague taste words. Pair DESIGN.md with screenshots, live CSS, or strong examples when asking an agent to build.
  • AI is an untrusted junior. Review every output against the design file before shipping.
  • Curation is design work. Keep strong branches visible, delete weak ones, and feed the next agent fewer, better references.

Agent Workflow​

Use this fixed sequence for AI design work.

  1. Flow and structure. Ask for layout, information hierarchy, and section jobs only. No colors, shadows, gradients, or animations.
  2. System application. Apply the exact tokens, typography, spacing, and component rules from DESIGN.md.
  3. Component mapping. Use existing components first. If a new component is necessary, define its job, props, states, and reuse boundary.
  4. Interaction pass. Add hover, focus, active, disabled, keyboard, reduced-motion, and mobile states.
  5. Audit pass. Score against the design file, hard thresholds, and anti-slop list.

Most work should iterate inside the existing system. Remix only when the intended direction changes.

Prompt Pattern​

Use this prompt when starting a UI task with an agent.

Use DESIGN.md as the source of truth.

Step 1: propose layout and hierarchy only. No colors, shadows, gradients, or motion.
Step 2: apply the design tokens exactly.
Step 3: map each section to existing components. If a new component is needed, define its one job.
Step 4: add interaction states and mobile behavior.
Step 5: audit against DESIGN.md and list every violation before handing back the result.

Do not create generic AI design. Do not invent tokens. Do not use decoration to hide weak structure.

QA Loop​

Run the loop from How to Audit a Page.

generate -> critique -> refine -> repeat

Critique must use a concrete rubric. "Looks good" is not a finding.

Check:

  • spacing scale violations;
  • typography role drift;
  • invented colors;
  • mixed border radii;
  • unjustified shadows;
  • decorative gradients;
  • weak mobile hierarchy;
  • hover-only meaning;
  • missing focus states;
  • contrast below the hard thresholds;
  • output that could fit another product by changing labels.

If the first critique finds no issues, the rubric is too soft. Look harder.

Accessibility​

Bake accessibility into the design file before code exists.

Name:

  • safe color pairs;
  • minimum body text size;
  • focus ring behavior;
  • touch target minimums;
  • reduced-motion rules;
  • color-independent status patterns;
  • image and icon labelling rules.

Use the thresholds from Product Design, Responsive + Performance, and Interaction + Accessibility.

Scope​

Choose the right scope before writing.

  • System bible: global visual language and shared components.
  • Page-local design file: one page's theme, visual grammar, and failure tests.
  • Venture design file: brand-specific product DNA.
  • Deck design file: load-bearing presentation or prompt-deck grammar.

Local files may narrow the system. They must not contradict it. When a local rule proves useful across two or more surfaces, promote it into the system bible.

Failure Modes​

Fail the design file if it:

  • lists colors without saying when to use them;
  • names components without one-sentence jobs;
  • has no mobile rules;
  • has no accessibility gates;
  • gives the agent mood words but no constraints;
  • copies a generic SaaS layout;
  • treats the first AI output as final;
  • cannot explain what should be cut.

Questions​

What design memory should an agent read before it edits the surface?

  • Which tokens are real, and which visual choices are accidental?
  • What must the page make a reader understand or do?
  • Which components already exist, and what is each component's one job?
  • What accessibility gates must pass before the design can ship?
  • What would make the output obviously generic?

Context​