Introduction

What design.md is and why we built it.

The shape

DESIGN.md is a single Markdown file with YAML frontmatter at the top and prose body below. The frontmatter is the machine-readable token bundle — colors, typography, spacing, radii, shadows, components. The body is the prose explanation: voice, lineage, do’s and don’ts.

---
name: Stripe
tagline: Infrastructure for the internet economy
colors:
  bg: '#ffffff'
  text: '#0a2540'
  brand: '#635bff'
  brand-alt: '#0055de'
  text-dim: '#425466'
  border: '#e6ebf1'
  surface: '#f6f9fc'
  on-brand: '#ffffff'
typography:
  body:
    family: '"Sohne Buch", -apple-system, sans-serif'
    size: '16px'
    weight: '400'
    lineHeight: '1.6'
  heading:
    family: '"Sohne Kraftig", -apple-system, sans-serif'
    weight: '500'
radii:
  sm: '4px'
  md: '8px'
  lg: '12px'
---

# Stripe

Stripe's marketing surface is clean, layered, and confident ...

## 1. Visual Theme & Atmosphere

White canvas with deep navy text. The brand purple (`#635bff`) appears
sparingly — buttons, links, and accent elements only ...

What’s in the catalog

We spent about 6 weeks filling in 300 brands by hand. Stripe, Linear, Notion, Anthropic, OpenAI, Vercel, Apple, Airbnb, Plaid, Grafana, Pinterest, Visa, IKEA, T-Mobile, and 286 others. Each entry has:

  • A full token bundle in YAML frontmatter — colors, typography, radii, spacing, shadows, components
  • A 15-section prose body covering visual theme, color palette with role mapping, typography rules, component styling, layout, motion, accessibility, voice, dark mode, lineage, do’s and don’ts, and an agent prompt guide
  • A live iframe preview rendered from the tokens alone — no screenshots, no hand-tweaked CSS

Tokens are extracted from production sites via Playwright and chrome-devtools-mcp plus manual cross-check, not scraped. Every catalog entry links to its source page.

Stripe — rendered from tokens alone

No screenshots. The frame above is a static HTML page rendered using only the tokens in stripe.design.md.

CLI vs MCP vs Catalog browser

Three surfaces, three audiences:

  • The CLI — npx @webdesignhot/design-md add stripe drops the full Stripe DESIGN.md into your repo. For when you want the tokens in your codebase as a file.
  • The MCP server — @webdesignhot/design-md-mcp exposes the catalog to MCP-compliant agents (Claude Code, Cursor, Codex, Cline). For when an agent generates UI and needs tokens during generation, not after.
  • The hosted catalog at webdesignhot.com/design.md/ — browse, search, compare, copy. For exploring brands and finding references.

Why we built it

Every time we started a new project, the landing page took two or three weeks and our designs looked worse than the incumbents with three-person marketing teams. We kept opening reference sites in DevTools, eyedropping colors, jotting font sizes in Notes.app, and losing the notes by the next project.

We designed a structured format to capture it once. Then we sat down for 6 weeks and filled in 300 brands.

The CSS is in the DOM. Why isn’t it just a file?

What it isn’t

  • Not a component library. No React, no Tailwind classes. Just tokens. Use them with whatever component library you have.
  • Not a replacement for Figma. Designers, this is the implementation side. The token values that end up in CSS.
  • Not “all brands.” We have 300. There are named gaps — telco, big banks, consulting firms. PRs welcome; we verify roles and completeness before merging.

Next steps