Frontend Patterns

Overview

User interfaces exist to help users accomplish tasks. Every UI decision should make the user's task easier or the interface more accessible.

Core principle: Design for user success, not aesthetic preference.

This skill is advisory in v10. Explicit user instructions, CLAUDE.md, repo standards, and approved plans override every suggestion here.

Focus Areas (Reference Pattern)

• React component architecture (hooks, context, performance)
• Responsive CSS with Tailwind/CSS-in-JS
• State management (Redux, Zustand, Context API)
• Frontend performance (lazy loading, code splitting, memoization)
• Accessibility (WCAG compliance, ARIA labels, keyboard navigation)

Approach (Reference Pattern)

1. Component-first thinking - reusable, composable UI pieces
2. Mobile-first responsive design - start small, scale up
3. Performance budgets - aim for sub-3s load times
4. Semantic HTML and proper ARIA attributes
5. Type safety with TypeScript when applicable

Advisory Guardrails

Use this skill to add:

• accessibility checks
• responsive/layout verification
• performance and loading-state checks
• optional style ideas when the user explicitly wants them

Do not use this skill to override an explicit visual direction, component contract, or approved workflow.

Component Output Checklist

Every frontend deliverable should include:

• Complete React component with props interface
• Styling solution (Tailwind classes or styled-components)
• State management implementation if needed
• Basic unit test structure
• Accessibility checklist for the component
• Performance considerations and optimizations

Focus on working code over explanations. Include usage examples in comments.

The Iron Law

NO UI DESIGN BEFORE USER FLOW IS UNDERSTOOD

If you haven't mapped what the user is trying to accomplish, you cannot design UI.

Design Thinking (Pre-Code)

Before writing any UI code, commit to answers for:

1. Purpose: What specific problem does this interface solve?
2. Tone: Choose an aesthetic direction and commit to it:
   • Brutally minimal, maximalist, retro-futuristic, organic/natural
   • Luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw
   • Art deco/geometric, soft/pastel, industrial/utilitarian
3. Constraints: Framework requirements, performance budget, accessibility level
4. Differentiation: What's the ONE thing someone will remember about this UI?

Key insight: Bold maximalism and refined minimalism both work. The enemy is indecision and generic defaults.

Loading State Order (CRITICAL)

Always handle states in this order:

// CORRECT order
if (error) return <ErrorState error={error} onRetry={refetch} />;
if (loading && !data) return <LoadingState />;
if (!data?.items.length) return <EmptyState />;
return <ItemList items={data.items} />;

Loading State Decision Tree:

Is there an error? → Yes: Show error with retry
                   → No: Continue
Is loading AND no data? → Yes: Show loading indicator
                        → No: Continue
Do we have data? → Yes, with items: Show data
                 → Yes, but empty: Show empty state
                 → No: Show loading (fallback)

Golden Rule: Show loading indicator ONLY when there's no data to display.

Skeleton vs Spinner

Use Skeleton When	Use Spinner When
Known content shape	Unknown content shape
List/card layouts	Modal actions
Initial page load	Button submissions
Content placeholders	Inline operations

Motion & Animation

Rule	Do	Don't
Reduced motion	Honor prefers-reduced-motion	Ignore user preferences
Properties	Animate transform/opacity only	Animate width/height/top/left
Transitions	List properties explicitly	Use transition: all
Duration	150-300ms for micro-interactions	Too fast (<100ms) or slow (>500ms)
Interruptible	Allow animation cancellation	Lock UI during animation

/* CORRECT: Compositor-friendly, respects preferences */
@media (prefers-reduced-motion: no-preference) {
  .card { transition: transform 200ms ease-out, opacity 200ms ease-out; }
  .card:hover { transform: translateY(-2px); opacity: 0.95; }
}

Error Handling Hierarchy

Level	Use For
Inline error	Field-level validation
Toast notification	Recoverable errors, user can retry
Error banner	Page-level errors, data still partially usable
Full error screen	Unrecoverable, needs user action

Success Criteria Framework

Every UI must have explicit success criteria:

1. Task completion: Can user complete their goal?
2. Error recovery: Can user recover from mistakes?
3. Accessibility: Can all users access it?
4. Performance: Does it feel responsive?

Typography Rules

Rule	Correct	Wrong
Ellipsis	… (single character)	... (three periods)
Quotes	" " curly quotes	" " straight quotes
Units	10 MB (non-breaking)	10 MB (can break)
Shortcuts	⌘ K (non-breaking)	⌘ K (can break)
Loading text	Loading…	Loading...
Numbers in tables	font-variant-numeric: tabular-nums	Default proportional
Headings	text-wrap: balance	Unbalanced line breaks
Line length	65-75 characters max	Unlimited width

Content Overflow Handling

Prevent broken layouts from user-generated content:

Scenario	Solution
Single-line overflow	truncate (Tailwind) or text-overflow: ellipsis
Multi-line overflow	line-clamp-2 / line-clamp-3
Long words/URLs	break-words or overflow-wrap: break-word
Flex child truncation	Add min-w-0 to flex children (critical!)
Empty strings/arrays	Show placeholder, not broken UI

{/* Flex truncation pattern - min-w-0 is REQUIRED */}
<div className="flex items-center gap-2 min-w-0">
  <Avatar />
  <span className="truncate min-w-0">{user.name}</span>
</div>

Test with: short text, average text, and absurdly long text (50+ characters).

Universal Questions (Answer First)

ALWAYS answer before designing/reviewing:

1. What is the user trying to accomplish? - Specific task, not feature
2. What are the steps? - Click by click
3. What can go wrong? - Every error state
4. Who might struggle? - Accessibility needs
5. What's the existing pattern? - Project conventions

User Flow First

Before any UI work, map the flow:

User Flow: Create Account
1. User lands on signup page
2. User enters email
3. User enters password
4. User confirms password
5. System validates inputs (inline)
6. User clicks submit
7. System processes (loading state)
8. Success: User sees confirmation + redirect
9. Error: User sees error + can retry

For each step, identify:

• What user sees
• What user does
• What feedback they get
• What can go wrong

UX Review Checklist

Check	Criteria	Example Issue
Task completion	Can user complete goal?	Button doesn't work
Discoverability	Can user find what they need?	Hidden navigation
Feedback	Does user know what's happening?	No loading state
Error handling	Can user recover from errors?	No error message
Efficiency	Can user complete task quickly?	Too many steps

Severity levels:

• BLOCKS: User cannot complete task
• IMPAIRS: User can complete but with difficulty
• MINOR: Small friction, not blocking

Accessibility Review Checklist (WCAG 2.1 AA)

Check	Criterion	How to Verify
Keyboard	All interactive elements keyboard accessible	Tab through entire flow
Focus visible	Current focus clearly visible	Tab and check highlight
Focus order	Logical tab order	Tab matches visual order
Labels	All inputs have labels	Check <label> or aria-label
Alt text	Images have meaningful alt	Check alt attributes
Color contrast	4.5:1 for text, 3:1 for large	Use contrast checker
Color alone	Info not conveyed by color only	Check without color
Screen reader	Content accessible via SR	Test with VoiceOver/NVDA

For each issue found:

- [WCAG 2.1 1.4.3] Color contrast at `component:line`
  - Current: 3.2:1 (fails AA)
  - Required: 4.5:1
  - Fix: Change text color to #333 (7.1:1)

Form Best Practices

Rule	Implementation
Autocomplete	Add autocomplete="email", autocomplete="name", etc.
Input types	Use type="email", type="tel", type="url" for mobile keyboards
Input modes	Add inputMode="numeric" for number-only fields
Never block paste	No onPaste + preventDefault() — users paste passwords
Spellcheck off	spellCheck={false} on emails, codes, usernames
Unsaved changes	Warn before navigation (beforeunload or router guard)
Error focus	Focus first error field on submit
Shared hit targets	Checkbox/radio label + control = one clickable area

<input
  type="email"
  autoComplete="email"
  spellCheck={false}
  inputMode="email"
  // Never: onPaste={(e) => e.preventDefault()}
/>

Visual Design Checklist

Check	Good	Bad
Hierarchy	Clear visual priority	Everything same size
Spacing	Consistent rhythm	Random gaps
Alignment	Elements aligned to grid	Misaligned elements
Interactive states	Hover/active/focus distinct	No state changes
Feedback	Clear response to actions	Silent interactions

Visual Creativity (Avoid AI Slop)

When creating frontends, avoid generic AI aesthetics:

• Fonts: Choose distinctive typography, not defaults (avoid Inter, Roboto, Arial, system fonts)
• Colors: Commit to cohesive palette. Dominant colors with sharp accents > safe gradients
• Avoid: Purple gradients on white, predictable layouts, cookie-cutter Bootstrap/Tailwind defaults
• Icons: Use SVG icons (Heroicons, Lucide, Simple Icons). NEVER use emoji as UI icons
• Cursor: Add cursor-pointer to ALL clickable elements
• Hover: Use color/opacity transitions. Avoid scale transforms that shift layout
• Backgrounds: Add depth with subtle textures, gradients, or grain instead of flat colors

Make creative choices that feel designed for the specific context. No two designs should look the same.

Spatial Composition (Break the Grid)

Move beyond safe, centered layouts:

Technique	Effect	When to Use
Asymmetry	Dynamic tension, visual interest	Hero sections, feature highlights
Overlap	Depth, connection between elements	Cards, images, testimonials
Diagonal flow	Energy, movement	Landing pages, marketing
Grid-breaking	Emphasis, surprise	Key CTAs, focal points
Generous negative space	Luxury, breathing room	Premium products, editorial
Controlled density	Information-rich, productive	Dashboards, data-heavy UIs

Rule: Match spatial composition to the aesthetic direction chosen in Design Thinking. Minimalist = negative space. Maximalist = controlled density.

Component Patterns

Buttons

// Primary action button with all states
<button
  type="button"
  onClick={handleAction}
  disabled={isLoading || isDisabled}
  aria-busy={isLoading}
  aria-disabled={isDisabled}
  className={cn(
    'btn-primary',
    isLoading && 'btn-loading'
  )}
>
  {isLoading ? (
    <>
      <Spinner aria-hidden />
      <span>Processing...</span>
    </>
  ) : (
    'Submit'
  )}
</button>

Forms with Validation

<form onSubmit={handleSubmit} noValidate>
  <div className="form-field">
    <label htmlFor="email">
      Email <span aria-hidden>*</span>
      <span className="sr-only">(required)</span>
    </label>
    <input
      id="email"
      type="email"
      value={email}
      onChange={handleChange}
      aria-invalid={errors.email ? 'true' : undefined}
      aria-describedby={errors.email ? 'email-error' : 'email-hint'}
      required
    />
    <span id="email-hint" className="hint">
      We'll never share your email
    </span>
    {errors.email && (
      <span id="email-error" role="alert" className="error">
        {errors.email}
      </span>
    )}
  </div>
</form>

Loading States

function DataList({ isLoading, data, error }) {
  if (isLoading) {
    return (
      <div aria-live="polite" aria-busy="true">
        <Spinner />
        <span>Loading items...</span>
      </div>
    );
  }

  if (error) {
    return (
      <div role="alert" className="error-state">
        <p>Failed to load items: {error.message}</p>
        <button onClick={retry}>Try again</button>
      </div>
    );
  }

  if (!data?.length) {
    return (
      <div className="empty-state">
        <p>No items found</p>
        <button onClick={createNew}>Create your first item</button>
      </div>
    );
  }

  return <ul>{data.map(item => <Item key={item.id} {...item} />)}</ul>;
}

Error Messages

// Inline error with recovery action
<div role="alert" className="error-banner">
  <Icon name="error" aria-hidden />
  <div>
    <p className="error-title">Upload failed</p>
    <p className="error-detail">File too large. Maximum size is 10MB.</p>
  </div>
  <button onClick={selectFile}>Choose different file</button>
</div>

Responsive Design Checklist

Breakpoint	Check
Mobile (< 640px)	Touch targets 44px+, no horizontal scroll
Tablet (640-1024px)	Layout adapts, navigation accessible
Desktop (> 1024px)	Content readable, not too wide

Performance Rules

Rule	Why	Implementation
Virtualize large lists	>50 items kills performance	Use virtua, react-window, or content-visibility: auto
No layout reads in render	Causes forced reflow	Avoid getBoundingClientRect, offsetHeight in render
Lazy load images	Reduces initial load	loading="lazy" on below-fold images
Prioritize critical images	Faster LCP	fetchpriority="high" or Next.js priority
Preconnect CDN	Faster asset loading	<link rel="preconnect" href="https://cdn...">
Preload fonts	Prevents FOUT	<link rel="preload" as="font" crossorigin>

URL & State Management

URL should reflect UI state. If it uses useState, consider URL sync.

State Type	URL Strategy
Filters/search	?q=term&category=books
Active tab	?tab=settings
Pagination	?page=3
Expanded panels	?panel=details
Sort order	?sort=price&dir=asc

Benefits: Shareable links, back button works, refresh preserves state.

// Use nuqs, next-usequerystate, or similar
const [tab, setTab] = useQueryState('tab', { defaultValue: 'overview' })

Touch & Mobile

Rule	Implementation
44px touch targets	Minimum for buttons, links, controls
No double-tap delay	touch-action: manipulation on interactive elements
Modal scroll lock	overscroll-behavior: contain in modals/drawers
Safe areas	padding: env(safe-area-inset-bottom) for notches
Tap highlight	Set -webkit-tap-highlight-color intentionally

Red Flags - STOP and Reconsider

If you find yourself:

• Designing UI before mapping user flow
• Focusing on aesthetics before functionality
• Ignoring accessibility ("we'll add it later")
• Not handling error states
• Not providing loading feedback
• Using color alone to convey information
• Making decisions based on "it looks nice"

STOP. Go back to user flow.

Rationalization Prevention

Excuse	Reality
"Most users don't use keyboard"	Some users ONLY use keyboard.
"We'll add accessibility later"	Retrofitting is 10x harder.
"Error states are edge cases"	Errors happen. Handle them.
"Loading is fast, no need for state"	Network varies. Show state.
"It looks better without labels"	Unlabeled inputs are inaccessible.
"Users can figure it out"	If it's confusing, fix it.

Anti-patterns Blocklist (Flag These)

Anti-pattern	Why It's Wrong	Fix
user-scalable=no	Blocks accessibility zoom	Remove it
maximum-scale=1	Blocks accessibility zoom	Remove it
transition: all	Performance + unexpected effects	List properties explicitly
outline-none without replacement	Removes focus indicator	Add focus-visible:ring-*
<div onClick>	Not keyboard accessible	Use <button> or <a>
Images without width/height	Causes layout shift (CLS)	Add explicit dimensions
Form inputs without labels	Inaccessible	Add <label> or aria-label
Icon buttons without aria-label	Unnamed to screen readers	Add aria-label
Emoji icons (🚀 ✨ 💫)	Unprofessional, inconsistent	Use SVG icons
Hardcoded date/number formats	Breaks internationalization	Use Intl.DateTimeFormat
autoFocus everywhere	Disorienting, mobile issues	Use sparingly, desktop only

Light/Dark Mode

Rule	Light Mode	Dark Mode
Glass/transparent	bg-white/80 or higher	bg-black/80 or darker
Text contrast	Minimum 4.5:1 (slate-900)	Minimum 4.5:1 (slate-100)
Borders	border-gray-200	border-white/10
HTML attribute	—	color-scheme: dark on <html>
Meta tag	Match background	Match background

<!-- Dark mode setup -->
<html style="color-scheme: dark">
<head><meta name="theme-color" content="#0f172a"></head>

Output Format

## Frontend Review: [Component/Feature]

### User Flow
[Step-by-step what user is trying to do]

### Success Criteria
- [ ] User can complete [task]
- [ ] User can recover from errors
- [ ] All users can access (keyboard, screen reader)
- [ ] Interface feels responsive

### UX Issues
| Severity | Issue | Location | Impact | Fix |
|----------|-------|----------|--------|-----|
| BLOCKS | [Issue] | `file:line` | [Impact] | [Fix] |

### Accessibility Issues
| WCAG | Issue | Location | Fix |
|------|-------|----------|-----|
| 1.4.3 | [Issue] | `file:line` | [Fix] |

### Visual Issues
| Issue | Location | Fix |
|-------|----------|-----|
| [Issue] | `file:line` | [Fix] |

### Recommendations
1. [Most critical fix]
2. [Second fix]

UI States Checklist (CRITICAL)

Before completing ANY UI component:

States

• Error state handled and shown to user
• Loading state shown ONLY when no data exists
• Empty state provided for all collections/lists
• Success state with appropriate feedback

Buttons & Mutations

• Buttons disabled during async operations
• Buttons show loading indicator
• Mutations have onError handler with user feedback
• No double-click possible on submit buttons

Data Handling

• State order: Error → Loading (no data) → Empty → Success
• All user actions have feedback (toast/visual)

Final Check

Before completing frontend work:

• User flow mapped and understood
• All states handled (loading, error, empty, success)
• Keyboard navigation works
• Screen reader tested
• Color contrast verified (4.5:1 minimum)
• Touch targets adequate on mobile (44px+)
• Error messages clear and actionable
• Success criteria met
• No emoji icons (SVG only)
• prefers-reduced-motion respected
• Light/dark mode contrast verified
• cursor-pointer on all clickable elements
• No transition: all in codebase