Forms must allow people to understand what information is requested, enter and review it, correct mistakes, and complete the task. Test the complete workflow, including instructions, validation, errors, confirmation, time limits, and dynamic changes.

Use Drupal’s Form API for forms and user-input processing. It provides consistent structures for labels, descriptions, required fields, validation, and submission. Changing a form in a module or theme can remove these relationships, so test the rendered result.

Keep forms focused and predictable

Ask only for information needed to complete the task. Organize controls in a logical order and use headings or groups to divide long forms. Place general instructions before they are needed and explain unusual formats, constraints, required information, and time limits.

Use a multi-step form when it reduces complexity. Identify the current step and total progress. Preserve entered information when people move between steps or correct errors, unless doing so would create a security or privacy risk.

Use native controls and Drupal Form API properties

Choose the Form API element that matches the information or action. Native HTML controls provide expected semantics, keyboard behavior, mobile input, and assistive-technology support. Do not replace a button, checkbox, radio button, select element, or text field with a generic element only to achieve a visual design.

Use Form API properties instead of recreating accessible relationships manually. For example:

$form['email'] = [
  '#type' => 'email',
  '#title' => $this->t('Email address'),
  '#description' => $this->t('Used only for account notifications.'),
  '#required' => TRUE,
  '#attributes' => [
    'autocomplete' => 'email',
  ],
];

Use the correct input type and valid autocomplete token when a field collects information about the user and the input purpose is covered by WCAG. Do not use autocomplete tokens for unrelated information.

Provide persistent labels and instructions

Every form control needs an accessible name that describes its purpose. Prefer a persistent visible label. Visible labels help people with cognitive disabilities, people using magnification, and people using speech input as well as screen-reader users.

• Use #title to provide the label for a Form API control.
• Keep the visible label and accessible name consistent. The accessible name should include the visible label.
• Do not use placeholder text as a label. Placeholder text disappears during input and may be difficult to perceive.
• Do not use the title attribute as a routine replacement for a label.
• Use #title_display set to invisible only when the visible context still identifies the control. Test the result with screen readers, speech input, and magnification.
• Use #description for formats, limits, consequences, or other help associated with the control.
• Keep labels and instructions visually close to their controls, including after zoom, reflow, and text-spacing changes.

Instructions must be available before a person submits invalid data. Do not rely only on examples inside a field, color, an icon, or an error shown after submission.

Group related controls

Use a fieldset and legend, or the equivalent Form API structure, when several controls need a shared question or instruction. Common examples include radio buttons, related checkboxes, and groups of address or date fields.

Write the legend and individual labels so they make sense together without unnecessary repetition. A visual border is not a programmatic group, and visual proximity alone does not establish the relationship.

Identify required and optional information

Use #required for required Form API controls. Do not replace it with a manually added asterisk or aria-required. Drupal should generate the required state and indicator consistently.

Explain how required or optional fields are identified when the form could otherwise be unclear. Do not communicate the state through color alone. If most fields are required, marking the smaller number of optional fields may reduce clutter, but the programmatic required state must remain correct.

Design validation and errors as part of the form

Validate input as specifically as the task requires. Client-side validation can provide early feedback, but server-side validation is still required. Test how browser validation, custom JavaScript, Ajax, and Drupal validation work together.

When validation fails:

• Identify each error in text. Do not rely only on color, position, or an icon.
• Explain what went wrong and how to correct it.
• Associate the message programmatically with the affected control.
• Keep the person’s valid entries unless retaining them would create a security or privacy risk.
• Provide an error summary or notification that is easy to find.
• Link summary items to the affected controls when practical.
• Place focus predictably when moving it is necessary to make the errors apparent.
• Confirm that error text, controls, and focus indicators remain visible at high zoom and in responsive layouts.

The core Inline Form Errors module can place messages near affected controls and provide an error summary. Enabling it does not resolve every form requirement. Test valid and invalid submissions through the complete workflow.

Communicate dynamic changes

Conditional fields, Ajax updates, autocomplete suggestions, and calculated values must remain understandable and operable. When a change is not apparent from focus or the surrounding content, provide an appropriate status message.

• Keep names, descriptions, required states, and validation rules synchronized with the visible interface.
• Do not reveal a required field without making its requirement available programmatically.
• Move focus only when the user’s action or task requires it.
• Do not announce every document update. Announce the result a person needs to continue.
• Provide loading, completion, empty, and error states for asynchronous operations.
• Validate conditional requirements on the server as well as in the browser.

Prevent avoidable effort and serious mistakes

Do not require people to enter the same information twice in one process when Drupal can provide or select it, unless a WCAG exception applies. Allow people to review, correct, and confirm submissions that create legal commitments, financial transactions, data changes, or other serious consequences.

Support password managers and copying and pasting. Do not require a cognitive-function test, such as recalling or transcribing a password, when WCAG requires an accessible authentication alternative.

Avoid time limits where possible. When a time limit is required, provide the warnings and options to extend, adjust, or disable it that the applicable WCAG success criteria require. Preserve entered data after re-authentication when possible.

Use custom controls only when necessary

A styled native control is usually more reliable than a custom widget. If a native control cannot support the task, document and test the custom control’s:

• Accessible name, role, state, value, and description.
• Keyboard commands and focus behavior.
• Pointer, touch, speech-input, and magnification use.
• Expanded, selected, disabled, invalid, loading, and empty states.
• Behavior at high zoom and with text-spacing overrides.

Do not assume that an ARIA role or a component-library example provides the required behavior. Test the rendered control in the Drupal form and workflow.

Support disabled authors

Forms used to create or manage content are authoring interfaces. Apply the Authoring Tool Accessibility Guidelines (ATAG) 2.0 as well as WCAG.

Disabled authors must be able to complete the same tasks, receive the same validation and help, and review the same previews. Forms should also help every author produce accessible content by preserving accessibility information and prompting for decisions Drupal cannot make automatically.

Test the complete workflow

Test forms with representative roles, permissions, languages, content, valid and invalid input, and saved or restored state. Include, when relevant:

• Keyboard-only completion in both forward and reverse focus order.
• Visible labels, control names, instructions, groups, required states, and descriptions.
• Browser autofill, password managers, copying and pasting, and appropriate virtual keyboards.
• Text resizing, zoom, reflow, text spacing, forced colors, and target sizes.
• Client-side, Ajax, browser, and server-side validation.
• Error summaries, inline errors, focus placement, and correction of several errors.
• Timeouts, re-authentication, confirmation, cancellation, and recovery.
• Screen readers and other assistive technologies required by the project or affected behavior.
• Testing with disabled users for complex, unfamiliar, or high-impact forms when possible.

Automated tools can identify some missing labels, invalid relationships, or state problems. They cannot determine whether instructions are understandable, an error is useful, or a person can complete the process. Follow How to do an accessibility review and the W3C Forms Tutorial.