Strict And Clean UI Design Rules

# Strict And Clean UI Design Rules Opinionated constraints for building better interfaces with agents. ## Stack - **MUST** use Tailwind CSS defaults (spacing, radius, shadows) before custom values - **MUST** use motion/react (formerly framer-motion) when JavaScript animation is required - **SHOULD** use tw-animate-css for entrance and micro-animations in Tailwind CSS - **MUST** use cn utility (clsx + tailwind-merge) for class logic ## Components - **MUST** use accessible component primitives for anything with keyboard or focus behavior (Base UI, React Aria, Radix) - **MUST** use the project’s existing component primitives first - **NEVER** mix primitive systems within the same interaction surface - **SHOULD** prefer Base UI for new primitives if compatible with the stack - **MUST** add an aria-label to icon-only buttons - **NEVER** rebuild keyboard or focus behavior by hand unless explicitly requested ## Interaction - **MUST** use an AlertDialog for destructive or irreversible actions - **SHOULD** use structural skeletons for loading states - **NEVER** use h-screen, use h-dvh - **MUST** respect safe-area-inset for fixed elements - **MUST** show errors next to where the action happens - **NEVER** block paste in input or textarea elements ## Animation - **NEVER** add animation unless it is explicitly requested - **MUST** animate only compositor props (transform, opacity) - **NEVER** animate layout properties (width, height, top, left, margin, padding) - **SHOULD** avoid animating paint properties (background, color) except for small, local UI (text, icons) - **SHOULD** use ease-out on entrance - **NEVER** exceed 200ms for interaction feedback - **MUST** pause looping animations when off-screen - **MUST** respect prefers-reduced-motion - **NEVER** introduce custom easing curves unless explicitly requested - **SHOULD** avoid animating large images or full-screen surfaces ## Typography - **MUST** use text-balance for headings and text-pretty for body/paragraphs - **MUST** use tabular-nums for data - **SHOULD** use truncate or line-clamp for dense UI - **NEVER** modify letter-spacing (tracking-) unless explicitly requested ## Layout - **MUST** use a fixed z-index scale (no arbitrary z-x) - **SHOULD** use size-x for square elements instead of w-x + h-x ## Performance - **NEVER** animate large blur() or backdrop-filter surfaces - **NEVER** apply will-change outside an active animation - **NEVER** use useEffect for anything that can be expressed as render logic ## Design - **NEVER** use gradients unless explicitly requested - **NEVER** use purple or multicolor gradients - **NEVER** use glow effects as primary affordances - **SHOULD** use Tailwind CSS default shadow scale unless explicitly requested - **MUST** give empty states one clear next action - **SHOULD** limit accent color usage to one per view - **SHOULD** use existing theme or Tailwind CSS color tokens before introducing new ones