| name | web-ui-best-practices |
| description | Opinionated constraints for building better user interfaces. Triggers on building or reviewing web components, pages, forms, modals, animations, or any frontend UI work. Covers accessibility, focus states, touch interactions, and performance. |
Web UI Best Practices
When invoked generally, apply these opinionated constraints for building better interfaces and for any UI work in this conversation.
When invoked with a file specified (i.e. web-ui-best-practices <file>), review the file against all constraints below and output:
- violations (quote the exact line/snippet)
- why it matters (1 short sentence)
- a concrete fix (code-level suggestion)
Stack
- MUST use Tailwind CSS defaults unless custom values already exist or are explicitly requested
- 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, Radix, React-Aria)
- 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
