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)

• Component-first thinking - reusable, composable UI pieces

• Mobile-first responsive design - start small, scale up

• Performance budgets - aim for sub-3s load times

• Semantic HTML and proper ARIA attributes

• 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:

• Purpose: What specific problem does this interface solve?

• 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

• Constraints: Framework requirements, performance budget, accessibility level

• 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:

• Task completion: Can user complete their goal?

• Error recovery: Can user recover from mistakes?

• Accessibility: Can all users access it?

• Performance: Does it feel responsive?

Typography Rules

Rule Correct Wrong

Ellipsis … (single character) ... (three periods)

Quotes " " curly quotes " " straight quotes

Units 10&nbsp;MB (non-breaking) 10 MB (can break)

Shortcuts ⌘&nbsp;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:

• What is the user trying to accomplish? - Specific task, not feature

• What are the steps? - Click by click

• What can go wrong? - Every error state

• Who might struggle? - Accessibility needs

• 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

Accessibility Issues

Visual Issues

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