Cursor rules are instructions that Cursor's Agent adds to its context before it writes code. For UI work, store them in .cursor/rules/ as .mdc files: one always-on rule that points Agent at your design specification, plus small rules scoped by file pattern to components, styles and motion. Keep each rule short, concrete and checkable.
This guide is the frontend setup: which rule type fits which UI decision, five rule files you can adapt, how they connect to a written UI specification such as the HorizonX Vibe Coding UI Specification, and a checklist for when a rule is ignored. Cursor behavior described here comes from the Cursor Rules documentation, checked on 2026-10-09. Cursor ships changes often, so re-check the docs if a detail differs in your version.
What are Cursor rules?
The Cursor Rules docs describe four kinds of rules. When a rule applies, its contents are included "at the start of the model context", so Agent reads it before your prompt.
| Kind | Where it lives | Use in UI work |
|---|---|---|
| Project Rules | .cursor/rules/*.mdc, committed to git |
Design system constraints for this codebase |
| User Rules | Customize > Rules, on your machine | Personal preferences such as reply style, not design decisions |
| Team Rules | Cursor dashboard (Team and Enterprise plans) | Organization-wide standards, optionally enforced |
| AGENTS.md | Project root and subdirectories, plain Markdown | Simple instructions without metadata |
Two limits matter for designers and frontend developers. Rules do not affect Cursor Tab or other AI features, and User Rules are not applied to Inline Edit (Cmd/Ctrl+K). They steer Agent, the chat that plans and edits files. When rules conflict, Cursor applies Team Rules first, then Project Rules, then User Rules, and earlier sources win.
What is an .mdc file in Cursor?
A Project Rule is a Markdown file with YAML frontmatter, saved with the .mdc extension. The docs are explicit: a plain .md file inside .cursor/rules is ignored, because it has no frontmatter. If you prefer plain Markdown, use AGENTS.md instead. You can organize .mdc files in subfolders.
Three frontmatter fields decide when a rule loads:
| Rule type in the UI | Frontmatter | When Agent sees it |
|---|---|---|
| Always Apply | alwaysApply: true |
Every chat. Globs and description are ignored |
| Apply to Specific Files | globs set, alwaysApply: false |
When a matching file is in context |
| Apply Intelligently | description set, no globs |
When Agent judges the description relevant |
| Apply Manually | Neither | Only when you @-mention the rule |
Globs are comma-separated. The docs list examples such as src/**/*.tsx, docs/**/*.md, docs/**/*.mdx and tailwind.config.*.
Which rule type fits which UI decision
This is the part most rule collections skip. A design system has decisions of very different scope, and loading all of them into every chat wastes context and dilutes the ones that matter. Our mapping:
| UI concern | Rule type | Reason |
|---|---|---|
| "Follow the spec, flag conflicts, no new tokens" | Always Apply | Two or three lines that every UI change needs |
| Component conventions: states, element choice, props | Apply to Specific Files (src/components/**/*.tsx) |
Only relevant while editing components |
| Tokens and styling: color, spacing, radius, breakpoints | Apply to Specific Files (style files and config) | Only relevant where styles are written |
| Motion and accessibility | Apply Intelligently | Crosses file types; the trigger is the task, not the path |
| Auditing a page against the spec | Apply Manually | A procedure you start on purpose |
A rule set for UI work
The layout below assumes a React project with a ui-spec.yaml at the root. Rename paths to match your stack.
.cursor/rules/
ui/
ui-spec.mdc
components.mdc
styling.mdc
motion-a11y.mdc
ui-audit.mdc
ui-spec.yaml
1. Always on: point Agent at the spec
---
alwaysApply: true
---
- Read `@ui-spec.yaml` before changing interface code. Treat its tokens,
component states, responsive rules, accessibility requirements and
acceptance criteria as implementation constraints.
- If a request conflicts with the spec, name the conflict before writing code.
- Never introduce a color, radius, shadow or duration that is not a token.
If one is missing, propose the new token instead of hardcoding a value.
The first two lines are the instruction the HorizonX specification page recommends. One detail from the Cursor docs changes how you write this rule: an @file mention is not inlined. Agent reads the referenced file with its tools when it needs it. Anything that must hold on every edit belongs in the rule body itself, which is why the "no new tokens" line is written out rather than left to the spec.
2. Components, scoped by glob
---
globs: src/components/**/*.tsx
alwaysApply: false
---
- Interactive components implement every state in the spec: default, hover,
focus-visible, active, disabled and loading.
- Use native elements first: <button> for actions, <a href> for navigation.
- A card has one primary link. Other links inside it must stay reachable.
- Follow `@src/components/Button.tsx` for prop names and state handling.
The state list matches the button states in the HorizonX spec's YAML. Pointing at one canonical component is the docs' advice: reference files instead of copying code, so the rule does not go stale.
3. Styling and tokens
---
globs: src/**/*.css, src/**/*.tsx, tailwind.config.*
alwaysApply: false
---
- Color, spacing, radius and shadow values come from the tokens in
`src/styles/tokens.css`. No raw hex or pixel values for these in components.
- Spacing uses the 4px scale. Radius is 6, 10, 16 or 999 (pill).
- Build mobile first and check 360, 768, 1280 and 1440 px widths.
- Do not restyle a component to fix one page. Fix the component or add a variant.
The numbers are the defaults in the spec's YAML (4px spacing base, four radius steps, four test viewports). Replace them with yours. If you already run a style linter, let it enforce what it can, for example Stylelint's color-no-hex, and keep the rule for intent the linter cannot read. Cursor's own guidance says the same: do not copy a whole style guide into a rule.
4. Motion and accessibility, applied by description
---
description: Animation, transitions, focus styles, contrast and accessibility in UI changes
alwaysApply: false
---
- Animate transform and opacity only. Durations come from the motion
tokens: 120, 200 or 320 ms.
- Put non-essential motion inside @media (prefers-reduced-motion: no-preference).
State feedback (focus, pressed, errors) must stay visible without motion.
- Every focusable element has a visible :focus-visible style with at least
3:1 contrast against what surrounds it.
- Body text contrast is at least 4.5:1. Do not signal state with color alone.
- Nothing flashes more than three times in one second.
The description is the trigger, so write it as a list of the tasks it covers. A vague description such as "UI best practices" gives Agent nothing to match against. The thresholds come from WCAG 2.2: contrast minimum, non-text contrast and three flashes. The reduced-motion query is documented on MDN.
5. A manual audit rule
---
alwaysApply: false
---
When asked to audit a page or component against the UI spec:
1. List each component used and the states it implements. Flag missing states.
2. List any color, spacing, radius, shadow or duration that is not a token.
3. Check the layout at 360, 768, 1280 and 1440 px wide.
4. Report findings as a list. Do not edit code until asked.
With no description and no globs, it loads only when you type @ui-audit in chat. That keeps a long procedure out of everyday edits.
Rules, AGENTS.md or skills?
AGENTS.md is plain Markdown in the project root or any subdirectory. Cursor combines nested files with their parents, and the more specific file wins. It is the simpler option, and other coding agents read it too, which is why the HorizonX spec's quick start suggests linking ui-spec.yaml from AGENTS.md or CLAUDE.md. A practical split: AGENTS.md carries the one-line pointer to the spec for every tool, and .mdc rules add Cursor-specific scoping.
Skills follow the open Agent Skills standard. According to the Cursor Skills docs, a skill is a folder with a SKILL.md file (frontmatter name and description) in .cursor/skills/ or .agents/skills/ for a project, or ~/.cursor/skills/ for your machine. Agent loads a skill when it judges it relevant, or you call it by typing / in chat. Use skills for procedures with steps and supporting files, such as "build a component from the spec". Use rules for constraints that must hold on every edit. The audit rule above is a reasonable candidate for a skill, and Cursor ships a /migrate-to-skills command for that conversion.
Migrating from .cursorrules
Older Cursor projects kept every instruction in one .cursorrules file at the repository root. The current Rules page (checked 2026-10-09) no longer documents that file; it documents .cursor/rules and AGENTS.md. If you still have one, split it by scope with the table above: lines every edit needs go to an Always Apply rule, file-specific conventions go to glob rules, and general prose can become AGENTS.md.
Checklist: why is my Cursor rule not applied?
- The file ends in
.mdcand sits under.cursor/rules/. A.mdfile there is ignored. - An Apply Intelligently rule has a
description. An Apply to Specific Files rule has a glob that matches a file actually in context. - You are using Agent. Rules do not reach Tab, and User Rules do not reach Inline Edit.
- The instruction that must always hold is in the rule body, not only in a referenced file.
- A Team Rule is not overriding it. Team guidance takes precedence.
- The rule is short. Cursor recommends staying under 500 lines and splitting large rules.
- Open Customize > Rules to see every rule and its status.
What to keep out of UI rules
- Taste words. "Modern", "clean" and "premium" give Agent nothing to check. Write values and states. Why AI-generated UI looks generic explains the gap these words leave.
- Token tables copied by hand. Keep tokens in one source and reference it. The design tokens guide covers how to structure that source.
- Rare edge cases. Cursor's advice is to add a rule when Agent repeats the same mistake, not in advance.
FAQ
What is an md file for Cursor?
Cursor reads two Markdown formats. .mdc files in .cursor/rules/ are Project Rules with frontmatter that controls when they load. AGENTS.md is plain Markdown in the project root or subfolders and always applies to work in its directory. A plain .md file inside .cursor/rules/ is ignored.
How do I add skills to my Cursor agent?
Create a folder in .cursor/skills/ (or .agents/skills/) with a SKILL.md file whose frontmatter has a name matching the folder and a description. Agent discovers it at startup. You can also type /create-skill in Agent chat and describe what the skill should do.
Where can I find Cursor rules examples?
Community repositories on GitHub collect rule files. Treat them as starting points: check that they use .mdc frontmatter rather than the old .cursorrules format, and cut them down to your project's decisions. The Cursor docs note that rules are not imported from a repository on their own; to share them that way you package them as a plugin.
Start from a spec, then write the rules
Rules are only as precise as the decisions behind them. If you do not have written tokens, component states and acceptance criteria yet, start with the HorizonX Vibe Coding UI Specification: copy the YAML, fill in the required values, and point your always-on rule at it. Then review what Agent produces with the vibe-coded UI production readiness checklist before it ships.