Feeding `design-system.md` to AI agents

design-system.md is the input that turns a generic AI coder into one that uses your design system. Here's how to feed it to each of the major tools.

See the design-system.md export (concepts) for what's inside the file and why Markdown.

Claude Code (CLI)

Two options, in order of strength:

Option A — vendor into CLAUDE.md (best for one project)

Append the contents of design-system.md into your repo's CLAUDE.md:

# Project conventions
…

# Design system

<paste design-system.md here>

Claude Code reads CLAUDE.md automatically on every session in that working directory. No setup.

Option B — reference by path (best for several projects sharing a system)

Drop design-system.md somewhere in the repo (e.g. docs/design-system.md) and add a one-liner to CLAUDE.md:

## Design system
For tokens, layout principles, and per-component rules see `docs/design-system.md` — treat it as authoritative when generating UI code.

Claude Code will read the file when relevant.

Cursor

Cursor reads project-level rules from .cursorrules (legacy) or .cursor/rules/ (current). Add a rule file:

# .cursor/rules/design-system.mdc
---
description: Project design system — apply when generating UI.
alwaysApply: true
---

<paste design-system.md here>

Reload the project. Cursor will apply the rules to every UI suggestion.

v0 (Vercel)

In a v0 project, paste design-system.md into Project Context in the project settings. It becomes part of every generation prompt.

Claude.ai (Projects)

In a Claude.ai Project:

Open the Project sidebar
Click Add to project knowledge
Upload design-system.md directly, or paste its content as text

The file becomes part of every conversation's system context. Updates: re-upload when the system changes.

Generic agents

Any agent that supports a system prompt or a project-level context document can take design-system.md. The conventions that make it AI-friendly (imperative bullets, stable section order, tables for tokens) work regardless of which tool reads it.

When to refresh

Every time you change tokens, principles, or rules. There's no Tostada-side push to your AI tool — you re-export and re-feed.

A workflow that scales: keep design-system.md committed to the repo, regenerate on every change, and let your AI tool read it from the repo path automatically.

What changes in the file

The export is stable and deterministic — same library state produces the same Markdown, byte-for-byte. Diffs in design-system.md between commits reflect real design system changes, which is exactly what you want a teammate (or AI agent) reviewing the diff to see.

Feeding design-system.md to AI agents