Converting my Brand Kit to DESIGN.md

When building a digital product today, you are no longer just designing for human engineers. You are designing for AI agents.

Historically, my design system in monospace.studio was split across multiple files:

• •docs/portfolio-spec/07_Brand_Evolution_Kit.md handled the human rationale, typography roles, and component constraints.
• •styles/tokens.json handled the machine-readable values.
• •styles/tokens.css provided the implementation.

While this decoupled architecture made sense a few years ago, it created friction when onboarding AI coding agents like Claude, Cursor, and Antigravity. Agents had to read multiple files, cross-reference token names, and infer design intent.

Enter DESIGN.md

To solve this, I recently migrated my entire design system to the Stitch DESIGN.md model.

The concept is elegantly simple: a single .md file in the root of the repository that serves as the definitive source of truth for both human and machine.

The Structure

My new DESIGN.md uses YAML frontmatter to encapsulate the exact token values:

---
colors:
  light:
    ink: "#111111"
    paper: "#FAFAFA"
typography:
  font-families:
    mono: "PT Mono, monospace"
---

Below the frontmatter, standard Markdown sections provide the human context, rules, and component documentation:

## Typography
The typographic scale uses a clearer two-and-an-accent stack:
* **Voice / labels:** `PT Mono` Regular.
* **Body:** `Inter`. Adds neutral readability at long-form sizes.

The Benefits

1. •Agent Efficiency: An AI agent now only needs to read one file to understand what the tokens are and how to use them.
2. •Zero Drift: I no longer have to worry about tokens.json drifting out of sync with the documentation in the Brand Kit.
3. •Frictionless Updates: Updating a token value or a UI constraint is a single PR against a single file.

By adopting DESIGN.md, I've made monospace.studio natively accessible to the next generation of AI-driven development tools. Evolve, not redesign.