Building an HTML-First Site to Double User Conversion

HTML-First Architecture Doubled User Conversion

Replacing a complex, JavaScript-heavy React application with an HTML-first architecture using Astro doubled the number of users completing a service application form overnight. This increase occurred because the new system remained functional for users on outdated browsers, low-end hardware, and poor network connections—segments of the population that were previously bounced by JavaScript failures and were invisible to JavaScript-based analytics.

The Failure of JavaScript-Heavy Frameworks in Public Services

In a regulated monopoly utility company, a critical application form was previously managed via an old ASP form or a manual process. A recent attempt to modernize this using a React app failed within three days due to severe customer complaints. The failed implementation suffered from several critical flaws:

  • Performance Bottlenecks: The app relied on excessive loading spinners and global JavaScript states.
  • Accessibility Gaps: The application was not accessible to users with disabilities.
  • Storage Mismanagement: Vital image uploads were attempted to be stored in localStorage, which has a strict 5MB limit, leading to data loss and crashes.

Core Principles of the HTML-First Approach

To ensure the service worked for every possible user, the site was rebuilt using Astro with a focus on progressive enhancement. The architecture was guided by the requirement that the site must function on any machine, regardless of connection quality or browser age.

Technical Requirements for Universal Access

  • Unique Session IDs: Every form session was assigned a unique ID to track progress.
  • Server-Side Persistence: Data, including uploads, was stored on the backend at every step of the form wizard to prevent data loss.
  • JavaScript Independence: The form was fully completable without JavaScript enabled.
  • Legacy Browser Support: The site was designed to function on outdated and low-performance web browsers.
  • Accessibility Compliance: The team adhered to WCAG AA standards.
  • Progressive Enhancement: Modern CSS and JavaScript were used only to enhance the experience, not as a requirement for core functionality.

Implementation: Form Wizards and Validation

The Multi-Page Form Pattern

The application utilized a venerable web pattern where each step of the form wizard was its own page. When a user clicked "next," the form submitted to the server; if the API validated the data, the browser was redirected to the next step. This approach avoided shipping megabytes of JavaScript to users who might be accessing the service on decade-old mobile devices over 3G connections.

Lightweight Validation via Web Components

Rather than using heavy React validation libraries, the developer implemented a custom HTML web component (later released as validation-enhancer). This component:

  1. Wrapped existing HTML forms and utilized native browser validation.
  2. Prevented default browser tooltips, instead placing errors in aria-describedby (or aria-errormessage) elements.
  3. Cleared validation errors in real-time as the user typed.
  4. Fell back to native browser validation if the JavaScript failed, and further fell back to backend API validation.

This entire validation enhancement was delivered in under 1KB of code.

Analysis of Results and Industry Implications

The "Invisible User" Phenomenon

The doubling of completed forms revealed a critical flaw in modern telemetry: JavaScript-based analytics packages cannot track users who bounce due to JavaScript failures. These users are effectively invisible to developers until the underlying technical barrier is removed.

Community Insights and Counterpoints

Technical discussions surrounding this case highlight a divide between "Resume Driven Development" and user-centric engineering:

  • The Case for Simplicity: Many developers noted that for most projects, a stack of HTMX, Go, and SQLite is sufficient, and that the industry has drifted toward unnecessary complexity due to the influence of big tech and VC funding.
  • The "Good Design" Argument: Some critics argued that the success was due to better design and a competent developer rather than the specific choice of HTML over React, noting that React can also be used to build accessible, performant sites if implemented correctly.
  • The Accessibility Mandate: Commenters emphasized that for government and utility services, providing a "lite" fallback is not just a preference but a quasi-legal requirement to ensure no citizen is alienated from critical infrastructure.

"Of course, your javascript-based analytics package doesn’t see the users you are bouncing because of javascript failures. It is frightening to think of how many people are alienated from critical systems every day because of this bias reinforcing the idea that they do not exist."

Conclusion

Building for the lowest common denominator—such as a PlayStation Portable on a 3G connection—ensures that a service works for everyone. By prioritizing HTML and progressive enhancement over client-side frameworks, developers can reach a wider audience and create systems that remain functional for decades.

Sources