Guide

Use DESIGN.md with your coding agent

DESIGN.md is a plain markdown file that tells a coding agent what your product should look like. Agentic UI Kit writes it from your theme, reads it back without losing anything, and points every agent at it before it builds UI.

What a DESIGN.md holds

The format comes from Google Labs (open source since April 2026, the same format Google Stitch imports and exports). A YAML block at the top lists the design tokens: colors, typography, rounded, spacing and components. Markdown sections below explain how to use them: Overview, Colors, Typography, Layout, Elevation & Depth, Shapes, Components, Do's and Don'ts.

A file written by the kit adds one more section, ## Agentic UI Theme, with the exact theme as JSON. That is what makes a round trip lossless: Theme Studio to DESIGN.md to the CLI and back gives the same theme id. A DESIGN.md from another tool has no such section, so the kit maps its tokens onto a theme and lists every value it could not use.

Create one

In the Theme Studio, open Use in project and copy or download DESIGN.md. In a project, the CLI writes it from the applied theme, or from the project's Design DNA when no theme is applied. It replaces a DESIGN.md it wrote before and never overwrites yours without --yes.

In your project folder

agentic-ui design export
agentic-ui design export corporate --out -   # print a preset's DESIGN.md

Apply a DESIGN.md

Import is a dry run by default: it validates the file, lists any problems with their line numbers, and prints the same plan as agentic-ui theme apply. Add --yes to write the theme. The Theme Studio's Import also accepts a pasted or uploaded DESIGN.md, and shows the values it will not use before it replaces your theme.

In your project folder

agentic-ui design check DESIGN.md
agentic-ui design import DESIGN.md
agentic-ui design import DESIGN.md --yes

How your agent uses it

agentic-ui setup (and init) writes an Agentic UI Kit section into AGENTS.md: search the catalog before writing UI, follow DESIGN.md, install with the CLI. The section sits between markers, so a re-run updates it and keeps everything you wrote around it. An existing CLAUDE.md gets an @AGENTS.md line so Claude Code reads it too.
The MCP tool get_design_context returns DESIGN.md parsed: resolved tokens, the prose sections, the do's and don'ts, and whether it matches the applied theme. understand_project tells the agent when the file exists.
The four agent skills read it in their first step (scripts/design.mjs). When DESIGN.md and the applied theme disagree, the agent asks you which one wins before it installs anything.

No MCP or skills in your agent? The Theme Studio also exports AGENTS.md: paste its section into yours. More on the files each agent reads is in Docs.

Example prompt

Paste into your agent

Build a settings page for billing contacts and tax details.
Follow DESIGN.md: use its tokens and its do's and don'ts.
Search the catalog first (get_design_context, then find_reusable_ui) and install what fits with agentic-ui add.