// For above-the-fold images
```
### Border Radius (from modern SaaS)
```
None (0px): Tables, dividers, full-bleed images
Small (4px): Buttons, inputs, tags, badges
Medium (8px): Cards, modals, dropdowns
Large (12px): Feature cards, hero elements
Full (9999px): Avatars, pills, toggle tracks
```
**Principles:**
- Consistency: pick 2-3 radius values and stick to them
- Nested elements: inner radius = outer radius - padding
- Sharp corners feel technical/precise; round feels friendly/approachable
### Shadows & Elevation (from Material, Linear)
```
Level 0: none (flat, on surface)
Level 1: 0 1px 2px rgba(0,0,0,0.05) - Subtle lift (cards)
Level 2: 0 4px 6px rgba(0,0,0,0.07) - Raised (dropdowns)
Level 3: 0 10px 15px rgba(0,0,0,0.1) - Floating (modals)
Level 4: 0 20px 25px rgba(0,0,0,0.15) - High (popovers)
```
**Principles:**
- Shadows should feel like natural light (top-down, slight offset)
- Dark mode: use lighter surface colors instead of shadows
- Combine with subtle border for definition
- Interactive elements can elevate on hover
---
## Part 3: Component Patterns
### Buttons (from Stripe, Linear)
**Hierarchy:**
1. **Primary** - One per view, main action, filled with brand color
2. **Secondary** - Supporting actions, outlined or ghost style
3. **Tertiary** - Low-emphasis actions, text-only with hover state
4. **Destructive** - Delete/remove actions, red with confirmation
**States:**
- Default → Hover (+shadow or darken) → Active (scale 0.97) → Disabled (50% opacity)
- Loading: replace text with spinner, maintain width
- Min width: 80px; min height: 36px (touch-friendly: 44px)
**Best practices:**
- **Specific labels:** "Save API Key" not "Continue" or "Submit"
- Verb + noun labels: "Create project" not "Create"
- Sentence case, not ALL CAPS
- Icon left of text (or icon-only with tooltip)
- Primary button right-aligned in forms/dialogs
- **Icon buttons require `aria-label`**
**Active state feedback:**
```css
button:active {
transform: scale(0.97);
}
```
### Forms (from Airbnb, Stripe, Vercel)
**Input anatomy:**
```
┌─────────────────────────────────┐
│ Label │ ← Required (above input, not inside)
│ ┌─────────────────────────────┐ │
│ │ Placeholder... │ │ ← Format hint only, ends with ...
│ └─────────────────────────────┘ │
│ Helper text or error message │ ← Specific and actionable
└─────────────────────────────────┘
```
**Autocomplete attributes (required):**
```html
```
**Input types and modes:**
```html
```
**Disable spellcheck where inappropriate:**
```jsx
// Disable for codes, emails, usernames, URLs
```
**Anti-patterns to avoid:**
```jsx
// NEVER block paste - this is hostile UX
e.preventDefault()} /> // ❌ NEVER DO THIS
// NEVER use placeholder as label
// ❌ Placeholder disappears on focus
// NEVER validate on every keystroke
onChange={(e) => validateEmail(e.target.value)} // ❌ Too aggressive
```
**Best practices:**
- Labels above inputs (not inside—accessibility)
- Placeholder ≠ label; use for format hints only, end with `...`
- Inline validation on blur, not on every keystroke
- Error messages: specific and actionable ("Email must include @")
- **Focus first error field** after form submission fails
- Success state: checkmark icon, green border (brief)
- Required fields: mark optional ones instead of required
- Single column forms outperform multi-column
**Unsaved changes warning:**
```jsx
// Warn users before leaving with unsaved changes
useEffect(() => {
const handleBeforeUnload = (e) => {
if (hasUnsavedChanges) {
e.preventDefault();
e.returnValue = '';
}
};
window.addEventListener('beforeunload', handleBeforeUnload);
return () => window.removeEventListener('beforeunload', handleBeforeUnload);
}, [hasUnsavedChanges]);
```
### Cards (from Material, Apple)
**Anatomy:**
```
┌────────────────────────────────┐
│ [Media/Image] │ ← Optional
├────────────────────────────────┤
│ Eyebrow · Metadata │ ← Optional
│ Title │ ← Required
│ Description text that can │ ← Optional
│ wrap to multiple lines... │
├────────────────────────────────┤
│ [Actions] [More] │ ← Optional
└────────────────────────────────┘
```
**Best practices:**
- Entire card clickable for primary action
- Consistent padding (16-24px)
- Image aspect ratios: 16:9, 4:3, 1:1 (be consistent)
- Limit to 2 actions max; overflow to menu
- Hover: subtle lift (translateY -2px + shadow increase)
### Tables (from Linear, Notion)
**Best practices:**
- Left-align text, right-align numbers
- **Use `tabular-nums` for numeric columns** (consistent width digits)
- Zebra striping OR row hover, not both
- Sticky header on scroll
- Sortable columns: show current sort indicator
- Actions: row hover reveals action buttons (or kebab menu)
- Empty state: helpful message + action
- Pagination vs infinite scroll: pagination for data accuracy, infinite for browsing
- Min row height: 48px for touch; 40px for dense
- **Virtualize tables with >50 rows**
```css
.numeric-column {
font-variant-numeric: tabular-nums;
text-align: right;
}
```
### Navigation (from Apple HIG, Material)
**Patterns by scale:**
- **2-5 items**: Tab bar / horizontal tabs
- **5-10 items**: Side navigation (collapsible)
- **10+ items**: Side nav with sections/groups
**Best practices:**
- Current location always visible
- Breadcrumbs for deep hierarchy (not for flat structures)
- Mobile: bottom nav for primary actions (thumb-friendly)
- Icons + labels together; icon-only needs tooltip
- Consistent order across pages
---
## Part 4: Interaction Design
### Feedback Patterns (from Dan Saffer's Microinteractions)
**Every action needs feedback:**
1. **Immediate** - Button press visual (scale, color change)
2. **Progress** - Loading states for anything >1s
3. **Completion** - Success confirmation (toast, checkmark, animation)
4. **Failure** - Clear error with recovery path
**Loading states:**
- 0-100ms: No indicator needed
- 100-300ms: Subtle change (opacity, skeleton)
- 300ms-1s: Spinner or progress bar
- 1s+: Skeleton screens + progress indication
- 10s+: Background processing with notification
### State Handling
**Every component needs these states:**
```
Default → Base appearance
Hover → Interactive hint (cursor change, highlight)
Focus → Keyboard navigation (visible ring)
Active → Being pressed/activated
Loading → Async operation in progress
Disabled → Not available (reduce opacity, remove pointer)
Error → Invalid input or failed operation
Success → Completed successfully (brief)
Empty → No data to display (helpful message + action)
```
### Touch & Pointer Interactions
**Faster tap response:**
```css
/* Remove 300ms tap delay on touch devices */
button, a, [role="button"] {
touch-action: manipulation;
}
```
**Contain scroll in modals:**
```css
/* Prevent scroll chaining to body when modal/drawer reaches edge */
.modal, .drawer, .dropdown {
overscroll-behavior: contain;
}
```
**Touch targets:**
- Minimum 44x44px for all interactive elements (Apple HIG)
- Provide adequate spacing between targets (8px minimum)
**Hover states for pointer devices only:**
```css
/* Only apply hover effects on devices with fine pointers */
@media (hover: hover) and (pointer: fine) {
.card:hover {
transform: translateY(-2px);
box-shadow: var(--shadow-lg);
}
}
```
**Tap highlight:**
```css
/* Customize or remove tap highlight on mobile */
button {
-webkit-tap-highlight-color: transparent; /* Remove default */
/* Or use a custom color */
-webkit-tap-highlight-color: rgba(0, 0, 0, 0.1);
}
```
### Optimistic Updates (from Linear, Notion)
- Update UI immediately, sync in background
- Show subtle "Saving..." indicator
- On failure: revert UI + show error toast with retry
- Best for: toggles, reordering, text edits
- Avoid for: destructive actions, payments
### Progressive Disclosure
**Reveal complexity gradually:**
- Show essential options first
- "Advanced" or "More options" for power features
- Inline expansion over page navigation
- Tooltips for supplementary information
- Context menus for secondary actions
### Inferring Intent
**Anticipate user actions before they happen:**
```jsx
// Preload on mousedown (fires before click)
// Preload on hover for links
router.prefetch('/dashboard')}
>
Dashboard
```
**Proximity-based preloading:**
```jsx
// Start loading when cursor approaches
function useProximityPreload(ref, onApproach) {
useEffect(() => {
const element = ref.current;
const handleMouseMove = (e) => {
const rect = element.getBoundingClientRect();
const distance = Math.hypot(
e.clientX - (rect.left + rect.width / 2),
e.clientY - (rect.top + rect.height / 2)
);
if (distance < 100) onApproach();
};
document.addEventListener('mousemove', handleMouseMove);
return () => document.removeEventListener('mousemove', handleMouseMove);
}, [ref, onApproach]);
}
```
**Smart defaults:**
- Pre-fill forms with likely values
- Remember user's last selection
- Use geolocation for location fields
- Default date pickers to sensible dates (today, tomorrow)
### Interaction Metaphors
**Physical analogies users already understand:**
| Gesture | Real-world Metaphor | UI Behavior |
|---------|---------------------|-------------|
| Drag | Moving physical objects | Reorder, move items |
| Swipe | Flipping pages, pushing aside | Navigate, dismiss |
| Pinch | Zooming a camera lens | Scale content |
| Pull down | Stretching a spring | Refresh content |
| Long press | Pressing firmly to reveal | Context menu |
**Consistency requirement:**
Once you establish a gesture metaphor, use it consistently:
```
❌ Swipe right to delete in one view, swipe right to archive in another
✅ Swipe right always archives, swipe left always deletes
```
**Honor platform conventions:**
- iOS: Swipe from left edge = back navigation
- Android: Back button/gesture = return to previous screen
- Desktop: Right-click = context menu
### Ergonomic Interactions
**Expand hit areas with pseudo-elements:**
```css
/* Thin visual element with large tap target */
.icon-button {
position: relative;
width: 24px;
height: 24px;
}
.icon-button::after {
content: '';
position: absolute;
inset: -12px; /* Expands hit area to 48x48px */
}
```
**Bidirectional scroll support:**
```css
/* Support both LTR and RTL scrolling */
.horizontal-scroll {
overflow-x: auto;
scroll-behavior: smooth;
/* Use logical properties */
scroll-padding-inline: 16px;
}
```
**Thumb-friendly mobile zones:**
```
┌─────────────────────────────────┐
│ Hard to reach (top) │ ← Avoid primary actions here
├─────────────────────────────────┤
│ │
│ Comfortable middle │ ← Secondary actions OK
│ │
├─────────────────────────────────┤
│ Easy reach (bottom) │ ← Primary actions here
└─────────────────────────────────┘
```
### Contained Gestures
**Prevent gesture conflicts with parent elements:**
```css
/* Contain drag/swipe gestures within element */
.draggable-area {
touch-action: none; /* Disable browser handling */
user-select: none; /* Prevent text selection during drag */
}
/* Allow vertical scroll but capture horizontal */
.horizontal-swipe {
touch-action: pan-y; /* Allow vertical, capture horizontal */
}
```
**Pointer capture for drag operations:**
```jsx
function useDrag(onDrag, onDragEnd) {
const handlePointerDown = (e) => {
e.currentTarget.setPointerCapture(e.pointerId);
};
const handlePointerMove = (e) => {
if (e.currentTarget.hasPointerCapture(e.pointerId)) {
onDrag({ x: e.clientX, y: e.clientY });
}
};
const handlePointerUp = (e) => {
e.currentTarget.releasePointerCapture(e.pointerId);
onDragEnd();
};
return {
onPointerDown: handlePointerDown,
onPointerMove: handlePointerMove,
onPointerUp: handlePointerUp,
};
}
```
**Drag threshold detection:**
```jsx
// Distinguish click from drag with movement threshold
const DRAG_THRESHOLD = 5; // pixels
function useDragThreshold() {
const startPos = useRef(null);
const [isDragging, setIsDragging] = useState(false);
const handlePointerDown = (e) => {
startPos.current = { x: e.clientX, y: e.clientY };
};
const handlePointerMove = (e) => {
if (!startPos.current) return;
const distance = Math.hypot(
e.clientX - startPos.current.x,
e.clientY - startPos.current.y
);
if (distance > DRAG_THRESHOLD) {
setIsDragging(true);
}
};
const handlePointerUp = (e) => {
const wasDragging = isDragging;
setIsDragging(false);
startPos.current = null;
return wasDragging; // Return true if was drag, false if was click
};
return { isDragging, handlePointerDown, handlePointerMove, handlePointerUp };
}
```
**Gesture state machine:**
```
IDLE → PRESS (pointer down)
PRESS → DRAG (movement > threshold)
PRESS → CLICK (pointer up, no movement)
DRAG → DRAG_END (pointer up)
DRAG_END → IDLE (animation complete)
```
---
## Part 5: Motion & Animation
### The Frequency Principle
Animation frequency should match usage frequency:
| Usage Pattern | Animation Approach |
|---|---|
| 100+ times/day | No animation—instant response |
| Occasional use | Standard animation (150-300ms) |
| Rare/first-time | Can add delight, longer duration |
Example: A "send message" button used constantly → instant. An "export report" button used weekly → can animate.
### Easing Blueprint
**Ease-out family (most common):**
Use for entrances, user-initiated actions, and most UI transitions.
```css
:root {
/* Increasing intensity: quad → cubic → quart → quint */
--ease-out-quad: cubic-bezier(0.25, 0.46, 0.45, 0.94);
--ease-out-cubic: cubic-bezier(0.215, 0.61, 0.355, 1);
--ease-out-quart: cubic-bezier(0.165, 0.84, 0.44, 1);
--ease-out-quint: cubic-bezier(0.23, 1, 0.32, 1);
}
```
**Ease-in-out family:**
Use for on-screen movement (element moving from point A to point B).
```css
:root {
--ease-in-out-quad: cubic-bezier(0.455, 0.03, 0.515, 0.955);
--ease-in-out-cubic: cubic-bezier(0.645, 0.045, 0.355, 1);
}
```
**Easing decision flowchart:**
```
Is the element entering or exiting the screen?
→ Yes: Use ease-out (for both enter AND exit)
Is the element moving on screen (A to B)?
→ Yes: Use ease-in-out
Is it a hover state or color change?
→ Yes: Use ease (CSS default) or ease-out-quad
Is it constant/looping motion (spinner, progress)?
→ Yes: Use linear
```
### Timing Guidelines
| Element Type | Duration | Notes |
|---|---|---|
| Micro-interactions | 100-150ms | Buttons, toggles, hover states |
| Tooltips, dropdowns | 150-250ms | Small UI appearing |
| Modals, drawers | 200-300ms | Larger surfaces |
| Page transitions | 300-400ms | Full view changes |
| Staggered items | 30-50ms delay | Between each item |
**Important:** Exit animations should be 20-30% faster than entrances.
### Animation Patterns
**Entrances:**
- Fade in + slide up (8-16px)
- Scale from 0.95 to 1 + fade (never from 0)
- Stagger children by 30-50ms
**Exits:**
- Fade out (faster than entrance)
- Scale to 0.95 + fade
- Slide in direction of dismissal
**Transform origin:**
Always set `transform-origin` toward the trigger element:
```css
/* Dropdown opening from button */
.dropdown {
transform-origin: top left; /* Opens from button location */
}
/* Modal opening from center */
.modal {
transform-origin: center center;
}
```
**Hover flicker prevention:**
```css
/* ❌ Don't animate the parent on hover */
.card:hover {
transform: scale(1.02); /* Causes flicker */
}
/* ✅ Animate a child element instead */
.card:hover .card-content {
transform: scale(1.02);
}
```
**Sequential tooltips:**
After the first tooltip in a series, skip animation for subsequent ones:
```jsx
// Skip animation if another tooltip was shown recently
const skipAnimation = Date.now() - lastTooltipTime < 300;
```
### Spring Physics
**When to use springs:**
- Drag and drop interactions
- Gesture-based animations
- Interruptible motion (user can grab mid-animation)
- Physics-based feel (natural, organic)
**Spring parameters:**
```jsx
// Physical spring configuration
const spring = {
stiffness: 300, // Higher = faster, snappier
damping: 30, // Higher = less oscillation
mass: 1 // Higher = more inertia, slower
};
// Typical ranges:
// stiffness: 100-1000 (most UI: 200-400)
// damping: 10-100 (most UI: 20-40)
// mass: 0.5-2 (most UI: 1)
```
**Critical principle: Never reuse spring values**
Each interaction should have its own tuned spring. A dropdown menu spring differs from a drag-to-dismiss spring.
```jsx
// ❌ Bad - same spring for everything
const SPRING = { stiffness: 300, damping: 30 };
// ✅ Good - tuned per interaction
const DROPDOWN_SPRING = { stiffness: 400, damping: 35, mass: 0.8 };
const DRAG_SPRING = { stiffness: 250, damping: 25, mass: 1 };
const BOUNCE_SPRING = { stiffness: 180, damping: 12, mass: 1 };
```
**Damping for rubber band effects:**
```jsx
// Rubber band effect for over-scroll
function rubberBand(offset, limit, elasticity = 0.55) {
const clampedOffset = Math.max(0, offset);
const delta = clampedOffset - limit;
if (delta <= 0) return offset;
// Logarithmic decay for natural feel
return limit + (1 - Math.exp(-delta / (limit * elasticity))) * limit * elasticity;
}
```
**iOS-style projection (momentum scrolling):**
```jsx
// Project final position based on velocity
function project(velocity, position, deceleration = 0.998) {
// v(t) = v0 * deceleration^t
// When v(t) ≈ 0, t = log(0.001) / log(deceleration)
const duration = Math.log(0.001) / Math.log(deceleration);
const distance = velocity * (1 - Math.pow(deceleration, duration)) / (1 - deceleration);
return position + distance;
}
```
**Framer Motion spring shorthand:**
```jsx
// Simple configuration
const springConfig = {
type: "spring",
duration: 0.5, // Overall duration
bounce: 0.2 // 0 = no bounce, 1 = very bouncy
};
// Subtle bounce (most UI): 0.1 - 0.3
// Playful bounce: 0.3 - 0.5
// Avoid > 0.5 in most production UI
```
### Motion Choreography
**Blur overlapping layers:**
When animated elements cross paths, they create visual noise. Add subtle blur:
```css
/* Add 1-2px blur during transitions */
.transitioning-element {
filter: blur(1px);
}
/* Or use will-change to hint GPU compositing */
.animated-layer {
will-change: transform;
transform: translateZ(0); /* Force separate layer */
}
```
**Stagger animation delays:**
```jsx
// Stagger children by 30-50ms each
const container = {
hidden: { opacity: 0 },
show: {
opacity: 1,
transition: {
staggerChildren: 0.04, // 40ms between each
delayChildren: 0.1, // Wait 100ms before starting
}
}
};
const item = {
hidden: { opacity: 0, y: 8 },
show: { opacity: 1, y: 0 }
};
```
**Double exit stiffness:**
Exit animations should feel quicker. Double the spring stiffness:
```jsx
function AnimatedPanel({ isOpen }) {
return (
// Below the fold: lazy load
// Critical background images: preload
```
---
## Part 8: Content & Copy
### Writing Style
**Active voice over passive:**
```
✅ "Install the CLI"
❌ "The CLI will be installed"
✅ "Your changes were saved"
❌ "Changes have been saved by the system"
```
**Title Case for headings and buttons:**
```
✅ "Save API Key"
❌ "Save api key"
✅ "Getting Started"
❌ "Getting started"
```
**Use numerals:**
```
✅ "8 deployments"
❌ "eight deployments"
✅ "3 items selected"
❌ "three items selected"
```
### Labels & Messages
**Specific labels over generic:**
```
✅ "Save API Key"
❌ "Continue"
✅ "Create Project"
❌ "Submit"
✅ "Delete Repository"
❌ "Confirm"
```
**Error messages include fix/next step:**
```
✅ "Email must include @ symbol"
❌ "Invalid email"
✅ "Password must be at least 8 characters"
❌ "Password too short"
✅ "Could not connect. Check your internet connection and try again."
❌ "Network error"
```
### Internationalization
**Use Intl APIs for formatting:**
```jsx
// ❌ Hardcoded format
const date = `${month}/${day}/${year}`;
const price = `$${amount.toFixed(2)}`;
// ✅ Locale-aware formatting
const date = new Intl.DateTimeFormat('en-US', {
dateStyle: 'medium'
}).format(new Date());
const price = new Intl.NumberFormat('en-US', {
style: 'currency',
currency: 'USD'
}).format(amount);
// Relative time
const rtf = new Intl.RelativeTimeFormat('en', { numeric: 'auto' });
rtf.format(-1, 'day'); // "yesterday"
```
---
## Part 9: Anti-Patterns Checklist
Flag these patterns during design review:
### Accessibility Violations
- [ ] `user-scalable=no` or `maximum-scale=1` in viewport meta
- [ ] `