The 400ms Rule: Doherty Threshold

The Doherty Threshold (Walter Doherty, IBM, 1982): when system response time falls below 400ms, users stay in a "flow" state — they feel like they're operating through the system, not waiting on it. Above 400ms, users shift mental modes. They look away, start a second task, or lose the thread of what they were doing.

2. Optimistic updates. For mutations (save, toggle, delete), apply the state change immediately and roll back on failure. The user sees the result before the server responds:

// Optimistic toggle — state change is immediate
async function toggleFavorite(itemId) {
  // Apply immediately (optimistic)
  setItems(items => items.map(i =>
    i.id === itemId ? { ...i, favorite: !i.favorite } : i
  ));
  try {
    await api.toggleFavorite(itemId);
    // Server confirmed — do nothing, state is already correct
  } catch (err) {
    // Rollback only on failure
    setItems(items => items.map(i =>
      i.id === itemId ? { ...i, favorite: !i.favorite } : i
    ));
    showError('Could not save. Please try again.');
  }
}

Failure rates for toggle operations are typically under 0.1% on stable connections. The UX cost of waiting for server confirmation on every toggle is paid by 100% of users; the rollback cost is paid by 0.1%.

The 600ms debounce was a copy-paste from a tutorial written in 2016 for slow mobile connections and servers with 400ms+ response times. Modern documentation stacks on fast CDN infrastructure have API response times of 50–150ms. A 600ms debounce on a 100ms API means the user waits 700ms by design — well above the 400ms Doherty Threshold — because of a configuration value that was never revisited. The server was not slow; the client was engineered to feel slow.

The architectural insight: the Doherty Threshold applies to the first perceptible response, not the final response. A user who sees partial results in 10ms and accurate results in 250ms experiences 10ms latency psychologically — their attention is engaged from the first keystroke. A user who sees nothing for 600ms and then sees results experiences 600ms latency — a full stop, a moment of wondering if the input registered. Same final results; completely different perception of responsiveness.

The demo asks you to complete a quick lookup task in both modes and rates your perceived frustration. 700ms inputs score 2–3/10 on satisfaction; sub-200ms inputs score 8–9/10. Same task, same result — different latency.

Building a local search index at idle time with requestIdleCallback ensures the index build does not compete with the initial page render or user interaction. The index should be capped in size — 200–500 documents is enough for instant-feeling results without noticeable memory cost. Libraries like lunr.js (small, no dependencies) or Pagefind (WASM-based, pre-built at static site generation time) are the two most practical choices for documentation sites.

// Build local index at idle — does not block interaction
let localIndex = null;

requestIdleCallback(() => {
  // lunr.js — lightweight, synchronous indexing
  localIndex = lunr(function () {
    this.ref('id');
    this.field('title', { boost: 10 });
    this.field('headings', { boost: 5 });
    this.field('description');
    TOP_200_DOCS.forEach(doc => this.add(doc));
  });
}, { timeout: 2000 }); // build within 2s even if never idle

function searchLocal(query) {
  if (!localIndex || query.length < 2) return [];
  return localIndex.search(query).slice(0, 8);
}