design.md spec
What is design.md?
A machine-readable design system specification for AI coding agents. One file, in your repo, that gives every AI tool a shared understanding of your visual identity.
AI coding agents are increasingly capable of writing UI code — but they have no standard way to understand a product's visual identity. Every team works around this differently: pasting screenshots into prompts, writing long system prompts that describe colors and fonts, or hoping the agent can infer styles from existing code. None of these approaches scale, and none of them are portable across tools.
Engineers end up recreating styles from memory, or re-explaining the same design decisions every session. Designers watch their carefully considered systems get approximated instead of followed. Design.md formalizes this as a spec — a YAML-fronted markdown file that lives in your repo alongside your code, and can be read by any AI tool that understands plain text.
---
name: Acme Corp
url: https://acme.com
extracted_at: 2024-01-15
confidence: 0.91
---
# Design System
## Colors
| Token | Value | Usage |
|----------------|-----------|---------------------|
| primary | #0F172A | Text, headings |
| accent | #6366F1 | CTAs, links, focus |
| background | #FFFFFF | Page background |
| muted | #F8FAFC | Cards, inputs |
| destructive | #EF4444 | Errors, warnings |
## Typography
- **Display:** Inter, 700, 48px / 1.0
- **Heading:** Inter, 600, 32px / 1.1
- **Body:** Inter, 400, 16px / 1.5
- **Caption:** Inter Mono, 400, 12px / 1.4
## Components
### Button (primary)
- Background: `accent`
- Text: `#FFFFFF`
- Border radius: `6px`
- Padding: `12px 24px`
- Hover: background lightens 10%
### Card
- Background: `background`
- Border: `1px solid #E2E8F0`
- Border radius: `12px`
- Shadow: `0 1px 3px rgba(0,0,0,0.08)`
## Dark mode
Dark mode is supported. Background flips to `#0F172A`, text to `#F8FAFC`.
Try it with your site.
Paste a URL →