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:

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