# 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

- Read the repository's DESIGN.md when present and use it to locate approved sources and decision precedence.
- 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.

## Fix the numbers before you draw

- Put every gap, margin, padding, and control height on an 8 pixel grid. Use the 4 and 12 pixel half steps only inside a control.
- Use one padding on every surface, 24 pixels unless the design system fixes another value. Do not pick a new inset per card.
- Use one corner radius on every surface, 24 pixels unless the design system fixes another value. Derive a nested corner as the outer radius minus the padding.
- Use at most two font families: Inter for the interface and one serif for display text. Use two weights, and a third only when it marks a level the first two cannot.
- Use about three type sizes on one view: a title, a section, and body. Let weight and color carry every other distinction.
- Start from two or three reference screens that already have the quality you want, name what to take from each, then fine-tune one axis at a time.
- Never choose the images. Place the hand-selected files and follow the written art direction for subject, crop, palette, and treatment.

## 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.