DESIGN.md generator

DESIGN.md generator for your brand

AI coding agents build faster than they design. A DESIGN.md file gives them your colors, typography, spacing and rules in one place, so every page they generate looks like your brand instead of a generic template.

Sample DESIGN.md (default kit)

This is real output from the generator, using the default kit. Open the editor to make it yours.

---
version: alpha
name: "My brand kit"
description: "Design system with Space Grotesk headings, Inter body text and a #635BFF brand color."
colors:
  primary: "#635bff"
  on-primary: "#ffffff"
  primary-strong: "#1f14ff"
  primary-soft: "#ececf9"
  brand:
    "50": "#efeefb"
    "100": "#d8d6f9"
    "200": "#bfbcf9"
    "300": "#a39ffa"
    "400": "#8680fc"
    "500": "#635bff"
    "600": "#3329f9"
    "700": "#150bdb"
    "800": "#140d9a"
    "900": "#110d5b"
    "950": "#090821"
  light:
    surface: "#ffffff"
    surface-container: "#f7f7fb"
    surface-container-high: "#eaeaf7"
    outline: "#d8d8e9"
    on-surface: "#2d2c4f"
    on-surface-strong: "#0e0d26"
    on-surface-muted: "#595780"
    primary: "#635bff"
    on-primary: "#ffffff"
  dark:
    surface: "#0d0d15"
    surface-container: "#13131e"
    surface-container-high: "#1b1a2b"
    outline: "#2b2a41"
    on-surface: "#cfcede"
    on-surface-strong: "#f2f2f8"
    on-surface-muted: "#9796b0"
    primary: "#726aff"
    on-primary: "#0d0d14"
typography:
  h1:
    fontFamily: "Space Grotesk"
    fontSize: "61px"
    fontWeight: 700
    lineHeight: 1.1
    letterSpacing: "-0.02em"
  h2:
    fontFamily: "Space Grotesk"
    fontSize: "48.8px"
    fontWeight: 700
    lineHeight: 1.1
    letterSpacing: "-0.02em"
  h3:
    fontFamily: "Space Grotesk"
    fontSize: "39.1px"
    fontWeight: 700
    lineHeight: 1.1
    letterSpacing: "-0.02em"
  h4:
    fontFamily: "Space Grotesk"
    fontSize: "31.3px"
    fontWeight: 700
    lineHeight: 1.1
    letterSpacing: "-0.02em"
  h5:
    fontFamily: "Space Grotesk"
    fontSize: "25px"
    fontWeight: 700
    lineHeight: 1.1
    letterSpacing: "-0.02em"
  h6:
    fontFamily: "Space Grotesk"
    fontSize: "20px"
    fontWeight: 700
    lineHeight: 1.1
    letterSpacing: "-0.02em"
  body-lg:
    fontFamily: "Inter"
    fontSize: "18px"
    fontWeight: 400
    lineHeight: 1.6
  body-md:
    fontFamily: "Inter"
    fontSize: "16px"
    fontWeight: 400
    lineHeight: 1.6
  body-sm:
    fontFamily: "Inter"
    fontSize: "14px"
    fontWeight: 400
    lineHeight: 1.6
rounded:
  sm: "8px"
  md: "16px"
  lg: "24px"
  full: "9999px"
spacing:
  xs: "4px"
  sm: "8px"
  md: "16px"
  lg: "24px"
  xl: "40px"
  2xl: "64px"
motion:
  fast:
    duration: "150ms"
    timingFunction: "ease-out"
  base:
    duration: "250ms"
    timingFunction: "cubic-bezier(0.2, 0, 0, 1)"
components:
  button-primary:
    backgroundColor: "{colors.primary}"
    textColor: "{colors.on-primary}"
    rounded: "{rounded.md}"
    typography: "{typography.body-md}"
  button-primary-hover:
    backgroundColor: "{colors.primary-strong}"
  button-secondary:
    backgroundColor: "transparent"
    textColor: "{colors.light.on-surface-strong}"
    rounded: "{rounded.md}"
  card:
    backgroundColor: "{colors.light.surface-container}"
    rounded: "{rounded.lg}"
  input:
    backgroundColor: "{colors.light.surface}"
    textColor: "{colors.light.on-surface}"
    rounded: "{rounded.md}"
  tag:
    backgroundColor: "{colors.primary-soft}"
    textColor: "{colors.primary-strong}"
    rounded: "{rounded.full}"
---

# My brand kit

## Overview

A clean, modern interface built around a single #635BFF brand color. Space Grotesk gives headings their voice; Inter keeps long text comfortable. Corners use a 16px radius. Whitespace is generous and the page stays calm so the brand color can lead.

## Colors

- **Primary (#635BFF):** the brand color for buttons, links, focus rings and active states.
- **Primary strong (#1F14FF):** hover and pressed states.
- **Surface (#FFFFFF / #F7F7FB):** page and card backgrounds in light mode.
- **Surface alt (#EAEAF7):** alternate sections and subtle fills.
- **Ink strong / ink / muted (#0E0D26 / #2D2C4F / #595780):** headings, body text and helper text.
- **Border (#D8D8E9):** dividers and outlines.

Dark mode uses `colors.dark.*`: page #0D0D15, cards #13131E, body text #CFCEDE. 
Never place text on a background below 4.5:1 contrast (3:1 for large text).

## Typography

Headings use **Space Grotesk** (weight 700, line height 1.1, tracking -0.02em). 
Body text uses **Inter** (weight 400, line height 1.6). Load both from Google Fonts or self-host them.

Sizes in the tokens above are the desktop (1120px viewport) values. The scale is fluid: base 16px, ratio 1.2 on mobile (360px viewport) to 1.25 on desktop. Use these clamp() values in CSS:

```css
:root {
  --text-h1: clamp(2.9875rem, calc(2.5967rem + 1.737vw), 3.8125rem);
  --text-h2: clamp(2.4875rem, calc(2.2211rem + 1.184vw), 3.05rem);
  --text-h3: clamp(2.075rem, calc(1.9003rem + 0.776vw), 2.4438rem);
  --text-h4: clamp(1.725rem, calc(1.6155rem + 0.487vw), 1.9563rem);
  --text-h5: clamp(1.4375rem, calc(1.3783rem + 0.263vw), 1.5625rem);
  --text-h6: clamp(1.2rem, calc(1.1763rem + 0.105vw), 1.25rem);
  --text-body-lg: 1.125rem;
  --text-body-md: 1rem;
  --text-body-sm: 0.875rem;
}
```

## Layout

Use an 8px spacing rhythm (4px for tight groups). Content max width around 1120px, centered, with 16px side padding on phones and 24px or more on larger screens. Stack columns on mobile.

## Elevation & Depth

Prefer thin borders and very soft shadows (for example `0 1px 2px rgb(0 0 0 / 0.06)`). Avoid heavy drop shadows.

## Shapes

Cards and inputs use 16px–24px corners; tags and avatars are fully rounded.

## Components

- **Buttons:** primary uses the brand color with its `on-primary` text; secondary is outlined. Provide hover, focus-visible and disabled states.
- **Cards:** surface background, 1px border, generous padding.
- **Inputs:** surface background, visible border, brand-colored focus ring.
- **Tags:** soft brand tint with strong brand text.

## Do's and Don'ts

- Do use the brand color sparingly so actions stand out.
- Do keep body text at 16px or larger on mobile.
- Don't introduce colors or fonts outside this file.
- Don't rely on color alone to convey meaning.

How it works

  1. Open the editor and choose a brand color, heading font and body font.
  2. Tune corner style, mood and the fluid type scale until the preview feels right.
  3. Open Export, choose DESIGN.md, then copy it or download the file.
  4. Commit DESIGN.md to your repository and point your AI tool at it.

What is a DESIGN.md file?

DESIGN.md is an open format from Google Labs for describing a design system to AI coding agents. It combines machine-readable YAML tokens (colors, typography, rounded corners, spacing, components) with plain-language guidance on how to use them.

WebStyleKit follows that format: valid YAML front matter first, then the prose sections in the order the spec defines. Fluid type sizes use valid pixel values in the tokens, with the responsive clamp() values spelled out in the Typography section.

How to use it in your project

Save the file as DESIGN.md in the root of your repository. In Claude Code you can mention it from CLAUDE.md; in Cursor add it to your rules; in v0 or Lovable paste it into the first prompt. Prefer a single paste? Use the AI prompt export, which includes the CSS variables inline.

Frequently asked questions

Is the DESIGN.md generator free?

Yes. Everything runs in your browser and there is no account or limit.

Does it include dark mode?

Yes. Light and dark color groups are generated, and dark mode is derived so text stays readable.

Which AI tools can use a DESIGN.md file?

Any tool that reads project files or accepts a long prompt, including Claude Code, Cursor, Windsurf, Lovable and v0.