---
id: "concept-design-markdown"
type: "concept"
source_timestamps: ["00:11:06", "00:11:34"]
tags: ["design-systems", "file-formats", "agent-readable"]
related: ["entity-stitch", "concept-command-line-design", "action-extract-design-markdown", "entity-claude"]
definition: "An agent-readable text file that durably captures a project's complete design system, allowing AI to build features matching the visual language."
sources: ["s48-markdown-design-meeting"]
sourceVaultSlug: "s48-markdown-design-meeting"
originDay: 48
---
# Design Markdown (design.md)

## Definition

An agent-readable export format generated by tools like [[entity-stitch|Stitch]]. A `design.md` file captures a project's entire design system — colors, typography, spacing rules, component patterns — as a durable text record.

## What It Contains

A typical `design.md` documents:
- **Color tokens** — primary, secondary, semantic palettes
- **Typography** — type scale, font families, line heights
- **Spacing rules** — grid, padding, margin conventions
- **Component patterns** — button states, card styles, input behaviors
- **Tone/voice** — language register, microcopy guidelines

## Why It Replaces the Handoff Doc

In the legacy workflow, designers exported PDFs, Notion pages, or Figma 'redlines' for engineering. These were lossy and stale. `design.md` is **durable plaintext** that any coding agent (notably [[entity-claude-d48|Claude]]) can read and apply when generating new features. The design system becomes executable context for the agent.

This collapses one of the worst seams in the [[framework-sequential-bottleneck|sequential bottleneck]]: design-to-engineering handoff.

## Practical Use

- Generate a `design.md` from your own product via Stitch.
- Or extract one from a reference site you admire — see [[action-extract-design-markdown]].
- Feed it to a coding agent and ask for new features that conform.

## Related
[[entity-stitch]] · [[concept-command-line-design]] · [[entity-claude-d48]] · [[action-extract-design-markdown]]