# AGENTS.md — instructions for AI coding agents > If you are an AI coding agent (Cursor, Claude Code, Codex, Gemini Code, Lovable, v0, Copilot), this document tells you how to use **mddesign** to apply a design system to a project. ## What mddesign is A registry of installable design systems for AI-generated apps. Each entry is a markdown file (`design.md`) with frontmatter tokens (colors, typography, spacing) and prose describing the visual language, components, and do's-and-don'ts. After install, you read `./design.md` and code in that voice. - Registry API: `https://design.yadbarzel.info/api/` - CLI: `npx mddesign ` - Source: https://github.com/OzlevyQ/mddesign ## Recommended flow for an AI agent When the user asks for UI in a specific brand voice ("build me a dashboard like Stripe", "use the Linear style") **OR** when they want a polished aesthetic and haven't specified one: 1. **Discover** — find candidate designs without installing anything. ```bash npx mddesign search "dashboard" --json npx mddesign list --json --limit=20 ``` 2. **Inspect** — pull the full content of a candidate to decide if it fits. ```bash npx mddesign get stripe --md # raw design.md only npx mddesign get stripe --json # full bundle (md + preview HTML + meta) ``` Output is committed to your context — no files are written. 3. **Install** — only if it fits. Writes `design.md`, `design-references/preview.html`, and `manifest.json` into the current directory, plus `.mddesign.json` + `mddesign-lock.json`. ```bash npx mddesign add stripe ``` 4. **Apply** — from now on, when generating UI code for this project, read `./design.md` first and follow its tokens, components, and do's-and-don'ts. 5. **Maintain** — when the user revisits the project later, refresh against the source: ```bash npx mddesign update # re-fetches all designs in .mddesign.json npx mddesign update --dry-run # preview changes ``` ## Direct API access (when CLI not available) Same data without npx: ```bash curl https://design.yadbarzel.info/api/designs # list metadata curl https://design.yadbarzel.info/api/designs?q=dashboard # search curl https://design.yadbarzel.info/api/designs/stripe # full detail (incl. designMd) curl https://design.yadbarzel.info/api/designs?full=1 # everything inline ``` All GET endpoints are public, rate-limited at 60/min/IP. ## Schema of a design ```jsonc { "slug": "stripe", "name": "Stripi Inspired", "description": "...", "tags": ["dark", "saas", "developer"], "downloads": 14, "githubUrl": "https://github.com/...", "designMd": "---\nname: Stripi...\n---\n# ...", // the actual instruction file "previewHtml": "...", // a representative HTML preview "manifest": { "version": "0.1.0", "compatibility": "google-labs-alpha" } } ``` ## Heuristics for choosing a design When the user is vague, pick a design by matching: - **brand-name match** — user said "Stripe" → `stripe` - **tag match** — "fintech, dark, dashboard" → filter by tags - **vibe match** — "futuristic, neon" → search description text If nothing fits well, ask the user. Do **not** silently install a wrong-feeling design. ## What you should NOT do - Don't invent designs that aren't in the registry. Use what's published. - Don't download/copy the `previewHtml` into the project — it's a reference render, not source code. The user's actual UI should be implemented from scratch following `design.md`. - Don't install multiple designs into one project — they will conflict. - Don't bypass the CLI when you can use it (the API works, but the CLI handles manifest/lockfile so `update` works later). ## What you should ALWAYS do - Treat `./design.md` as the source of truth for visual decisions. - Read it once at the start of a session, then refer to it before each new component. - When tokens change (`./design.md` was updated), re-read it. - Respect the "Do's and Don'ts" section literally.