Cursor .cursor/rules/*.mdc

DESIGN.md + Cursor

Configuration reference: DESIGN.md include

Prerequisites

  • Cursor installed (version with rules support)
  • A project with an initialized Git repository
  • A DESIGN.md file — grab one from the library or generate with the design-md skill

Setup

1. Place your DESIGN.md

Drop the file at the project root:

my-project/
├── DESIGN.md
├── .cursor/
│   └── rules/
│       └── design.mdc
├── src/
└── ...

2. Create the Cursor rule

Create the .cursor/rules/ directory and add a design.mdc file:

# .cursor/rules/design.mdc

---
description: Design system visual rules
globs: ["**/*.tsx", "**/*.jsx", "**/*.vue", "**/*.svelte", "**/*.astro", "**/*.css"]
---

Leia o arquivo DESIGN.md na raiz do projeto antes de gerar qualquer componente visual.

Regras:
- Use APENAS as cores definidas na seção Colors do DESIGN.md
- Siga a escala tipográfica da seção Typography
- Respeite o espaçamento da seção Spacing
- Aplique os padrões da seção Components para estados (hover, disabled, focus)
- Nunca viole as restrições da seção Do's and Don'ts

The globs field ensures the rule only applies to UI files. .mdc files are Cursor’s rule format.

3. Verify the setup

Open a component file and ask Cursor:

Create a login form following the project's design system

Cursor should read DESIGN.md through the rule and apply the colors, fonts, and spacing you defined.

4. Additional rules (optional)

For larger projects, create separate rules by context:

# .cursor/rules/components.mdc

---
description: Component patterns
globs: ["**/components/**"]
---

Ao criar componentes, siga estritamente os padrões da seção Components do DESIGN.md.
Cada componente deve ter estados: default, hover, focus, disabled.

Troubleshooting

  • Cursor doesn’t read the rule — check that the file has a .mdc extension (not .md) and lives inside .cursor/rules/. Cursor only loads rules from that directory.
  • Rule applied to wrong files — adjust the globs field in the .mdc frontmatter. Use specific patterns to limit scope.
  • Wrong colors or fonts — your DESIGN.md might have ambiguous values. Use semantic names + hex + usage rule: brand-primary (#1A73E8): CTAs only.
  • Inconsistency between components — add a Components section to DESIGN.md with explicit states. Without defined states, Cursor invents different patterns on each generation.

Useful combinations

  • Multiple .mdc rules — split rules by responsibility: design.mdc for visual, code-style.mdc for code conventions, testing.mdc for test patterns. Cursor loads all of them automatically.
  • DESIGN.md + .cursorrules — the .cursorrules file at the root is the global equivalent. Use it for general rules and .cursor/rules/ for file-type-specific rules.
  • Rules with framework context — add framework-specific instructions in your .mdc: “Use Tailwind classes matching the DESIGN.md” or “Apply CSS Modules with design system variables”.

Next steps

Useful links