AI Design.md File

You are learning a move

No active mission. Use this page to improve one real decision; reading alone is not proof.

How do you help an AI make design decisions without asking it to invent taste?

A DESIGN.md file is portable design memory. It gives humans and agents one succinct source for the intent, visual system, reusable references, constraints, and proof that should survive the next iteration.

Use one before creating, editing, reviewing, or translating a product interface, article, deck, landing page, or component library.

The governing idea

AI accelerates judgment; it does not own it.

The human names the reader, valuable change, hierarchy, evidence, and protected constraints. The design file makes those decisions inspectable and reusable. The implementation then proves whether they work.

A useful design file answers five questions:

1. What must this surface help someone understand or do?
2. What should it feel like, and which concrete choices create that feeling?
3. Which existing relationships should be reused?
4. What must never drift or be copied?
5. What observable result would prove the design is working?

Minimum useful file

Keep machine-readable configuration in YAML and judgment in Markdown.

---
name: product-name
description: The design job in one sentence.
colors:
  ground: "#ffffff"
  text: "#111827"
  accent: "#2563eb"
typography:
  display: "Distinctive display family"
  body: "High-legibility text family"
layout:
  shell: "Narrow reading column inside a wider evidence frame"
rounded:
  controls: "8px"
---

Design authority

## Intent
[Reader, valuable change, hierarchy, and desired character.]

## Composition
[The few relationships that organise the surface.]

## Components
[Existing components, their jobs, and allowed variants.]

## Interaction and access
[Keyboard, focus, motion, responsive, loading, empty, and error rules.]

## Avoid
[Specific failure modes and protected boundaries.]

## Proof
[What a reader must be able to notice, understand, or do.]

Tokens without usage rules are a palette, not a system. Mood words without constraints are inspiration, not memory.

Encode reference judgment

A reference is useful when it teaches a relationship, not when it supplies a look to copy.

Record each approved reference in four parts:

Field	Question
Thesis	What reader or product job makes this reference useful?
Composition	Which hierarchy, rhythm, navigation, evidence, or interaction relationship should survive?
Avoid	Which identity, assets, effects, or failure modes must not transfer?
Proof	What should a reader be able to perceive or do if the relationship works?

Choose one primary reference for the dominant job. Add a secondary reference only when it owns a different concern, such as navigation or motion. Averaging several visual identities usually removes the judgment that made each one coherent.

Extract:

• hierarchy and reading order;
• density and rhythm;
• navigation and orientation;
• evidence placement;
• interaction and responsive behavior.

Do not extract:

• another product's identity, copy, assets, fonts, or exact palette;
• licensed material without permission;
• decorative effects that do not serve the named job.

Record source, rights, allowed use, and exclusions outside public design memory when the evidence is private or licensed. Publish only the reusable principle.

The judgment loop

job
→ observed reality
→ reference relationship
→ design constraint
→ composition
→ rendered proof
→ retained learning

1. Name the job. State the reader, costly moment, valuable change, and primary action.
2. Start from reality. Inspect shipped screens, live tokens, current components, strong examples, and known access constraints.
3. Select the relationship. Choose the smallest reference or pattern that clarifies the job.
4. Encode the decision. Write the token, component, layout, interaction, and exclusion rules that should remain stable.
5. Compose with existing parts. Create a new component only when the relationship is genuinely new.
6. Prove the result. Test comprehension, hierarchy, responsive behavior, keyboard use, reduced motion, failure states, and performance.
7. Curate the memory. Promote proven decisions, mark exceptions, and remove accidental patterns.

Decision tests

Before handing the file to an agent, ask:

• Can a stranger name the reader and page job?
• Does every prominent visual choice serve that job?
• Are token roles explicit instead of merely listed?
• Does each component have one intelligible responsibility?
• Are mobile and interaction states designed, not deferred?
• Can the agent distinguish reusable relationships from protected identity?
• Does the proof describe an observable result rather than “looks good”?

If any answer is no, improve the design memory before generating more output.

Prompt

Use DESIGN.md as the design authority for this surface.

1. Restate the reader job, hierarchy, protected constraints, and proof.
2. Propose structure and reading order before decoration or motion.
3. Map the structure to existing components and tokens.
4. Identify any genuinely new relationship before creating a component.
5. Add responsive, keyboard, focus, loading, empty, error, and reduced-motion states.
6. Audit the result against DESIGN.md and quote each violation.

Do not invent tokens, copy reference identity, or use decoration to hide weak structure.

Transfer test

The method has transferred when someone can use the design file on a new surface, explain why each major decision exists, reject an attractive but misaligned reference, and improve the file from observed evidence.

For implementation detail, continue to Design Language. For rendered proof, use How to Audit a Page.

Public resources

• Google Labs design.md
• Atlassian: what we learned testing portable design context

Context

• depends-on Purpose
• pairs-with Design Language
• uses How to Audit a Page
• uses Tight Five

Questions

Which design judgment must remain stable after the current implementation changes?

• Which reference relationship serves the reader job?
• Which identity, asset, or licensed material must remain private?
• Changes my mind: rendered evidence shows that a different explicit constraint produces a better reader outcome without weakening access or provenance.
• Next question: what is the smallest design decision that needs one durable owner?