create-design-md

Create a DESIGN.md File

Author a complete DESIGN.md file — the plain-text design system format that AI agents read to generate consistent UI. This skill guides through creating all 9 required sections with proper structure, ensuring the output matches the quality of the 58 existing files in the collection.

What is DESIGN.md?

DESIGN.md is a concept from Google Stitch — a markdown design system document optimized for LLM comprehension. It captures the complete visual DNA of a website or app: colors, typography, components, spacing, shadows, and design philosophy. Drop it in a project root and any AI coding agent instantly understands how the UI should look.

The 9-section format

Every DESIGN.md follows this structure. All 9 sections are required for a complete file.

Section 1: Visual Theme & Atmosphere

The opening narrative. Describe the design philosophy, visual mood, density, and key characteristics. This is prose, not specs — it tells the reader what the design feels like and why it works.

Include:

• Overall mood and philosophy (e.g., "cinematic reductionism", "warm editorial minimalism")
• Typography personality and approach
• Color story and emotional tone
• Key visual characteristics as bullet points (8-10 items with specific values)

Section 2: Color Palette & Roles

Every color with its hex value, CSS variable name (if known), and functional role. Group by purpose:

• Primary: Brand colors, main backgrounds, key text colors
• Interactive: Link colors, CTA backgrounds, hover states, focus rings
• Text hierarchy: Heading, body, secondary, muted, disabled
• Surface & borders: Card backgrounds, dividers, border colors
• Shadows: Shadow colors with rgba values
• Status colors: Success, warning, error (if present)

Format: **Color Name** (\#hex`): Description of when and how to use it.`

Section 3: Typography Rules

Font families with fallback stacks, then a complete hierarchy table:

Role	Font	Size	Weight	Line Height	Letter Spacing	Notes
Display Hero	...	...px	...	...	...	When to use
Section Heading	...	...	...	...	...	...
Body	...	...	...	...	...	...
Caption	...	...	...	...	...	...

Include at least: Display, Heading, Sub-heading, Body, Button, Caption, Micro. Add notes about OpenType features, variable font axes, or font-display strategy if relevant.

Section 4: Component Stylings

Detailed specs for each component with all states:

• Buttons: Primary, secondary, ghost/outline variants. Each with: background, text color, border, padding, radius, and states (hover, active, disabled, focus)
• Cards/Containers: Border treatment, shadow, radius, padding, background
• Inputs/Forms: Border style, focus ring, padding, placeholder color, error state
• Navigation: Layout, active state, hover state, mobile behavior
• Distinctive components: Anything unique to this design (e.g., pill badges, gradient borders)

Section 5: Layout Principles

• Spacing system: base unit and scale (e.g., 4px base with 4/8/12/16/24/32/48/64)
• Grid: columns, container max-width, gutters
• Whitespace philosophy (generous vs compact)
• Border-radius scale

Section 6: Depth & Elevation

• Shadow definitions for each level (low, medium, high elevation)
• Surface hierarchy (how surfaces layer)
• Any special depth effects (glassmorphism, gradients, overlays)

Section 7: Do's and Don'ts

Design guardrails:

• Do: 5-8 rules to always follow
• Don't: 5-8 anti-patterns to avoid These are the brand differentiators — the rules that make the design feel intentional.

Section 8: Responsive Behavior

• Breakpoints with pixel values
• Touch target sizes for mobile
• Collapsing strategy (how complex layouts simplify)
• Font size adjustments per breakpoint

Section 9: Agent Prompt Guide

Quick-reference summary for fast component generation:

• Quick color reference (5-6 key colors)
• Ready-to-use component prompts (3-4 examples showing how to instruct an agent)
• Iteration guidance (common adjustments and refinements)

Workflow

1. Determine the source

Ask the user where the design data comes from:

From a live website: The user provides a URL. Extract design tokens by analyzing the site's CSS, computed styles, and visual patterns. Note: you may need web access to fetch the site.

From existing CSS/code: The user has CSS files, Tailwind config, theme objects, or design token files. Extract and restructure into DESIGN.md format.

From scratch: The user describes the design they want. Generate a complete, internally consistent design system based on their description.

From visual reference: The user describes a mood or references existing brands. Create an original design system inspired by (but not copying) the reference.

2. Load a format reference

Read an existing DESIGN.md to calibrate the expected quality and format. Good references:

• design-md/stripe/DESIGN.md — comprehensive, well-structured, rich detail
• design-md/apple/DESIGN.md — excellent typography documentation
• design-md/claude/DESIGN.md — warm, editorial tone

Read one of these before writing to match the quality bar.

3. Draft all 9 sections

Write each section following the format above. For each section:

• Use specific values (hex codes, pixel sizes, weights) — never vague descriptions
• Include CSS variable names where known
• Write prose sections (1, 7) with personality — these aren't just data dumps
• The typography table must be complete with all columns filled

4. Validate completeness

Check the draft against this checklist:

• Section 1 has clear key characteristics bullet points
• Section 2 has all colors with hex values and functional roles
• Section 3 has font families with fallbacks AND a complete hierarchy table
• Section 4 has buttons with states, cards, inputs, and navigation
• Section 5 has a spacing scale with specific values
• Section 6 has shadow definitions with exact values
• Section 7 has at least 5 Do's and 5 Don'ts
• Section 8 has breakpoints with pixel values
• Section 9 has quick color reference and example prompts

5. Output the file

Write to DESIGN.md in the location the user specifies (default: project root).

The first line should be: # Design System Inspiration of {Brand Name}

6. Contributing to the collection

If the user wants to add this to the awesome-design-md repo:

1. Create a new directory under design-md/{lowercase-name}/
2. Place the DESIGN.md file there
3. Create a README.md with a brief description
4. Update design-md/_index.md with the new entry
5. Open a PR following the CONTRIBUTING.md guidelines