Tool: DESIGN.md, the look written down

What it does

• One markdown file that holds the look of a site.
• Tokens (named values) sit at the top in YAML. Written rules sit below.
• Agents read it before every change, so the look stays the same.

When to reach for it

• The direction is chosen and building is about to start.
• Several agents or sessions will touch the site.
• The look has started to drift.
• You've inherited a site whose look lives only in its code. Use document to write it down.

How to use it

Write it by hand, in the format awesome-design-md uses

• Top-level keys: version, name, description, colors, typography, rounded, spacing, components.
• colors maps role names (primary, ink, canvas, hairline…) to hex values.
• typography holds named roles, each with fontFamily, fontSize, fontWeight, lineHeight and letterSpacing.
• rounded and spacing are named scales. Claude's file runs corners from 4px to a 9999px pill, and spacing from 4px to 96px.
• components builds each element from token names in braces. Never type a raw hex colour.
• Sections below, in order: Overview, Colors, Typography, Layout, Elevation & Depth, Shapes, Components, Do's and Don'ts.

Or generate it from existing code with impeccable

• Run /impeccable document.
• It reads, in order: CSS custom properties, the Tailwind config, CSS-in-JS themes, token files, the component library, the global stylesheet, then styles from the rendered site.
• It gives colours descriptive names ("Deep Muted Teal-Navy", not "blue-800").
• It adds one named guiding image, the "Creative North Star", and short named rules, such as "The One Voice Rule. The primary accent is used on ≤10% of any given screen."
• It never overwrites an existing DESIGN.md silently. It offers refresh, overwrite or merge.

Keep it honest

• impeccable's rule checker flags any font, colour, corner size or text size not declared in DESIGN.md.
• 34 awesome-design-md files say to run npx @google/design.md lint DESIGN.md after edits. Nobody here has run it.
• When to write it is disputed. See Drawer 5.

What happened when we used it

• Our build wrote the look down in one DESIGN.md, in this collection's format, partway through, once three versions existed.
• Colours, type, spacing and components came first, then layout, motion, voice, and what to do and not do.
• Every later change reads it, so the look doesn't drift.
• The page's advice: when you turn the build into a skill for a new site, make DESIGN.md the first thing it writes.

Source

• Source: awesome-design-md (the format and 84 examples).
• Source: impeccable (the document command and the rule checker).