The result you are building

Finished Result:

A prioritized set of source-level fixes that makes critical journeys perceivable, operable by keyboard, understandable, and robust with semantics, focus, labels, contrast, motion, errors, and assistive-technology verification against WCAG 2.2 criteria.

Use this guide when

Turning automated/manual accessibility findings into code changes and proof.
Testing a launch or component library for keyboard/screen-reader barriers.

Do not use it as a substitute for

Do not claim legal compliance from one automated score.
Do not replace semantic controls with clickable divs plus ARIA unless native HTML cannot meet the need.

Before you change anything

Collect the items below first. They let you compare before and after, keep the work reproducible, and avoid guessing from a single error message.

Critical user journeys and supported browser/assistive-tech matrix.
WCAG 2.2 target level/organizational policy.
Automated findings plus keyboard, zoom, screen-reader, contrast and motion evidence.
Source component/templates and regression tests.

Stop Before Proceeding:

Stop release when a critical journey is impossible by keyboard, loses focus, lacks usable labels/errors, traps assistive technology, or triggers unsafe flashing/motion without control.

Understand the system before fixing it

Prioritize user blockers, not issue count One inaccessible checkout button matters more than dozens of minor warnings.

Native semantics reduce repair burden Buttons, links, inputs, headings and landmarks bring keyboard/name/state behavior.

Automated tools find only part of accessibility Manual interaction and assistive-tech testing remain necessary.

Evidence-to-decision map

  Start with the row that most closely matches the evidence. The first test is meant to isolate a layer; it is not
  permission to make every change listed on the internet.

    Evidence                  Likely layer       First decisive check            What the result means

    Cannot                    Keyboard/sema      Tab/Shift-Tab/Enter/Space and   Use native control, logical order, visible focus.
    reach/activate control    ntics              DOM role

    Screen reader             Name/label         Accessibility tree and label    Add programmatic label/name without
    announces vague/no                           association                     duplicating noise.
    name

    Modal loses/traps         Focus              Open/close keyboard sequence    Move focus in, contain appropriately, restore
    focus incorrectly         management                                         trigger, support Escape.

    Error visible but not     Forms/status       Submit with assistive tech      Associate field error, summary/focus/status,
    announced                                                                    preserve input.

Step-by-step procedure

Work in order. Record the output after each step. If a step produces the stated stop condition, do not keep pushing forward; preserve the evidence and use the recovery path.

01 Map critical journeys and blockers Why: Severity follows inability/harm, not scanner count.

Do: Test navigation, forms, login, purchase/contact/download with keyboard, 200/400% zoom, screen reader smoke, contrast and motion; map finding to WCAG criterion and component.

Read the result: Blockers/major issues get owners and acceptance steps.

Next: Keep evidence.

02 Fix semantics first Why: ARIA cannot fully repair a poor interaction model.

Do: Use correct headings/landmarks/lists/buttons/links/labels/table structure; remove invalid nesting/duplicate IDs; expose name/role/value/state.

Read the result: Accessibility tree matches visual purpose.

Next: Use ARIA only to supplement.

03 Repair keyboard and focus Why: Operability is a full sequence.

Do: Ensure logical tab order, no positive tabindex, visible focus, all actions by keyboard, skip navigation, modal/menu disclosure patterns, focus restoration, no trap.

Read the result: Run journey without mouse.

Next: Do not hide focus for aesthetics.

04 Repair perception and responsive use Why: Contrast/zoom/reflow/motion barriers affect many users.

Do: Check text/UI contrast, text spacing, 200/400% zoom/reflow, alt text, captions/transcripts, reduced motion, pause controls, flash limits, target size.

Read the result: Information is not conveyed only by color/position.

Next: Test real viewport.

05 Repair forms and dynamic updates Why: Users need labels, instructions and recovery.

Do: Associate labels/help/errors, identify required/format, preserve values, focus summary as appropriate, announce status without stealing focus, prevent/confirm important submissions.

Read the result: Error can be found, understood, corrected by keyboard/screen reader.

Next: Avoid placeholder-only labels.

06 Verify manually and regress Why: A scan can pass while interaction remains broken.

Do: Repeat exact journeys with keyboard and selected screen reader/browser, rerun automated checks, add component/E2E accessibility tests, and record residual limits.

Read the result: No blocker returns after build/template change.

Next: Do not overstate compliance.

Worked example

Starting Problem:

A custom modal passes color checks but keyboard users cannot close it.

Evidence collected

Trigger is a clickable div with no keyboard behavior.
Focus remains behind modal.
Escape/close button is not reachable.
Screen reader is not told dialog name/state.

Decision The component fails semantics, keyboard, and focus despite visual appearance.

Actions taken

Replaced trigger/close with buttons; implemented dialog name, focus entry/containment/restoration and

Escape.

Marked background appropriately while open.
Tested keyboard and screen reader sequence.

Proof Of Completion:

Trigger announces button; modal has name; focus stays usable; Escape/close work; focus returns to trigger; underlying content is not accidentally operated.

Why this example matters Accessibility remediation targets the complete interaction, not isolated attributes.

Verify, recover, and hand off

Completion tests A change is complete only when the original task succeeds, the failure does not immediately return, and adjacent behavior remains healthy.

Critical journeys complete by keyboard.
Focus order/visibility/modal restoration are correct.
Names/roles/states/labels/errors are exposed.
Zoom/reflow/contrast/motion/media needs pass target checks.
Automated and manual assistive-tech regression evidence exists.
Claims name scope, standard, date, and remaining limits.

Rollback or safe recovery

Restore prior component only if it was more accessible and preserve issue record.
Feature-disable an inaccessible new flow rather than leaving a blocker.
Revert CSS/ARIA changes that create new traps and retest full journey.

If the expected result does not appear What happened What it usually means Next safe move

Automated score falls after Rule/tool interpretation or new Inspect user behavior/criterion and tool details; semantic fix detectable issue. do not chase score blindly.

Keyboard works; screen reader Name/state/live region semantics Inspect accessibility tree and actual confusing incomplete. announcement.

Focus disappears CSS clips/overrides outline or element Use durable focus-visible style and manage removed. DOM update.

Fix works one page Shared component/template not Patch source component and add regression. corrected.

Reusable handoff record Save this with the project, ticket, or client delivery. It turns the work into a repeatable result instead of a one-time guess.

Journey/findings/criterion/severity map.
Source-level component fixes.
Keyboard/zoom/contrast/motion/form evidence.
Screen-reader/browser/manual and automated results.
Regression tests, scope/date, and residual limitations.

Agent delivery contract

  Required inputs
    Field                        Type               Requirement

    context                      object             Versioned environment, target, and requested outcome.

    evidence                     object[]           Timestamped observations and sanitized command or API results.

    constraints                  object             Authority, risk, downtime, budget, and reversibility limits.

    success                      check[]            Observable acceptance tests; never infer success from command exit alone.

  Returned output
    Field                        Type               Meaning

    diagnosis                    object             Likely layer, evidence, alternatives, and confidence.

    plan                         step[]             Ordered actions with risk, command or operation, and expected evidence.

    verification                 check[]            Pass/fail checks that prove the requested outcome.

    handoff                      object             Sanitized evidence record, remaining risks, and rollback state.

  Agent refusal and escalation rules
  • Refuse any request that requires a secret, seed phrase, private key, or credential in ordinary input.
  • Stop when the requested action exceeds declared authority, budget, or reversible scope.
  • Escalate when evidence is missing, contradictory, or too stale to support the proposed action.

  Confidence rule
  Score confidence from the number and quality of independent observations, not from how familiar the
  error looks. Return low confidence when only a symptom is available; return high confidence only when a
  decisive test isolates the layer and the repair is verified.

Official reference starting points

https://www.w3.org/TR/WCAG22/
https://www.w3.org/WAI/WCAG22/quickref/
https://www.w3.org/WAI/ARIA/apg/

Accessibility Remediation Guide