Accessibility form patterns for large-scale services

Introduction

Form accessibility is not a matter of passing one screen, but an operational topic directly related to the overall reliability of the product. As the service grows, components and error message rules change for each team, making it difficult to provide a consistent experience to keyboard users and screen reader users. This article covers how to create reusable form contracts in large-scale services and automatically validate them before release.

Problem definition

Most accessibility problems arise from missing basic rules rather than complex technologies. In particular, when the following items accumulate, disability reports increase rapidly:

• The connection between the label and the input element is broken during the component wrapping process.
• Field errors are displayed only visually and are not transmitted to the screen reader.
• There is no focus movement policy after verification failure, so the user does not know where the failure occurred.

The solution strategy is simple. Accessibility contracts should be enforced on form components, and contract violations in storybooks/tests should be blocked at the build stage.

Key concepts

Accessibility fails when maintained as a checklist document. Maintenance costs are reduced when the UI component itself is designed to not allow failure.

Code Example 1: FormField component contract

import { useId } from "react";

type FieldProps = {
  label: string;
  error?: string;
  children: (inputProps: { id: string; "aria-invalid": boolean; "aria-describedby"?: string }) => React.ReactNode;
};

export function FormField({ label, error, children }: FieldProps) {
  const id = useId();
  const errorId = id + "-error";

  return (
    <div className="space-y-1">
      <label htmlFor={id} className="text-sm font-medium">{label}</label>
      {children({ id, "aria-invalid": Boolean(error), "aria-describedby": error ? errorId : undefined })}
      {error ? <p id={errorId} role="alert" className="text-sm text-red-600">{error}</p> : null}
    </div>
  );
}

Code example 2: Move focus to first error field

export function focusFirstInvalidField(form: HTMLFormElement) {
  const invalid = form.querySelector<HTMLElement>("[aria-invalid='true']");
  if (!invalid) return;

  invalid.focus();
  invalid.scrollIntoView({ behavior: "smooth", block: "center" });
}

export function onSubmitError(form: HTMLFormElement, errors: Record<string, string>) {
  if (Object.keys(errors).length === 0) return;
  focusFirstInvalidField(form);
}

Architecture flow

Tradeoffs

• Enforcing a common FormField incurs initial migration costs, but significantly reduces operational quality variation.
• Real-time verification allows immediate feedback, but excessive verification can disrupt the input flow.
• Incorporating accessibility tests into CI slows deployment, but significantly reduces failure ticket costs.

Cleanup

Large-scale form accessibility is a contract design issue, not individual page improvement. By embedding rules in the component API and adding automatic verification, the quality of accessibility can be maintained above a certain level even as functions increase.

Image source

• Cover: source link
• License: CC BY-SA 3.0 / Author: MichaelMaggs
• Note: After downloading the free license image from Wikimedia Commons, it was optimized to JPG at 1600px.