30 Prompts for Accessibility Fixes in Front-End Code
Brackenford Libraries takes about 9,400 event bookings a year across 12 branches, and when the booking form was rebuilt in React the focus ring disappeared in the first sprint. Nobody noticed until a keyboard user reached the branch picker and could not tell where they were. The 30 prompts below work through that form in the order a screen reader meets it: focus path, names, contrast, errors, then audit. Each is written for a specific fix, not a general review. For the wider review habit, see our code review prompts.
Fix Order Before Snippet Choice
Start with the keyboard path, because a component that cannot be reached cannot be labelled. Then names, then visual state, then errors. Most React accessibility bugs in this form came from a wrapper div that swallowed the focus, not from a missing ARIA attribute. Read the rendered DOM, not the component source, before you ask for a fix.
The Fix List, Grouped by Element
Fix Set 1: Keyboard Path and Focus
- Maps the tab order of the booking form against the visual order.
Here is the rendered DOM of a library event booking form. List the tab order a keyboard user will experience, compare it with the visual order, and flag every element that is focusable but should not be, or reachable only by mouse. - Finds the wrapper that steals focus from the branch picker.
This React component renders a div with tabIndex set to -1 around a select. Explain what that does to keyboard users, show the corrected JSX, and state whether the div should exist at all. - Fixes a focus trap in the date picker modal.
The date picker opens in a modal and Tab escapes to the page behind it. Write the focus management: initial focus target, the Tab cycle inside the dialog, Escape handling, and where focus returns on close. React with refs, no library. - Restores a visible focus indicator that survives the design system reset.
The CSS reset removes outlines and the focus style was never restored. Write a focus-visible rule for buttons, links, inputs and the branch cards, with a 3:1 contrast against both the page and the component. Show the CSS only. - Adds a skip link that lands somewhere useful.
Add a skip link to the booking page that jumps past the 12-branch navigation to the form heading. Write the markup, the visually hidden style, and the visible state on focus. Confirm the target is focusable. - Makes the branch list operable with arrow keys.
A custom branch picker uses divs with click handlers. Rewrite it as a listbox with roving tabindex: arrows move, Home and End jump, Enter selects, and the active option is announced. Show the React code and the required ARIA.
Fix Set 2: Names, Labels and Structure
- Gives every input a programmatic label instead of a placeholder.
This form uses placeholders as labels. Rewrite each field with a visible label element tied by htmlFor and id, keep the hint text, and add autocomplete tokens for name, email and telephone. Output the JSX. - Groups the party size radios with a fieldset and legend.
The party size radios sit in a plain div. Rewrite them with fieldset and legend, keep the error slot, and explain in two sentences what a screen reader announces before and after the change. - Writes accessible names for icon-only controls.
These three icon buttons have no text: close, next month, previous month. Give each an accessible name, mark decorative icons as hidden, and show the JSX. Flag any name that would change with context. - Connects hint and error text with aria-describedby.
For this email field, wire the hint and the error message with aria-describedby, set aria-invalid only when an error exists, and make sure the ids are unique when the form renders twice on one page. - Fixes heading order across the booking flow.
Here is the heading outline for the three-step booking flow. Correct the levels so there is one h1, each step is an h2, and no level is skipped. Show the before and after outline only. - Replaces a div-based modal with dialog semantics.
Rewrite this div modal using the native dialog element: showModal on open, close on Escape, focus first field, return focus to the trigger. List the three behaviours the native element gives you for free.
Fix Set 3: Contrast and Visual State
- Checks the disabled branch options for contrast and meaning.
These disabled branch options sit at 2.1 to 1 contrast and rely on grey alone to mean unavailable. Give a compliant colour pair, add a text or icon cue, and explain why disabled controls still need to be readable. - Tests the focus ring against every background it lands on.
The focus ring is 2px in the brand blue, which is used on the submit button. Propose a two-tone ring that works on white, grey and the blue button, with measured contrast ratios. CSS only. - Stops using colour alone to signal a required field.
The required asterisk is red and the label is red too. Rewrite the field so required status is in text, keep the visual style, and confirm what a screen reader announces. Show the JSX and a one-line CSS note. - Fixes placeholder contrast without making it look like a value.
The placeholder is 1.9 to 1 against white. Raise it to at least 4.5 to 1, keep it visually distinct from entered text, and confirm it is not the only label. Give the hex values and the ratio. - Checks the dark theme for the same failures.
Compare these light and dark theme tokens for text, border, focus and error states. List every pair below 4.5 to 1 for text or 3 to 1 for UI boundaries, and give a corrected value for each. - Makes the loading state visible without a spinner alone.
The submit button shows a spinner and the label disappears. Rewrite it so the label stays, a busy state is announced, and the button cannot be double submitted. Show the JSX and the aria attributes.
Fix Set 4: Errors and Validation
- Rewrites error messages so they say what to do next.
Rewrite these five error strings so each names the field, the problem and the fix in one sentence. No "invalid input", no codes, no blame. Keep each under 90 characters. - Builds the error summary at the top of the form.
Write an error summary for a failed booking submit: one heading, a list of errors as links to each field, and focus moved to the summary on submit. Show the JSX and the focus call. - Times validation so it does not fire on every keystroke.
This email field validates on change and shouts at the user after one character. Move validation to blur, keep revalidation on change only after the first error, and explain the rule in two sentences. - Announces a server error without moving focus unexpectedly.
The booking POST fails with a 500. Write the handling: a live region message, the retry path, and the reference number shown to the user. Do not move focus away from the submit button. - Handles a field that becomes irrelevant when a branch is closed.
When a branch is closed, the date field is hidden. Write the logic so hidden fields are removed from the tab order, their errors are cleared, and the summary does not link to something invisible. - Confirms success in a way a screen reader user will hear.
After a successful booking, the page swaps to a confirmation panel. Write the focus move, the heading, the live region announcement, and the one detail the user needs to keep. Keep it to one short paragraph.
Fix Set 5: Audit, Test and Handoff
- Writes a keyboard-only test script for the whole booking flow.
Write a 12-step keyboard-only test script for booking an event: from the skip link to the confirmation. Each step names the key pressed, the expected focus target, and the pass condition. No mouse allowed. - Writes a screen reader script with expected announcements.
Write a 10-step screen reader test for the branch picker and party size group. For each step give the action, what should be announced, and the most likely failure. Note where VoiceOver and NVDA differ. - Triages an automated scan into real bugs and noise.
Here are 34 axe results for the booking form. Group them into must-fix, needs-a-human, and false positive. For each must-fix, give the file and the likely cause in one line. - Writes the pull request checklist for this form only.
Write a 10-item accessibility checklist for a pull request touching the event booking form. Each item must be checkable in under two minutes and tied to a specific element, not a general principle. - Builds the ticket an engineer can pick up without a meeting.
Turn this audit finding into a ticket: title, affected component, user impact, steps to reproduce with keys, expected behaviour, suggested fix, and a test to prove it. Under 180 words. - Keeps the fixes from regressing on the next sprint.
Turn these 12 fixes into a regression list for the booking form. For each, give the check, the tool, and whether it can run in CI. Mark the four that need a manual pass before release.
A Review Pass That Fits a Sprint
Run the keyboard script on Monday, the screen reader script on Wednesday, and the automated scan before the pull request merges. Three passes, three different failure types, none of them longer than 20 minutes on a form this size. Log every finding with the component name so the next sprint does not reopen the same dialog. If a fix cannot be tested with a keyboard in under a minute, it is probably too clever for a booking form.
Bonus: What Automated Scans Will Not Catch
Focus order. A scan cannot tell you that Tab jumps from the branch picker to the submit button. Error timing. No tool knows that a message fires after one keystroke. Reading order in the DOM. Visual layout and source order diverge constantly in a two-column form. Usable names. A button can pass every rule and still be announced as “button”. Test with a real screen reader, and pair these fixes with the patterns in our error handling prompt guide so the failure path is written as carefully as the happy one.
Sources & Notes
Brackenford Libraries, its 12 branches and 9,400 annual bookings are fictional. Code samples assume React 18 with a modern browser and no component library; adapt the focus management if your dialog comes from a library that already handles it. WCAG 2.2 AA is the baseline referenced here, and contrast ratios were checked against the 4.5 to 1 text and 3 to 1 non-text thresholds. Automated tools catch roughly a third of issues, so treat a clean scan as the start of testing, not the end.
