Our blog used to look like every other SaaS blog. Gradient orbs under the hero. Colored ✓/✗ pills in comparison tables. Three typefaces loaded on every page. Backdrop-filter blur on every card. Em-dashes as connective tissue in every paragraph. That’s the visual and editorial vocabulary coding agents reach for by default. If you don’t tell them otherwise, that’s what you ship.

We spent a week converging the whole site toward a quieter, editorial direction modeled on anthropic.com/news. Warm cream background, near-black ink, one coral accent. Sans for structure, serif for voice. Zero shadows on content. 1px hairline dividers instead of shadow cards. 64 top / 32 bottom margins on every H2.

The question was how to keep future work on that system without handing every agent the 900-line internal spec. The answer came from an open-source project called awesome-design-md.

What DESIGN.md is

DESIGN.md is just a markdown file at the project root. No Figma exports. No JSON schema. No design-token DSL. It documents a design system in prose and tables that an AI coding agent can read straight from the filesystem. Markdown is the format LLMs read best.

The awesome-design-md repo curates 68 of these files, one per popular brand (Airbnb, Linear, Notion, Stripe, Tesla, Apple). Each follows a 9-section template: visual theme, color palette, typography, components, layout, depth, do’s and don’ts, responsive behavior, and an agent prompt guide. Developers drop one into their project and tell their agent “build me a page that looks like this.”

Our editorial DESIGN.md

We wrote nomadcrew-landing/DESIGN.md using that format. It captures the full converged system: 16-role type scale backed by Work Sans and Source Serif 4, 9-step 8px spacing, 3-value radius, zero elevation on content surfaces. Specific values with hex codes. Do’s and don’ts that ban blue links, colored pills, emojis in headings, em-dash connectives in prose, and photography in hero illustrations.

The full file lives at github.com/NomadCrew/nomadcrew-landing/blob/main/DESIGN.md.

The controlled test

A design spec only matters if it changes agent behavior. So we ran a test. A fresh agent was given the task of building an /about page, with one rule: read only DESIGN.md. No access to our internal editorial spec, no peeking at the existing blog layouts or stylesheets.

The output matched the system on the first try. Correct tokens pulled from CSS variables. No hex literals. Work Sans for headings, Source Serif 4 for body. 64/32 rhythm on H2 margins. 68ch article measure. Hairline-divided team rows. Inverse dark finale CTA with coral primary button. Even the fictional team bios read in the editorial voice, avoiding em-dash connectives and “not X, it’s Y” constructions without being told.

What the test surfaced

The test also found seven gaps in the file. The agent handled each one by making a reasonable guess, then flagged what was underspecified:

  1. Finale CTA padding used a raw “48px” instead of referencing the --space-6 token.
  2. Finale heading and body sizes (24/32 and 17/26) didn’t map to any named type role, so the agent hardcoded them.
  3. No guidance for pages that aren’t articles, blog lists, or heroes. Generic pages like About, Privacy, and Careers had no measure defaults.
  4. No reusable “Directory Row” component. Team lists, changelogs, and author pages all use the same hairline-row pattern as the blog index, but the file only named it for blog lists.
  5. A global a {} link rule conflicted with buttons, which must not underline by default.
  6. The spec’s /og-image.jpg placeholder contradicted the “no photography” rule. Placeholders need their own policy.
  7. Mobile H1 scaling (40px to 32px) was stated in prose but not tokenized.

We patched all seven in the same pass. The improvements stayed in DESIGN.md, which is where future agents will look.

Why this format works

Three things make DESIGN.md useful where other design-system artifacts fail for AI agents:

It’s one file at the root. Agents find it without being told. Any CLAUDE.md, AGENTS.md, or GitHub Copilot instruction can point at it in a sentence. Our contributors get onboarded the same way.

It’s prose plus tables, not JSON. Agents model meaning from surrounding sentences. A type-scale row that says “Work Sans 700, -0.01em tracking, used for article + page H1” gives an agent far more signal than an equivalent JSON object. The prose carries intent. The tables carry values.

The do’s and don’ts are explicit. Most design-system failures we’ve seen from AI agents are defaults the model grabs because nothing ruled them out. The file’s “Don’t” section enumerates those defaults directly: don’t use blue links, don’t use backdrop-filter blur, don’t use rounded-full radius on cards. Each rule is a bug-fix we already paid for.

What it unlocks

New agents joining a task now read DESIGN.md first. Our compare pages, tools pages, future landing sections, and future blog posts all route through the same format. External contributors building on top of our landing site can read one file instead of a week of commits. And when the design system evolves, one file changes instead of dozens.

If you’re running AI coding agents against a frontend codebase and struggle with generic-looking output, try this. Drop a DESIGN.md at the root. Fill in the nine sections. Run one controlled test where an agent builds a new page from only that file. Whatever gaps the test finds are your real design system’s gaps.