From WCAG to component requirements: Make accessibility testable

Category: Accessibility

Accessibility is often treated as a check at the end of a web project. By then, the team will often discover issues with contrast, keyboard navigation, forms and screen reader support after the design, content and code are already in place. The issues are more expensive to fix, and the same problems may arise again the next time someone creates a new page.

A more robust method is to make accessibility part of the requirements for each reusable component. A menu, button, form field, dialog box or product card should not only look right. The component must also be usable with a keyboard, understandable to a screen reader and functional when magnified and under different contrast requirements.

The result is a concrete definition of what “done” means. WCAG is translated from general guidelines into requirements that designers, developers, editors and testers can use in their daily work.

Start with the components that support the user journey

It is rarely necessary to specify everything at once. Start with the components that are used frequently or that users depend on to complete a task. On a typical corporate website, these will usually include:

• Main menu and mobile menu
• Links and buttons
• Form fields, checkboxes and error messages
• Search and filtering
• Dialog boxes and alerts
• Cards with an image, heading and link
• Tabs, accordions and other content that opens and closes

Prioritize components that appear on many pages. A single error in the main menu can affect the entire website, while an error in a rarely used campaign module has a more limited reach. This does not mean the latter error can be ignored, but it provides a sensible order for the work.

Translate WCAG into observable behavior

WCAG provides a necessary framework, but a development team needs requirements that can be observed and tested. “The component must comply with WCAG” is too general as an acceptance criterion. Instead, describe what the user should be able to do and what information assistive technologies should receive.

For a mobile menu, the acceptance criteria might be:

• The menu button can be reached and activated with a keyboard.
• It is visually clear when the menu button has focus.
• The screen reader communicates that the button opens a menu and whether the menu is open or closed.
• Focus moves in a logical order when the menu is open.
• The menu can be closed without a mouse.
• Focus returns to a sensible location after closing.

Wording like this makes the requirement understandable to several roles. It can be used in design reviews, development, manual testing and later regression tests.

Create an accessibility card for each component

An accessibility card is a brief specification that follows the component in the design system or task management tool. The card should be precise enough to test, but short enough that it is actually used.

1. Purpose and intended use

Describe what the component does and when it should be used. A link takes the user to another location. A button performs an action. If these elements are used interchangeably because they look alike, keyboard use and the screen reader experience can become unpredictable.

2. Keyboard behavior

Specify which elements should receive focus, the order they follow and which keys control the component. Do not make all visual elements focusable. Only interactive elements should normally be included in the tab order.

The focus indicator must be visible against the background and should work in all of the component’s states. It is not enough for it to be clear against a white background if it nearly disappears in a dark menu or over an image.

For complex components, the card should also describe what happens when the user presses Escape, the arrow keys or Enter. The keyboard interaction should follow a familiar and consistent model, not a local invention that users have to learn from scratch.

3. Semantics and screen reader support

Screen readers depend on structure and programmatic information. The component card should therefore specify which name, role and state should be communicated to the user.

Use actual headings, buttons, links, lists and form fields where an appropriate HTML element exists. Built-in semantics are generally more robust than building interactive elements from generic containers. Additional accessibility attributes should supplement the structure, not attempt to repair a fundamental error in the element type.

Also test the text that is actually read aloud. A button named “Read more” can be difficult to understand when the user navigates through a list of buttons without the rest of the page as visual context. “Read more about business insurance” provides a clearer target.

4. Contrast and visual states

Color requirements must be defined for more than ordinary body text. At WCAG Level AA, ordinary text should generally have a contrast ratio of at least 4.5 to 1. Large text can have a ratio of at least 3 to 1. Graphic elements that are necessary for understanding or using the interface, such as field borders and focus indicators, also need sufficient contrast against their surroundings.

Check all states: default, hover, focus, active, selected, disabled and error. A form error cannot be communicated solely by turning the field border red. Add text and, where appropriate, an icon, so the information does not depend on color vision.

Designers should specify approved combinations of text and background colors. This means editors do not have to guess whether light text can be placed over a particular brand color or image.

5. Scaling, text flow and small screens

The component must accommodate text being enlarged and taking up more space than expected. Fixed-height buttons, cards with truncated headings and menus that assume short words can break when users zoom in or the browser increases text size.

The acceptance criterion should be that essential content and functionality remain available without text overlapping, being clipped or requiring unnecessary horizontal scrolling. Test with real Norwegian content, not just short placeholder text.

Treat the form as a single task

Form fields can each be technically correct while the form as a whole is still difficult to complete. Component requirements must therefore be supplemented with a test of the overall flow.

• All fields have visible, programmatically associated labels.
• Required fields are clearly marked before submission.
• Help text explains the format and expectations before the user makes an error.
• The error message identifies the field and explains how to correct the error.
• Focus and error summaries help the user get to the right place after submission.
• Information that has already been entered does not disappear after a validation error.
• The confirmation after submission is clear, including to screen readers.

Avoid labels that appear only as placeholder text inside the field. The text may disappear when the user starts typing, making it harder to verify what the field is actually asking for.

Divide responsibility between roles

Accessibility often fails at the handover between disciplines. The designer has checked the contrast, but the developer lacks specifications for keyboard behaviour. The developer has created good semantics, but the editor publishes unclear link text and skips heading levels.

Therefore, assign responsibility explicitly:

• Design: Contrast, focus appearance, states, order and behaviour when scaling.
• Development: Semantic structure, keyboard control, focus management and information for assistive technologies.
• Content: Headings, link text, alternative text, instructions and understandable error messages.
• Testing: Holistic use with keyboard, screen reader, zoom and different screen sizes.
• Product owner: Prioritisation, acceptance criteria and decisions about what blocks publication.

Responsibility may be divided, but quality must be assessed as a whole. A component is not accessible if only the visual design or only the code is correct.

Use a consistent testing sequence

Automated tools can identify some errors, but they cannot determine whether the focus order is logical, whether the text is understandable or whether a dialog is practical to use. Combine automated checks with brief manual tests.

1. Review the structure: Check headings, landmarks, buttons, links and labels.
2. Use only the keyboard: Go through the component in both directions, activate functions and check focus.
3. Test with a screen reader: Listen for the name, role, state, instructions and changes after an action.
4. Check contrast: Measure text, icons, field borders, error states and focus indicators.
5. Enlarge the content: Look for clipping, overlap, hidden functionality and horizontal scrolling.
6. Test with real content: Use long headings, actual error messages and realistic alternatives.

Record the test result at component level. This allows the team to distinguish between a local content error and a system error affecting every page where the component is used.

Define what blocks publication

Not all deviations have the same consequences. A missing focus indicator in the main menu can block navigation for keyboard users. An imprecise alternative text for a decorative image has a different level of severity.

Create a simple prioritisation based on three questions:

1. Does the error prevent the user from completing an important task?
2. Is there a usable alternative route?
3. How many pages and user journeys are affected?

Errors that block navigation, purchases, login, applications or contact should normally stop publication. Less serious deviations must still be logged with an owner and deadline. Otherwise, “temporary” quickly becomes permanent.

Make the improvement permanent

The greatest benefit comes when a fix is built into the reusable component. If focus indication is improved in the design system’s button, every page using the button gets the same improvement. If the team only fixes one page, the problem will persist elsewhere.

A good component library should therefore show the approved appearance, expected keyboard behavior, screen reader information, content rules and test status. When these are part of the definition of done, accessibility becomes part of production rather than a cleanup task before launch.

Start with five critical components and write testable requirements for each. This is more valuable than a long, general checklist that no one owns. Once the method works, it can be extended to the rest of the website and used whenever the team designs, develops or changes a component.