Ux Design

Cognitive Load Principles

{"intrinsic":"simplificar fluxo","extraneous":"eliminar ruído visual","germane":"patterns consistentes"}

Modern Interaction Patterns

Full details: modern-patterns.md

Optimistic UI (MUST USE)

// User clicks → UI updates instantly → Request fires → Rollback if error
const handleLike = async () => {
  setLiked(true) // Optimistic
  try { await api.like(id) }
  catch { setLiked(false); toast.error("Failed") } // Rollback
}

Command Palette (⌘K)

{"when":"10+ actions available","must":"fuzzy search, recent items, keyboard nav","lib":"cmdk via shadcn"}

Inline Editing

{"pattern":"click → input appears → blur/enter saves","feedback":"subtle border, auto-save indicator","when":"frequent single-field edits"}

Multi-select + Bulk Actions

{"pattern":"checkbox col → selection count → sticky action bar bottom","keyboard":"shift+click range, ctrl+click toggle"}

Infinite vs Pagination

SaaS UX Pattern Library

Dashboard

{"layout":"KPIs→Charts→Activity","kpis":{"grid":"grid-cols-2 md:grid-cols-4","card":"icon+value+label+trend","max":4},"charts":{"line":"trends","bar":"comparisons","h":"h-[200px] md:h-[300px]"},"activity":"avatar+action+timestamp","mobile":{"kpis":"2col,swipe>4","charts":"full-w,h-scroll"}}

Settings

{"layout":{"desktop":"sidebar→forms","mobile":"accordion|tabs"},"sections":["General","Profile","Notifications","Security","Billing","Team","API"],"forms":{"label":"above","save":"sticky-bottom-mobile"},"feedback":{"save":"toast 3s","unsaved":"warning dialog"},"danger":"red zone bottom+confirm"}

Billing

{"pricing":{"tiers":3,"highlight":"Popular badge+border-primary","toggle":"monthly/annual"},"cards":"name→price→features→CTA","usage":{"display":"Progress current/limit","warn":"yellow@80%,red@95%"},"invoices":{"cols":"date|desc|amount|status|actions","mobile":"cards"},"checkout":"plan→payment→confirm→success"}

Onboarding

{"flow":["Welcome","Profile","FirstAction","Success"],"maxSteps":5,"progress":"stepper|checklist","empty":"illustration+headline+desc+CTA","tooltips":{"max":3,"dismiss":"click|X"},"celebration":"confetti/animation on completion"}

DataTables

{"layout":"filters→table→pagination","header":{"search":"debounce 300ms","filters":"dropdown+chips","bulk":"on selection"},"table":"checkbox|main|secondary|status|actions","mobile":"cards|h-scroll+sticky-col1","states":{"loading":"skeleton 3-5 rows","empty":"illust+CTA","error":"msg+retry"}}

Auth

{"login":"email+pwd,social,forgot,signup link","signup":"name+email+pwd,terms,social","layout":{"desktop":"split form|illustration","mobile":"centered,logo top"},"flows":{"magic":"email→link→inbox→logged","forgot":"email→reset→newpwd→success","2fa":"6digits+resend"}}

Workspace

{"members":"avatar+name+email+role+actions","roles":["Owner","Admin","Member","Viewer"],"invite":"email+role+send,pending list","switcher":"header dropdown,current highlighted","settings":["General","Members","Billing","DangerZone"]}

Navigation

{"desktop":{"sidebar":"logo→nav→spacer→user,collapsible 240px→60px","header":"breadcrumb|search|notif|user,h-14 md:h-16,sticky"},"mobile":{"bottomNav":"5 max,icon+label,h-16","drawer":"hamburger→full nav"},"states":{"active":"bg-muted+text-primary+font-medium"}}

Forms

{"layout":"max-w-2xl,space-y-6 sections,space-y-4 fields","fields":"label above+required*,placeholder=example,helper=muted,error=destructive","validation":"blur first,change after error,inline errors","actions":"bottom right,primary+secondary outline","mobile":"sticky bottom+safe-area","autosave":"draft indicator for long forms"}

Modal

{"sizes":{"sm":"max-w-sm","md":"max-w-md","lg":"max-w-lg","full":"max-w-4xl"},"structure":"header(title+X)→content(scroll)→footer(actions right)","mobile":"drawer bottom (Vaul)","behavior":"X|Esc|outside close,focus trap"}

Feedback

{"toast":{"position":"bottom-right,mobile:bottom-center","success":"green,auto 3s","error":"red,manual+retry","warning":"yellow,manual"},"loading":{"content":"Skeleton","actions":"Spinner+disable","progress":"uploads"},"confirm":{"destructive":"AlertDialog red","standard":"Dialog"}}

Context Detection

Auto-detect SaaS context from keywords:

Multiple contexts: "Team Settings" → Settings + Workspace

Micro-interactions & Feedback

Timing Guidelines

Button State Flow

idle → hover(scale-[1.02]) → active(scale-[0.98]) → loading(spinner+disabled) → success(check)/error(shake) → idle

Progress Indicators

Success Celebrations

{"subtle":"checkmark animation + green pulse","milestone":"confetti for achievements, first actions","rule":"match importance of action"}

Visual Design (Modern)

Full details: modern-patterns.md

Bento Grids

{"when":"feature showcases, varied dashboards","pattern":"asymmetric grid-cols, varied item sizes","rule":"max 4 different sizes"}

Glassmorphism (Correct Usage)

<div className="bg-white/10 backdrop-blur-md border border-white/20 shadow-lg shadow-black/5">
// Use for: overlays, highlighted cards, hero elements
// Avoid: small text over glass, overuse

Dark Mode First

{"principle":"design dark first, derive light","benefits":"vibrant colors, less eye strain","must":"AA contrast ratio in dark mode"}

Shadows (SaaS-Grade)

// WRONG: Pure black shadows
shadow-lg // can look dirty

// CORRECT: Tinted subtle shadows
className="shadow-lg shadow-primary/5"
// or custom with color tint

The 60-30-10 Rule

{"60%":"neutral (background)","30%":"secondary (cards/surfaces)","10%":"accent (CTAs/highlights)"}

Typography

Font Pairing

{"display":["Clash Display","Cabinet Grotesk","Satoshi","Plus Jakarta Sans"],"body":["DM Sans","Inter (if must)","Source Sans Pro"],"mono":["JetBrains Mono","Fira Code"]}

Scale (Mobile-First)

// Headings
<h1 className="text-2xl md:text-3xl lg:text-4xl font-display font-bold">
<h2 className="text-xl md:text-2xl font-display font-semibold">

// Body
<p className="text-sm md:text-base text-muted-foreground">

// Small
<span className="text-xs text-muted-foreground">

Mobile-First (MANDATORY)

Base Architecture

// CORRECT: Mobile-first (320px base)
<div className="p-4 md:p-6 lg:p-8">
<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3">

// WRONG: Desktop-first
<div className="p-8 sm:p-4">  // NEVER

Touch Requirements

{"minTarget":"44x44px","spacing":"8px between touch elements","feedback":"active:scale-[0.98] or bg change"}

Input Scaling (iOS Zoom Prevention)

// ALWAYS 16px+ for inputs (prevents iOS zoom)
<Input className="text-base" /> // 16px minimum
// NEVER text-sm on mobile inputs

Mobile Patterns

Safe Area

<div className="fixed bottom-0 inset-x-0 p-4 pb-safe">
// CSS: padding-bottom: max(1rem, env(safe-area-inset-bottom));

UX Writing Quick Reference

Full details: ux-writing.md

Microcopy Rules

• Concise: "Save" not "Click here to save"
• Active: "Email sent" not "Your email has been sent"
• Human: "Something went wrong" not "Error 500"

Error Messages

{"structure":"What happened + Why + How to fix","good":"Email already registered. Try logging in instead.","bad":"Error: duplicate key violation"}

Empty States

{"structure":"Title + Value description + CTA","example":"No projects yet → Create your first project to start organizing work → Create Project"}

Loading States

• Avoid generic "Loading..."
• Use context: "Fetching your dashboard...", "Almost there..."
• Show progress: "Uploading 3 of 5 files..."

States (MANDATORY)

Every component/page must handle ALL states:

// Loading
if (isLoading) return <Skeleton className="h-[200px]" />

// Error
if (error) return (
  <ErrorState
    message="Failed to load data"
    action={<Button onClick={refetch}>Try again</Button>}
  />
)

// Empty
if (!data?.length) return (
  <EmptyState
    icon={<FileIcon />}
    title="No items yet"
    description="Create your first item to get started"
    action={<Button>Create Item</Button>}
  />
)

// Success
return <DataDisplay data={data} />

Performance UX

Perceived Performance

1. Shell first: Layout skeleton instant
2. Critical content: < 1s
3. Secondary: Lazy load
4. Images: Blur placeholder → full

Skeleton Design Rules

• Must mirror final layout exactly
• Subtle pulse/gradient animation
• No "jumping" when content arrives
• 3-5 skeleton rows for lists

Preloading

// Prefetch on hover
<Link prefetch onMouseEnter={() => prefetch(url)}>

// Preload images
<Image placeholder="blur" blurDataURL={tiny} />

Anti-Patterns (BLOCKED)

Accessibility (MANDATORY)

Minimum Requirements

• Contrast: WCAG AA (4.5:1 text, 3:1 UI)
• Focus: Visible focus rings, logical tab order
• Labels: All inputs labeled, alt text on images
• Motion: prefers-reduced-motion support
• Keyboard: All actions keyboard accessible

Focus Management

// Visible focus
className="focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2"

// Trap focus in modals (shadcn does this)
// Restore focus on close

Reduced Motion

// Respect user preference
className="motion-safe:animate-fadeIn"

// Or in CSS
@media (prefers-reduced-motion: reduce) {
  * { animation-duration: 0.01ms !important; }
}

Component Intelligence Matrix

Docs Lookup

{"shadcn":".fnd/skills/ux-design/shadcn-docs.md"} {"tailwind":".fnd/skills/ux-design/tailwind-v3-docs.md"} {"motion":".fnd/skills/ux-design/motion-dev-docs.md"} {"recharts":".fnd/skills/ux-design/recharts-docs.md"} {"tanstackTable":".fnd/skills/ux-design/tanstack-table-docs.md"} {"tanstackQuery":".fnd/skills/ux-design/tanstack-query-docs.md"} {"tanstackRouter":".fnd/skills/ux-design/tanstack-router-docs.md"} {"uxLaws":".fnd/skills/ux-design/ux-laws-principles.md"} {"modernPatterns":".fnd/skills/ux-design/modern-patterns.md"} {"uxWriting":".fnd/skills/ux-design/ux-writing.md"}

Recommended Libs

{"core":[{"name":"shadcn/ui","for":"components"},{"name":"tailwindcss","for":"styling"},{"name":"motion","for":"animations"}]} {"data":[{"name":"recharts","for":"charts"},{"name":"@tanstack/react-table","for":"tables"},{"name":"@tanstack/react-query","for":"data fetching"}]} {"ux":[{"name":"sonner","for":"toasts","cmd":"npx shadcn add sonner"},{"name":"vaul","for":"mobile drawers","cmd":"npx shadcn add drawer"},{"name":"cmdk","for":"command palette","cmd":"npx shadcn add command"},{"name":"nuqs","for":"URL state"},{"name":"@tanstack/react-virtual","for":"1000+ items"}]}

Checklist (Before Shipping)

UX

• All states handled (loading, empty, error, success)
• Optimistic UI for quick actions
• Feedback for every action (toast, animation)
• Progressive disclosure (not everything visible)
• Consistent patterns throughout

Visual

• 60-30-10 color rule applied
• Shadows are tinted, not pure black
• Typography hierarchy clear
• Spacing consistent (4, 6, 8 scale)
• Dark mode works and looks intentional

Mobile

• Touch targets 44px+
• Input font 16px+
• Bottom drawers for modals
• Safe area padding
• Bottom nav or hamburger menu

Performance

• Skeleton loaders match layout
• Images lazy loaded with blur
• Lists virtualized if >50 items
• Prefetch on hover for links

Accessibility

• WCAG AA contrast
• All inputs labeled
• Focus visible and logical
• Reduced motion supported
• Keyboard navigation works

Quick Patterns

Layout Shell

<div className="min-h-screen bg-background">
  <header className="sticky top-0 z-50 border-b bg-background/95 backdrop-blur supports-[backdrop-filter]:bg-background/60">
    <div className="container flex h-14 md:h-16 items-center px-4" />
  </header>
  <div className="container flex flex-col md:flex-row gap-6 p-4 md:p-6">
    <aside className="hidden md:block w-64 shrink-0">
      <nav className="sticky top-20 space-y-2" />
    </aside>
    <main className="flex-1 min-w-0 space-y-6" />
  </div>
</div>

Card with Hover

<Card className="group cursor-pointer transition-all hover:shadow-lg hover:shadow-primary/5 hover:border-primary/50">
  <CardHeader>
    <CardTitle className="group-hover:text-primary transition-colors">
      {title}
    </CardTitle>
  </CardHeader>
</Card>

Animated List

<motion.ul initial="hidden" animate="show" variants={{
  hidden: { opacity: 0 },
  show: { opacity: 1, transition: { staggerChildren: 0.05 } }
}}>
  {items.map((item) => (
    <motion.li key={item.id} variants={{
      hidden: { opacity: 0, y: 10 },
      show: { opacity: 1, y: 0 }
    }}>
      {item.name}
    </motion.li>
  ))}
</motion.ul>

Responsive Chart

<div className="h-[200px] md:h-[300px] w-full">
  <ResponsiveContainer width="100%" height="100%">
    <LineChart data={data}>
      <CartesianGrid strokeDasharray="3 3" className="stroke-muted" />
      <XAxis dataKey="name" className="text-xs" tick={{ fill: 'hsl(var(--muted-foreground))' }} />
      <Tooltip contentStyle={{ backgroundColor: 'hsl(var(--popover))', border: '1px solid hsl(var(--border))' }} />
      <Line type="monotone" dataKey="value" stroke="hsl(var(--primary))" strokeWidth={2} dot={false} />
    </LineChart>
  </ResponsiveContainer>
</div>