Build websites that survive reality.

Example: a menu must open, expose its expanded state, move through links by keyboard, and close predictably. HTML owns the button and navigation semantics; CSS owns presentation; JavaScript owns the expanded state; the test owns the observable interaction. If the requirement is only disclosure of adjacent content, native <details> may remove most of that coordination.

Write the evidence beside the decision. A component note can state the expected source order, keyboard contract, loading behavior, performance budget, and release smoke check. That short record prevents later maintainers from interpreting accidental implementation details as requirements.

After implementation, follow the path forward and backward. Can the visitor complete the task? Can a maintainer identify the failing layer? Can operations return to the last known good artifact? “Done” is the intersection of those answers, not the moment a component renders once.

Working principle: prefer an observable invariant over a reassuring status. HTTP 200 proves that something answered; it does not prove that the intended release, accessible interaction, or current content answered.

A visit starts with a URL, not a component. The browser resolves the host, establishes a connection, negotiates security, sends an HTTP request, and interprets the response status and headers. A redirect can change the destination before any document is parsed. A cache can satisfy the request without contacting the origin. A service worker can intercept it. If the final response is HTML, the browser tokenizes the document and builds a DOM while discovering stylesheets, images, fonts, scripts, and other dependencies.

CSS follows its own path. The browser parses rules, calculates which declarations win, resolves inherited and computed values, and produces the boxes needed for layout. Layout determines geometry; paint turns visual instructions into display items; compositing arranges suitable layers for the screen. JavaScript can interrupt or extend this sequence by changing the DOM, modifying styles, scheduling work, or requesting more data. The process is incremental: users can see and operate useful content before every optional asset has finished, provided the document and loading strategy allow it.

This model explains why similar symptoms can have unrelated causes. A blank area may be a missing response, a CSS rule hiding content, an image without reserved dimensions, a script waiting for data, or text painted in an unreadable color. A slow click may come from a long event handler, layout forced repeatedly inside a loop, a network dependency, or work from an unrelated widget sharing the main thread. Begin with the layer that can produce the observed signal, then collect evidence from the network panel, DOM, computed styles, performance trace, accessibility tree, server log, or release manifest.

A useful trace ends in a reproducible statement: under a named input and environment, a specific layer violates a specific invariant. “The page is flaky” is not yet a diagnosis. “When two searches overlap, the slower first response replaces the second result because the request is not cancelled or checked against current state” is actionable. It names the trigger, the incorrect transition, and the smallest boundary where a fix can be verified.

Assume a page lists technical articles and lets a reader filter by topic. The durable starting point is a server-rendered list of links with useful titles and summaries. That baseline is readable, indexable, and operable even if JavaScript fails. Put the filter controls in a form. Give each control a visible label. Use a submit button so the interaction has a native keyboard path and a meaningful fallback. If the selected filter belongs in a query parameter, the resulting URL becomes shareable, restorable through browser history, and testable without reconstructing private application state.

CSS can enhance the layout without changing the document’s meaning. A grid may place controls beside results on wide screens and stack them on narrow screens. Cards can use intrinsic sizing and wrapping instead of fixed heights. Focus styles must remain visible. Status text should not be conveyed by color alone. Reserve space for predictable media, but let text expand when a title wraps or the visitor increases font size. The success criterion is not that every screenshot matches; it is that content relationships and controls remain understandable across supported conditions.

JavaScript can then intercept the form to update results without a full navigation. Model the interface with explicit states: idle, loading, success with results, success with no results, and error. Keep the submitted criteria separate from controls the user is still editing. Disable only actions that truly conflict with the pending operation. Associate a visible status with the result region and move focus only when doing so helps the task; unexpected focus movement can be more disruptive than the original update.

let currentRequest;

async function updateResults(url) {
  currentRequest?.abort();
  currentRequest = new AbortController();
  setStatus("loading");

  try {
    const response = await fetch(url, { signal: currentRequest.signal });
    if (!response.ok) throw new Error(`Request failed: ${response.status}`);
    renderResults(await response.json());
    setStatus("success");
  } catch (error) {
    if (error.name !== "AbortError") setStatus("error");
  }
}

The important feature is not the exact syntax. The latest request owns the visible result, and cancellation is treated differently from failure. Without that rule, a slow response to an earlier choice can overwrite a fast response to the current choice. The same invariant can be implemented with a request identifier or framework lifecycle, but it should stay visible in the design and in the test.

Test the baseline first: load the page with JavaScript disabled, submit a filter, and confirm that the server returns the expected URL and list. Then test the enhancement with a keyboard, a screen reader’s basic navigation, artificial latency, an empty result, an error response, rapid repeated submissions, browser Back, and a narrow viewport at increased zoom. Inspect the network log to confirm cancelled or superseded work. Verify that the status is announced without repeating every keystroke and that the result heading remains easy to locate.

Performance work follows evidence. If interaction delay comes from rendering hundreds of cards, reduce the work, paginate, or render in manageable batches. If images dominate loading, send suitable dimensions and formats. If the filter’s code is tiny, adding a heavy client runtime may cost more than it saves. The best architecture is the smallest one that preserves the URL, accessible control contract, explicit async states, and measurable response to the user’s action.

1. State the observation. Record the exact URL, input, viewport, browser, release identity, expected result, and actual result.
2. Find a minimal reproduction. Remove unrelated routes, data, extensions, accounts, and timing until the failure has the fewest necessary conditions.
3. Choose the likely owning layer. Use the symptom to begin at network, document, style, layout, behavior, data, or release—not to declare the answer.
4. Collect discriminating evidence. Prefer a check whose result would make one hypothesis more likely and another less likely.
5. Change one cause. Avoid bundles of speculative edits that make a passing result impossible to attribute.
6. Verify the invariant and nearby paths. Re-run the reproduction, a normal case, a failure case, and the smallest relevant regression check.

Suppose a dialog sometimes opens behind the page. Randomly increasing its z-index may appear to work, but it does not identify the stacking context that trapped it. Inspect the ancestors, positioned elements, transforms, opacity, isolation, and top-layer behavior. The durable question is whether the dialog belongs in the browser’s top layer or whether an unnecessary ancestor created a new stacking context. The fix might be native <dialog>, a corrected DOM boundary, or removal of the creating property—not a number large enough to win today.

Suppose a layout jumps during load. Capture a performance trace or enable layout-shift regions. Identify the element that moved and the element whose late size change caused it. A card may need image dimensions or an aspect ratio; text may need a better font-loading strategy; injected content may need reserved space; a banner may need to avoid insertion above the current viewport. The metric guides attention, but the trace supplies the causal relationship.

Suppose production shows old content after a successful deployment. Confirm the runtime release identity before purging caches or redeploying. Compare the requested host, resolved destination, response headers, artifact hash, and server process. The pipeline may have promoted one artifact while traffic still reaches another environment, or a cache key may ignore a release-varying input. “Deploy again” can temporarily change the symptom while preserving the routing defect that caused it.

Keep a short evidence log for difficult incidents: timestamp, request, release, observation, hypothesis, check, result, and next decision. This is not ceremonial documentation. It prevents loops, helps another person reproduce the state, and makes the final regression check obvious. Once the cause is confirmed, preserve only the smallest durable evidence—a test, assertion, health field, or runbook check that catches the same class of failure before users do.

Build once and promote the same immutable artifact through environments. Rebuilding for production creates a new object with potentially different dependencies, timestamps, generated files, or configuration. Record the source commit, build identifier, dependency lock state, and artifact digest. Keep environment-specific secrets and endpoints outside the compiled source where practical, but validate their required shape before traffic switches.

Separate deployment success from service health and release correctness. A process can start and answer HTTP 200 while serving the wrong build, failing its critical dependency, or returning a generic fallback. Expose a safe release identifier and use a smoke test through the same public host, TLS, proxy, and routing path that visitors use. Test a representative page, an essential asset, and one critical interaction or data request. Do not leak secrets or internal topology in the health response.

Choose a traffic switch that matches the risk. A small static site may use an atomic symlink or directory swap. A service may use rolling, blue-green, or canary deployment. Whatever the mechanism, define what happens to in-flight work, schema compatibility, caches, background jobs, and sessions. Database changes deserve special attention: expand the schema so old and new code can coexist, deploy compatible code, migrate data when necessary, and contract only after the previous version no longer depends on the old shape.

A rollback is a practiced operation, not a sentence in a plan. Preserve the previous artifact and the configuration needed to run it. Know whether a data migration is backward compatible. Define the signal that triggers rollback and the person authorized to initiate it. After switching back, verify public release identity and the same critical path used after deployment. If rollback would lose accepted user data, the safer response may be to disable the affected feature, route around it, or roll forward with a narrowly scoped repair.

Observability should describe the user journey as well as the machine. Combine rates and latency with a small number of task-level signals: whether a page produced its primary content, whether an action reached its confirmed state, and whether the expected release served the request. Break down failures by route, release, and dependency only where that dimension changes a decision. An alert that cannot suggest an owner or response creates noise; an alert tied to a service objective, recent release, and runnable check gives the operator a useful starting point.

After a stable release, remove temporary flags, stale artifacts, and emergency exceptions on an explicit schedule. Confirm backups can be restored, certificates and domains have owners, and monitoring follows the canonical host. These routine controls are easy to postpone because they do not change the visible interface, yet they determine whether the next change is reversible. Operational simplicity is a feature: fewer hidden variants mean fewer possible explanations when production behaves differently from a developer’s machine.

Close the loop by connecting operational evidence to development decisions. If an incident came from a missing cache variation, encode the cache key contract. If an asset path broke under a subdirectory, add a deployed-path smoke check. If a database change blocked rollback, change the migration sequence. Reliable teams do not eliminate every failure; they make failures legible, bounded, and progressively harder to repeat.