---
paths:
  - "**/*.{tsx,jsx,vue,svelte,html,css,scss}"
---

# Better Design UI and UX guardrails

Apply these rules whenever you create, change, review, or debug a user interface. Project-specific instructions and an established design system take precedence when they are more specific.

## Start from the system

- Inspect the project for its design tokens, component library, type scale, spacing scale, radii, and shadows before styling.
- Reuse an existing component when it already serves the interaction. Do not recreate a design-system component locally.
- Use semantic tokens and approved variants. Do not invent raw colors, arbitrary spacing, one-off radii, or one-off shadows.
- If the project has no visual system, establish one before polishing individual screens.

## Make hierarchy and spacing explain the screen

- Give each screen one primary purpose and one visually dominant action. Keep secondary actions quieter.
- Use values from the spacing scale. Keep spacing tighter within a group and noticeably larger between groups.
- Keep body text between roughly 45 and 75 characters per line and use balanced wrapping for headings.
- Make distinct type roles visibly distinct. Aim for about a 25 percent size jump between adjacent roles.

## Use durable interaction patterns

- Use links for navigation, buttons for actions, real forms for submission, and native elements before ARIA workarounds.
- Keep every flow keyboard-operable with a visible focus indicator and logical focus order.
- Use at least 44 by 44 pixel hit areas on touch surfaces and at least 24 by 24 pixels for pointer input.
- Gate hover-only styling behind hover and fine-pointer media queries. Never hide a required action behind hover.
- Give every control a clear accessible name and every call to action a defined outcome.

## Design every reachable state

- Implement empty, loading, error, and success states for every component that loads or changes data.
- Keep loading feedback next to the action that caused it and preserve useful content while background work runs.
- Make errors answer what happened, why when useful, and what the user can do next.
- Do not turn a failed request into a false empty state, expose internal errors, or discard user input silently.
- During form submission, keep the original action label visible, disable repeat submission, and surface field errors beside their fields.

## Build accessibility and responsiveness in

- Meet WCAG AA contrast floors: 4.5 to 1 for normal text and 3 to 1 for large text and non-text interface elements.
- Never use color as the only signal. Pair it with text, shape, position, or an icon.
- Build mobile-first and reflow instead of shrinking. The page must work at 320 pixels without page-level horizontal scrolling.
- Do not disable browser zoom. Verify the layout with larger text and at 200 percent zoom.
- Respect reduced-motion preferences while preserving the same content, state, and task completion path.

## Review evidence before calling the UI complete

- Check the rendered interface at a narrow width and a representative desktop width.
- Complete the primary flow with keyboard only and inspect every focus indicator.
- Test empty, loading, error, success, long-content, and reduced-motion states that the change can reach.
- Run the project's type, lint, test, and build checks that cover the changed surface.
- When Better Design MCP tools are available, load the relevant UI and UX principles before implementation, then run get-review-rules and check-comprehension before presenting the result.

## What these instructions do not guarantee

These instructions guide agent behavior. They do not mechanically enforce design-system conformance, accessibility, performance, or test coverage. Use project lint rules, automated tests, browser checks, and human review for requirements that must be guaranteed.