How Claude Code + DESIGN.md Turns Markdown into a Low‑Cost UI Designer

Background

AGENTS.md defines how an AI builds a project. When AI generates UI, the visual output often mismatches the product’s style—incorrect button colors, fonts, spacing, or animations.

DESIGN.md Concept

Google Stitch introduced DESIGN.md as a sibling to AGENTS.md. DESIGN.md describes the visual appearance and feel of a project.

File Roles

AGENTS.md

– read by code agents – defines construction instructions. DESIGN.md – read by design agents – defines visual style.

Why DESIGN.md Works

A plain‑text design system document enables an AI design agent to produce style‑consistent UI without requiring Figma exports, JSON schemas, or special tooling.

Collected Repository

VoltAgent compiled an open‑source collection at https://github.com/VoltAgent/awesome-design-md containing DESIGN.md files from 73 mainstream websites, organized by category (AI platforms, tools, editors, design systems, content sites, SaaS products, personal pages).

Simple Workflow

Copy a DESIGN.md into the project root, prompt the AI with “build me a page that looks like this”, and obtain pixel‑perfect UI that matches the specification.

Markdown is used because large language models parse markdown directly, eliminating the need for additional parsing or configuration.

Repository Contents (selected examples)

Claude – Anthropic style, warm terracotta tones, clean editorial layout.

Cohere – Enterprise AI platform, lively gradients, data‑dense dashboards.

ElevenLabs – AI voice, dark cinematic UI, audio‑wave aesthetics.

Mistral AI – French minimalism, purple palette.

Ollama – Terminal‑first, monochrome simplicity.

OpenCode AI – Developer‑oriented dark theme.

Replicate – White canvas, code‑first focus.

Runway – Creative AI tool, festival‑style aesthetics.

Together AI – …

DESIGN.md Structure

Brand positioning / personality adjectives

Color palette (primary, secondary, semantic)

Typography (family, size, weight, line‑height)

Spacing system

Corner radius / shadow / border specifications

Component examples (buttons, cards, forms, navigation)

Motion principles

Overall vibe description (e.g., restrained, lively, cinematic)

All items are written in natural language within a single markdown file, without nested JSON or token structures.

How to Use

Locate a desired website style on the getdesign.md site.

Download the corresponding DESIGN.md into the project root.

Prompt an AI code assistant (e.g., Claude Code, Cursor, Codex) with “Based on this DESIGN.md, create a XX page”.

Advanced usage includes mixing elements from multiple DESIGN.md files, distributing a single DESIGN.md across a team to ensure consistent output, and pairing DESIGN.md with AGENTS.md to align visual and engineering constraints.

Evaluation

The primary insight is that the DESIGN.md concept itself merits inclusion in development workflows. Aligning visual constraints via DESIGN.md and engineering constraints via AGENTS.md makes AI‑generated code more predictable.

For individual developers, a single DESIGN.md eliminates the repetitive step of providing Figma links, brand guides, and color details to the AI.