SAYLOR Turn accessibility findings into specific fixes for semantics, keyboard use, focus, labels, contrast, motion, errors, and assistive technology.
The result you're building
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.
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
| Evidence | Likely layer | First decisive check | What the result means |
|---|---|---|---|
| Cannot reach/activate control | Keyboard/semantics | Tab/Shift-Tab/Enter/Space and DOM role | Use native control, logical order, visible focus. |
| Screen reader announces vague/no name | Name/label | Accessibility tree and label association | Add programmatic label/name without duplicating noise. |
| Modal loses/traps focus incorrectly | Focus management | Open/close keyboard sequence | Move focus in, contain appropriately, restore trigger, support Escape. |
| Error visible but not announced | Forms/status | Submit with assistive tech | Associate field error, summary/focus/status, 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.
Step 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.
Step 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.
Step 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.
Step 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.
Step 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.
Step 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
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.
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 semantic fix | Rule/tool interpretation or new detectable issue. | Inspect user behavior/criterion and tool details; do not chase score blindly. |
| Keyboard works; screen reader confusing | Name/state/live region semantics incomplete. | Inspect accessibility tree and actual announcement. |
| Focus disappears | CSS clips/overrides outline or element removed. | Use durable focus-visible style and manage DOM update. |
| Fix works one page | Shared component/template not corrected. | Patch source component and add regression. |
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