UI Design
Opinionated constraints for building better interfaces with agents.
When to Use
- Building UI components with Tailwind CSS
- Implementing animations or transitions
- Adding interactive elements with keyboard/focus behavior
- Reviewing frontend code for accessibility
- Designing layouts with proper z-index and spacing
- Working with loading states, error handling, or empty states
Stack
| Requirement | Rule |
|---|
| Tailwind CSS | MUST use defaults (spacing, radius, shadows) before custom values |
| Animation library | MUST use motion/react
(formerly framer-motion
) for JS animation |
| CSS animation | SHOULD use tw-animate-css
for entrance and micro-animations |
| Class logic | MUST use cn
utility (clsx
+ tailwind-merge
) |
Components
| Requirement | Rule |
|---|
| Interactive primitives | MUST use accessible primitives (Base UI
, React Aria
, Radix
) for keyboard/focus behavior |
| Existing components | MUST use project's existing primitives first |
| Consistency | NEVER mix primitive systems within the same interaction surface |
| New primitives | SHOULD prefer Base UI
if compatible with stack |
| Icon buttons | MUST add aria-label
to icon-only buttons |
| Custom behavior | NEVER rebuild keyboard or focus behavior by hand unless explicitly requested |
Interaction
| Requirement | Rule |
|---|
| Destructive actions | MUST use AlertDialog
for destructive or irreversible actions |
| Loading states | SHOULD use structural skeletons |
| Viewport height | NEVER use h-screen
, use h-dvh
|
| Fixed elements | MUST respect safe-area-inset
|
| Error display | MUST show errors next to where the action happens |
| Input behavior | NEVER block paste in input
or textarea
elements |
Animation
| Requirement | Rule |
|---|
| Default | NEVER add animation unless explicitly requested |
| Compositor props | MUST animate only transform
, opacity
|
| Layout props | NEVER animate width
, height
, top
, left
, margin
, padding
|
| Paint props | SHOULD avoid background
, color
except for small, local UI (text, icons) |
| Entrance easing | SHOULD use ease-out
on entrance |
| Feedback timing | NEVER exceed 200ms
for interaction feedback |
| Looping | MUST pause looping animations when off-screen |
| Accessibility | MUST respect prefers-reduced-motion
|
| Custom easing | NEVER introduce custom easing curves unless explicitly requested |
| Large surfaces | SHOULD avoid animating large images or full-screen surfaces |
Typography
| Requirement | Rule |
|---|
| Headings | MUST use text-balance
|
| Body text | MUST use text-pretty
for paragraphs |
| Data | MUST use tabular-nums
|
| Dense UI | SHOULD use truncate
or line-clamp
|
| Letter spacing | NEVER modify letter-spacing
(tracking-
) unless explicitly requested |
Layout
| Requirement | Rule |
|---|
| Z-index | MUST use a fixed scale (no arbitrary z-x
) |
| Square elements | SHOULD use size-x
instead of w-x
+ h-x
|
Performance
| Requirement | Rule |
|---|
| Blur effects | NEVER animate large blur()
or backdrop-filter
surfaces |
| Will-change | NEVER apply will-change
outside an active animation |
| useEffect | NEVER use for anything expressible as render logic |
Design
| Requirement | Rule |
|---|
| Gradients | NEVER use unless explicitly requested |
| Purple/multicolor gradients | NEVER use |
| Glow effects | NEVER use as primary affordances |
| Shadows | SHOULD use Tailwind CSS default scale unless explicitly requested |
| Empty states | MUST give one clear next action |
| Accent colors | SHOULD limit to one per view |
| Color tokens | SHOULD use existing theme or Tailwind CSS tokens before introducing new ones |
Quick Reference
Allowed Animation Properties
transform, opacity
Forbidden Animation Properties
width, height, top, left, margin, padding, blur(), backdrop-filter
Required Accessibility Patterns
// Icon button - always add aria-label
<button aria-label="Close dialog">
<XIcon />
</button>
// Respect reduced motion
@media (prefers-reduced-motion: reduce) {
* { animation: none !important; }
}
Class Utility Pattern
import { clsx } from 'clsx';
import { twMerge } from 'tailwind-merge';
export function cn(...inputs: ClassValue[]) {
return twMerge(clsx(inputs));
}
