How to Improve Accessibility in Legacy Web Applications
Improve an existing web application with a standards-led cycle: scope key flows, find barriers, fix shared patterns, and combine automated checks with human evaluation.
To improve accessibility in a legacy web application, assess representative pages and critical tasks against the applicable accessibility requirements, fix recurring barriers in shared components, and retest with both automated checks and human evaluation. Start with the application you have: a full rewrite is not a prerequisite.
Use WCAG 2.2 as the current W3C-recommended WCAG 2 technical reference, then confirm the legal, contract, and procurement requirements that apply to your organization and jurisdiction. A scanner can help find detectable issues, but it cannot establish that the application is accessible or that people can complete its tasks.
1. Set the scope and choose the standard
Legacy systems often have many routes, shared templates, old content, embedded tools, and third-party code. Make an inventory before deciding what to repair.
- List routes and page types, such as search results, forms, account pages, dashboards, and help content.
- Identify shared layouts and components: navigation, dialogs, form controls, tables, alerts, and menus.
- Write down the important user tasks, including the starting point, steps, and expected result.
- Record content types and embedded widgets, including documents, media, and vendor-provided interfaces.
- Mark which code your team can change and which issues require vendor escalation.
WCAG organizes requirements around four principles: content should be perceivable, operable, understandable, and robust. Its success criteria have Level A, AA, and AAA conformance levels. The appropriate target depends on the application and its obligations; do not treat one level as a universal legal requirement. W3C encourages using the latest WCAG 2 version and states that content conforming to WCAG 2.2 also conforms to 2.1 and 2.0. See the WCAG overview.
For U.S. federal work, consult the Revised Section 508 Standards and relevant agency guidance. Section508.gov provides guidance for software and websites, while its web-content overview describes WCAG 2.0 Level AA in that federal context. Those pages are not a universal rule for every organization or jurisdiction: verify the requirements that apply to your project. See Create Accessible Software & Websites and the Section 508 web content overview.
2. Evaluate real pages and tasks
Choose representative examples rather than scanning only the homepage. Include routes using shared components, older templates, long content, important forms, and third-party widgets. Walk through complete tasks, such as finding an item, submitting a form, or changing an account setting.
- Run automated checks. Use an accessibility checker to flag issues it can detect, such as missing accessible names or some structural problems. Keep the results as leads for review, not as a conformance verdict.
- Review manually. Examine content and interaction against relevant success criteria. Check whether controls are understandable and usable in the actual flow, including keyboard interaction and focus behavior.
- Test task completion with disabled people. Include people with disabilities in usability testing where possible. Their experience can reveal barriers that a rule-based scan does not describe.
- Record evidence. For each issue, capture the route or component, the task affected, the relevant criterion where known, the observed behavior, and the retest result.
W3C says success criteria are testable and describes conformance evaluation as a combination of automated testing and human evaluation. Its guidance recommends evaluators who understand how people with disabilities use the web and recommends usability testing that includes disabled people. See WCAG 2.1 and Understanding Conformance.
3. Prioritize by user impact and reach
There is no universal remediation queue for an application that has not been assessed. A practical starting strategy is to address barriers that prevent a core task and defects repeated by shared components. This is an implementation choice, not a priority order mandated by the cited standards.
| Question | How it helps set priority |
|---|---|
| Does this prevent a user from completing an important task? | Raises the urgency of investigating and repairing the barrier. |
| Does a shared component produce the issue on many routes? | A source-level repair may improve multiple affected pages consistently. |
| Is the affected code controlled by your team? | Clarifies whether to fix directly or document and escalate to a vendor. |
| Can the behavior be retested reliably? | Helps define a regression check and confirm the repair. |
Keep findings tied to actual routes, tasks, and observed behavior. Avoid assigning effort estimates or claiming broad impact before confirming how the application uses the component.
4. Repair shared patterns at their source
When an issue comes from a common template or component, repair that source where feasible instead of making inconsistent page-by-page adjustments. Preserve application behavior while making the interaction and content work for the users and technologies covered by your requirements.
- Fix shared navigation, form, dialog, table, alert, and menu patterns centrally when the defect is shared.
- For content-specific findings, correct the affected content and give publishers a repeatable way to avoid the same problem.
- For embedded or vendor-controlled features, document the user impact and evidence, then request a repair or identify an accessible alternative.
- Track the affected route or flow, criterion, change, owner, and retest result.
Do not infer that a code change resolves an issue solely because the checker no longer reports it. Revisit the task and verify the relevant behavior with human evaluation.
5. Retest and make accessibility ongoing work
After a repair, repeat automated checks and manually evaluate the affected task. When a shared component changes, review representative routes that use it. Include people with disabilities in usability testing as part of the evaluation process where possible.
Make this cycle part of ordinary product work: include accessibility questions in design and code review, content publishing, and regression planning. A one-time scan cannot promise that an application remains accessible as code and content change. Keep records of what was evaluated, what was repaired, and what still needs follow-up.
6. Use screenshots as visual review evidence
Screenshots can help teams compare visual states before and after a change, document a rendered page, or share a review artifact. They do not establish WCAG conformance: they cannot replace interaction checks, assistive technology use, or task-based evaluation with people.
For a local visual review, capture the same route and state before and after the repair, and record the viewport and relevant setup so reviewers can interpret the comparison. If a cookie banner or popup obscures the page, account for that state when reviewing the image. Keep screenshots as supporting evidence alongside the actual test steps and findings.
Or skip the browser setup
ScreenshotNeo is a website screenshot API and MCP server for developers. One GET request returns a PNG, JPEG, WebP, or PDF. The call below captures a page; it is visual documentation, not an accessibility evaluation.
See the ScreenshotNeo documentation for request options.
cURL
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpPython
import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)Node.js
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);ScreenshotNeo removes known consent banners, newsletter popups, and chat widgets before capture; each cleanup step can be turned off. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and response headers report the page verdict and billing status. Its MCP server provides screenshot, page-info, and PDF tools for AI agents. The free plan includes 1,000 screenshots per month without a card; paid plans start at $5 for 3,000 screenshots.
Sign up for 1,000 free screenshots a month, with no card required.
7. Troubleshooting common process problems
| Problem | Likely cause | What to do |
|---|---|---|
| The scanner reports no issues, but users still cannot complete a task. | Automated checks cover only issues they can detect and do not replace human evaluation. | Walk through the task manually, review the relevant criteria, and include disabled people in usability testing. |
| The same problem appears across many routes. | A shared component or template may be the source. | Trace the affected pages to their common source, repair it there where possible, and retest representative routes. |
| A finding appears only in one page or content item. | The problem may be specific to that page, content, or embedded widget. | Reproduce it in context, identify who controls the content or code, and assign the repair or vendor escalation. |
| A fix passes a scan but the flow still fails. | The scan result was treated as proof of correct behavior. | Retest the complete task with human evaluation and record the actual outcome. |
| Requirements are disputed across teams or vendors. | The organization may be mixing technical guidance with a specific legal, contract, or procurement obligation. | Identify the relevant jurisdiction and obligation, consult the responsible legal or procurement owner, and document the technical target separately. |
| A visual comparison looks different after a repair. | The capture state, viewport, loaded content, or overlays may differ. | Repeat the capture with consistent conditions and inspect the live interaction as well; an image alone cannot confirm accessibility. |
8. Performance, reliability, and cost considerations
Prioritize work according to the application’s actual task importance and the reach of shared code. Reusing a corrected shared pattern can avoid inconsistent fixes, but validate which pages use it before estimating the effect. No universal time, cost, or defect-reduction figure follows from the available guidance.
For reliable evaluation, retain a reproducible record of routes, task steps, test conditions, findings, owners, and retests. Repeat checks when shared code or content changes. Automated tools can support repeatable triage, but budget time for human evaluation and usability testing; a tool score is not a conformance guarantee.
FAQ
Do I need to replace the legacy application to make it accessible?
No. Start by assessing the existing routes and shared patterns, then repair barriers in place where feasible. The required changes depend on the system and its obligations.
Does a clean automated report prove WCAG conformance?
No. W3C describes evaluation as combining automated testing and human evaluation. A clean report is only one piece of evidence.
Should every application target WCAG 2.2 AA?
WCAG 2.2 is the current W3C-recommended WCAG 2 version, but the required target depends on the organization, jurisdiction, contracts, and procurement requirements. Confirm the applicable obligation.
Can screenshots be used for accessibility testing?
They can support visual review and documentation, but they cannot establish that controls work or that people can complete tasks. Pair them with interaction checks and human evaluation.
When should we involve disabled users?
Include people with disabilities in usability testing to evaluate whether real tasks work for them. W3C recommends this as part of accessibility evaluation.
