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.

Violating the letter of this process is violating the spirit of frontend design.

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.

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?

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

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)

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)

Visual Design Checklist

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

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

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]

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
• Touch targets adequate on mobile
• Error messages clear and actionable
• Success criteria met