Cursor Rules for UI and UX: Design Decisions in Code

Cursor rules for UI and UX capture the design decisions that live between the design file and the production interface. Without them, an assistant given a component task has no way to know which design tokens to use, how the team handles focus management, which accessibility standard applies, or what acceptance criteria the component must meet before it is considered done. Those details exist in Figma comments, Slack threads, and past reviews. fenbs brings the approved design decisions into the AI context so the next Cursor session builds on what the team already settled.

This guide provides a working template for each area of UI and UX work and explains what each rule is designed to prevent.

What UI and UX Cursor rules cover

Design decisions fall into a few categories that each need their own rules. Token rules prevent hardcoded color values. Interaction rules prevent inconsistent focus and keyboard behavior. Accessibility rules make WCAG compliance a testable check rather than a vague aspiration. Acceptance rules tell the assistant what "done" means before it declares a component finished.

• Design tokens: color, spacing, typography, and radius must come from the token system, not from hardcoded values.
• Interaction patterns: focus management, keyboard navigation, and state transitions.
• Accessibility: which standard applies, which tools to run, and which patterns to follow.
• Acceptance criteria: what a component must do before it is considered complete.
• Design feedback integration: how approved design feedback becomes a rule rather than a comment.

Design token rules

A hardcoded color value is a small problem in isolation. Across a large codebase it becomes a maintenance problem: every color that is not a token is a place the design system has no reach. A rule that forbids hardcoded values and names the token system forces that discipline at the point where the code is written.

# Design token rules

## Colors
Never use a hardcoded hex, RGB, or HSL color value in a style.
Use design tokens from the token file (tokens.css, theme.ts, or the design system export).
Correct: color: var(--color-text-primary)
Incorrect: color: #1a1a1a

## Spacing
Use spacing tokens for margin, padding, and gap.
The spacing scale is 4px base (4, 8, 12, 16, 24, 32, 48, 64).
Do not use odd or arbitrary values (e.g. 7px, 13px) unless the design explicitly specifies them.

## Typography
Font family, size, weight, and line height come from the typography tokens.
Do not set font-family to a literal font name; use the token variable.

## Border radius
Use the radius tokens: --radius-sm, --radius-md, --radius-lg.
Do not hardcode border-radius values.

Interaction pattern rules

Interaction patterns are where the gap between a visual implementation and a usable one lives. A button that looks correct but has no keyboard focus ring, a modal that does not trap focus, or a dropdown that does not close on Escape will all pass a visual review and fail an accessibility or usability test. Rules in this area describe what the correct behavior is, not just how the component looks. Testing interaction rules is straightforward with a keyboard-only check: close all pointing devices and tab through the component. Verify you can reach every interactive element, activate it with Enter or Space, and dismiss overlays with Escape. Add keyboard testing to the acceptance criteria rule so it happens during development, not only at review. Most keyboard accessibility gaps are fastest to catch this way.

# Interaction patterns

## Focus management
Every interactive element must have a visible focus indicator.
Do not set outline: none without providing an alternative focus style.
When a modal or dialog opens, move focus to the first interactive element inside it.
When it closes, return focus to the element that triggered it.

## Keyboard navigation
Interactive components must be operable with the keyboard alone.
Custom dropdowns and menus follow the ARIA authoring practices for the relevant pattern
  (combobox, listbox, menu button).
Escape closes an open dropdown, menu, or modal.
Arrow keys navigate within a list, grid, or tab panel.

## State transitions
Loading states must have a visual indicator (spinner, skeleton, or text) and an ARIA live region.
Error states must announce the error text to screen readers using role="alert" or aria-live="assertive".
Do not use color alone to communicate state.

Accessibility rules

Accessibility rules work best when they name specific checks rather than general principles. "Make it accessible" is not actionable for an assistant. "Every image must have an alt attribute; decorative images use alt=''" is. The rule should also name the standard and the tools that verify it.

# Accessibility

## Standard
This project targets WCAG 2.1 Level AA.

## Required checks
Before a component is considered done:
- Run axe-core (or the browser extension) on the rendered output. No violations allowed.
- Test keyboard navigation: tab, shift-tab, enter, space, escape, and arrow keys as applicable.
- Verify contrast ratio meets 4.5:1 for text and 3:1 for UI components (use the token palette).

## Markup rules
- Every form input must have an associated <label> or an aria-label.
- Every interactive element that is not a native button or link must have role and aria-* attributes.
- Images: alt text describes the content. Decorative images: alt="".
- Headings use the correct hierarchy. Do not skip levels for visual sizing; use CSS classes.

## Screen reader smoke test
Verify that the component's name, role, and state are announced correctly.
Check that error messages are announced immediately, not only visible.

Acceptance criteria rules

An acceptance criterion in a Cursor rule tells the assistant what finished means for a UI component. Without it, the assistant declares a component done when it renders correctly. With it, the assistant also checks keyboard behavior, screen reader output, responsive behavior, and the error state.

The most useful acceptance criteria are the ones that catch the missing state. A component that has a default state and a hover state but no focus state will fail an accessibility review. A component that renders correctly with sample data but does not handle an empty array will produce a visual regression in production. Build the missing-state cases into the acceptance rule so the assistant knows to implement and verify them before calling the work done. A useful addition is a brief description of how to verify each criterion manually. For a focus-ring check, that means removing the mouse pointer and tabbing through every interactive element. For a responsive check, it means resizing to each named breakpoint before marking the component ready for review. Manual verification steps in the rule prevent the assistant from declaring a component done based on a visual pass alone.

# UI component acceptance criteria

A new component is not done until:
1. It renders correctly at the three breakpoints: 375px (mobile), 768px (tablet), 1280px (desktop).
2. It passes axe-core with no violations.
3. All interactive states are implemented: default, hover, focus, active, disabled, loading if applicable.
4. Error state renders and announces the error message to screen readers.
5. The component works with keyboard navigation only.
6. Design tokens are used for all colors, spacing, and typography; no hardcoded values.
7. A Storybook story exists (or a test using the project's component testing tool).

How to do this with fenbs

1. Create a free account and add the project for your frontend or design system.
2. Record the approved design decisions in fenbs: which token file to use, which accessibility standard applies, and the component acceptance criteria your team agreed on.
3. Connect Cursor to fenbs over MCP from Integrations. Ask it to read the project context before working on a new component.
4. After each design review, add any approved feedback that affects all future components as a Decision in fenbs. Name the person who approved it and the date. Update the Cursor rule file to match.
5. Use fenbs tasks to track components that need to be updated after a design system change. The task record links the component, the change, and the decision that required it.