# DESIGN.md with Cursor

> Point Cursor at DESIGN.md with a project rule in .cursor/rules, AGENTS.md or an @ mention. Includes a sample .mdc rule and the four rule types.

Canonical page: https://sitepeel.dev/guides/design-md-cursor/

Save DESIGN.md in your project, then add a rule in .cursor/rules that tells Cursor’s Agent to follow it for UI work. AGENTS.md and @ mentions also work.

Published: 2026-10-24

Tool used in this guide: [Design MD generator](https://sitepeel.dev/design-md-generator/index.md)

## How to use it

1. **Add DESIGN.md to the project** Generate it from a website with Sitepeel, review it and save it in the project root.
2. **Create a project rule** Type /create-rule in Agent chat, or open Customize, then Rules, then Add Rule.
3. **Set when it applies** Use globs for your UI files, or alwaysApply: true for a small, UI-heavy project.
4. **Mention it for new pages** For a page with no files yet, add @DESIGN.md to your prompt so Agent reads it first.
5. **Check the result** Ask which tokens Agent used, then compare the page with DESIGN.md at phone and desktop widths.

## Sample Cursor rule for DESIGN.md

Save this as .cursor/rules/design.mdc. With globs set and alwaysApply false, Cursor attaches the rule when a matching file is in context.

Example: .cursor/rules/design.mdc

```
---
globs: src/**/*.tsx, src/**/*.css
alwaysApply: false
---

- Read @DESIGN.md before changing any UI.
- Use its color, typography, spacing and radius tokens. No new hex values.
- Reuse existing components and follow its Do's and Don'ts.
- If DESIGN.md has no rule for a case, say so instead of inventing one.
```

## Choose how the rule is applied

Cursor rule types and their front matter

| Type | Front matter | When it loads |
| --- | --- | --- |
| Always Apply | alwaysApply: true | Every chat |
| Apply to Specific Files | globs, alwaysApply: false | When a matching file is in context |
| Apply Intelligently | description, alwaysApply: false | When Agent judges the description relevant |
| Apply Manually | alwaysApply: false only | When you @-mention the rule in chat |

## Use AGENTS.md instead of a rule

Cursor reads AGENTS.md, a plain Markdown file with no front matter, in the project root and in subfolders. Nested files combine with their parents, and the more specific file wins. If your repository already has AGENTS.md for Codex or Copilot, add a short UI section there.

- [Sample AGENTS.md section for DESIGN.md](https://sitepeel.dev/guides/design-md-codex/index.md)

## Check what Agent built

- Ask Agent to list the DESIGN.md tokens and components it used
- Search the diff for new hex values and one-off pixel sizes
- Open the page at phone and desktop widths and compare it with DESIGN.md
- Rule not applied? Check the .mdc extension and that your globs match the files
- Keep each rule under 500 lines, as Cursor’s docs advise

- [Agent still ignores the design? Check these five things](https://sitepeel.dev/guides/ai-ignoring-design-md/index.md)

## Questions and answers

### Does Cursor read AGENTS.md?

Yes. Cursor supports AGENTS.md in the project root and in subfolders. Nested files combine with parent folders, and more specific instructions take precedence. It is plain Markdown with no front matter.

### Does Cursor read DESIGN.md automatically?

No. Point to it from a project rule or AGENTS.md, or type @DESIGN.md in chat. A mention inside a rule tells Agent where to look; Agent reads the file when it needs it.

### Why isn’t my Cursor rule applied?

Check that the file ends in .mdc and sits in .cursor/rules. For Apply Intelligently, add a description; for Apply to Specific Files, make sure the globs match the files in context.

### Do Cursor rules affect Tab completions?

No. Rules guide Agent in chat. Cursor’s docs say they don’t affect Cursor Tab or other AI features.

## Further reading

- [Cursor docs: Rules](https://cursor.com/docs/rules)
- [Cursor help: @ mentions and context](https://cursor.com/help/customization/context)

## Related pages

- [What is DESIGN.md](https://sitepeel.dev/guides/what-is-design-md/index.md): DESIGN.md is a Markdown design-system file for AI coding agents. See its format, a small example, the official linter and how to make one from any site.
- [DESIGN.md with Claude Code](https://sitepeel.dev/guides/design-md-claude-code/index.md): Import DESIGN.md into CLAUDE.md with @DESIGN.md so Claude Code follows your colors, type and spacing. Includes a sample CLAUDE.md and checks.
- [DESIGN.md with Codex](https://sitepeel.dev/guides/design-md-codex/index.md): Make OpenAI Codex follow DESIGN.md with a few lines in AGENTS.md. See where Codex looks for instructions, its size limit and how to check what loaded.
- [Use Design MD with AI](https://sitepeel.dev/guides/use-design-md-with-ai/index.md): Hand DESIGN.md to Cursor, Claude Code or another AI coding assistant: where to save it, two prompts to copy and how to review what it builds.
- [When AI ignores DESIGN.md](https://sitepeel.dev/guides/ai-ignoring-design-md/index.md): Your agent has DESIGN.md but the UI is still wrong? Check that it loads, remove conflicting rules, name real components and verify the result.