DESIGN.md Contract

Use this when coding-agent practice evidence includes DESIGN.md, design tokens, visual/UI generation, design-review skills, or repeated UI style drift. This is a readiness reference, not a full authoring guide. For creation or detailed review, hand off to design-md-review when available.

Meaning

DESIGN.md is a plain-text visual design-system contract for humans and coding agents: YAML frontmatter carries machine-readable tokens, and Markdown carries design rationale and guardrails.

When authoring support is needed, load the complete packaged example after this contract. It is a generic structural fallback, not product evidence: replace its illustrative values only with inspected project sources.

Do not route lowercase design.md architecture specs, requirements.md, or tasks.md here. This reference is only about uppercase DESIGN.md visual identity and design-token guidance.

Applicability

Apply only when the target owns user-facing UI, visual reports, generated UI, brand surfaces, component libraries, themes, or design systems. For backend, CLI, SDK, data, or infra projects, mark not applicable.

Outside a confirmed frontend or visual project, absence is a recommendation, not a risk, unless repeated visual drift, inconsistent generated UI, or invented local style rules are observed. In the default Agent Work Loop repository scan, a confirmed frontend or visual project without an exact uppercase root DESIGN.md is one ordinary Low finding mapped to Task Understanding / Relevant Context. Projects without confirmed frontend or visual implementation evidence remain not applicable.

Inspect

Look for DESIGN.md, Tailwind config, CSS variables, theme files, token JSON/YAML, Storybook, component docs, design-review skills, lint commands, CI checks, hooks, or reports. Classify evidence separately:

• Present: DESIGN.md exists.
• Structured: it has frontmatter plus readable sections.
• Token-ready: frontmatter uses top-level colors, typography, rounded, spacing, and components groups.
• Agent-ready: prose explains product feel, component use, states, and do/don't rules.
• Aligned: tokens map to implementation theme, CSS variables, Tailwind, component props, or Storybook.
• Backstopped: lint, diff, export, CI, hook, or review gate checks drift.

File presence is not enforcement.

Classify an exact root DESIGN.md as a project Rules asset beside AGENTS.md. Keep provider-native Rules first, then AGENTS.md, then the visual contract. Lowercase architecture design.md and nested design notes do not become this Rules asset.

Quality Signals

Strong evidence:

• Semantic color roles, foreground/background pairs, and state colors.
• Structured typography, spacing, and radius scales.
• Component token maps for real UI surfaces and states such as button-primary-hover or text-input-focused.
• Markdown sections for Overview, Colors, Typography, Layout, Elevation & Depth, Shapes, Components, and Do's and Don'ts.
• Rationale that says when to use a token, when not to use it, and what agent mistake it prevents.
• Accessibility guidance for contrast, focus-visible, color-not-alone, reduced motion, forms, and error states.

Weak evidence:

• Prose-only brand description with no token frontmatter.
• Nested tokens: instead of top-level token groups.
• Raw names such as blue500 without semantic roles.
• Component names without variants, states, or token mappings.
• Vague guidance such as "make it clean".
• Tokens that drift from implementation theme or current product.

Validation

Prefer cross-platform commands:

npx -p @google/design.md designmd lint DESIGN.md
npx -p @google/design.md designmd diff DESIGN.md DESIGN-next.md
npx -p @google/design.md designmd export --format css-tailwind DESIGN.md

Use the designmd alias in package scripts because the design.md binary name can collide with Markdown file associations on Windows.

Lint proves structure and token checks. Export proves tokens can feed Tailwind/CSS/DTCG workflows. Diff is drift evidence, not visual QA by itself.

Recommendation Rules

Recommend DESIGN.md when agents generate UI and invent colors, spacing, typography, radii, or component variants; when a visual system has no agent-readable source of truth; or when tokens exist without usage rationale.

When the file is missing, inspect existing UI evidence before authoring. Use design-system-capture when the contract must be inferred from code, screenshots, Figma, themes, or components, then use design-md-review to author or review the root file when those Skills are available. Preserve inferred rules as inference and mark unresolved policy needs-design-decision instead of inventing brand decisions.

When those optional Skills are unavailable, use the complete packaged example as the structural fallback while keeping every project value evidence-bound.

Recommend lint, CI, or hooks only after the team has a stable DESIGN.md shape. Route screenshot/CSS/Figma/live-UI extraction to design-system-capture first when available.

Projection

Use DESIGN.md as positive AI Agent Practices evidence:

• Context Map: agents can understand the visual language quickly.
• Quality Gates: token contracts and lint/export checks reduce style drift.
• AI Readiness: UI generation has a reusable visual source of truth.
• Rules inventory: the root file appears beside AGENTS.md; in the standalone per-asset Rules evaluator it can raise the bounded surface mean without removing another Rule's warning or worst risk.
• Agent Work Loop: static presence supports relevant-context; routed and task-applied use can support stronger Task Understanding evidence and score only within the model's existing evidence ceilings.

Do not add a new scorecard row. Do not let visual design docs replace executed build, lint, typecheck, preview, accessibility, or visual-regression evidence.

Output Shape

### DESIGN.md contract
- **Scope**: in scope | not applicable | needs evidence
- **Evidence level**: Present | Structured | Token-ready | Agent-ready | Aligned | Backstopped
- **Strongest evidence**: <file, command, report, or implementation mapping>
- **Main gap**: <missing token/rationale/alignment/backstop>
- **Recommendation**: <smallest next action>