The design-system.md export

Of the three files Tostada exports, design-system.md is the one that fundamentally changes how AI tools interact with your codebase. tokens.css is for the browser; design-system.json is for tooling; design-system.md is for agents.

What's in it

The Markdown is generated from your library state in a stable order:

1. Header — library name, generation timestamp, optional description
2. ## Tokens — three sub-sections:
   • ### Primitives — table of every primitive token, grouped by group field
   • ### Semantic aliases — auto-categorized by ID prefix (bg-, fg-, border-, other)
   • ### Component variable bindings — every component variable with its light + dark resolution
3. ## Layout principles — split into ### Page shells and ### Page layouts; each principle renders its fields as a bullet list with units, then any notes as a blockquote
4. ## Navigation hierarchy — primary nav placement, breakpoints, breadcrumb policy, focus order
5. (Future) Per-component application rules

The same content as the Library, in the same order. The Library is the editor; the Markdown is the export.

Why Markdown

Three reasons:

• Humans read it. A new hire can open it in any editor and skim the whole system in five minutes.
• AI agents parse it. Claude Code, Cursor, v0, and Claude Project memory all accept Markdown as system context.
• It's a plain text file. No vendor format, no API, no plugin. The file is the contract.

How AI agents consume it

The export uses three conventions that improve AI ingestion:

• Tables for tokens. Tokens render as | ID | Name | Value/Reference | Dark | tables, which agents reliably read as structured data.
• Imperative bullets for rules. Do / Don't lists become bullet lines in active voice — what to do, what not to do, full stop.
• Stable section order. The same headings always appear in the same order, so an agent can navigate with anchors (#tokens, #layout-principles).

See feeding design-system.md to AI agents for tool-specific recipes.

The Spread also reads it

The Spread pipeline takes your design-system.md as input — it's the spec the rebuild conforms to. This is why the same imperative voice that helps AI code-generation also helps automated retheming: both are agents reading the same artifact.

When it updates

The Documentation tab regenerates the file on every render — there's no build step. Edit a token, switch tabs, watch the diff. Click Copy to clipboard or Download ZIP to grab the file plus its CSS and JSON siblings.

Where this lives in code

• Generator: src/lib/docs.ts — generateDesignSystemMd
• UI: Library → Documentation → design-system.md tab