Altwise

Website redesign or platform move: an accessibility checklist (WordPress to Astro, Webflow and more)

An accessibility checklist for redesigning a small business website or moving it to a new platform: take a baseline, keep alt text, rebuild language, titles and skip links, check headings, menus, forms, redirects and embeds, AI prompt wording and a 5-minute check.

Lots of small business sites are being rebuilt right now: WordPress sites moved to fast static sites (Astro, Eleventy, Hugo) on free hosting, old themes swapped for new ones, or a whole site moved to Webflow, Squarespace, Wix or Shopify, often with an AI coding agent doing much of the work. A move is a good chance to fix old problems. It's also when things quietly disappear: alt text that didn't come across in the export, a skip link the old theme added for you, form labels from a plugin, page titles, and old links that now go to an error page. Nobody notices until a customer who uses a screen reader, a keyboard, voice control or a magnifier can't get through. Here's a checklist for before, during and after the move.

1. Take a baseline before you touch anything

Before the move, write down the pages that matter and the main task on each (book, buy, call, ask for a quote), run an automated check on them, and try each task with only a keyboard. Keep the results with a date. After the move you run the same checks and compare, so you know whether the new site is better or worse, not just different. Web designers do the same at handoff: see the client handoff checklist.

old URL,new URL,page title,main task,alt text ok,keyboard ok,notes
/,/,Riverside Bakery | Fresh bread in Tulsa,order a cake,yes,yes,
/order-cakes/,/order,Order a custom cake | Riverside Bakery,send order form,no,no,date picker mouse-only
/about-us/,/about,About us | Riverside Bakery,read,yes,yes,
# example pages and business, use your own

2. Bring the alt text with you

Exports and content migrations often drop image descriptions, or fill them with file names like "IMG_2041.jpg". WordPress keeps alt text in the media library, and not every export or importer copies it into the new pages. Check every image after the move: informative images need a short description, decorative ones need an empty alt="". (WCAG 1.1.1) See alt text examples.

# Run in your built site folder (for example dist/ or public/).
# Images with no alt attribute at all:
grep -rhoE '<img[^>]*>' dist | grep -v 'alt=' | sort | uniq

# Markdown images with empty descriptions (check each one is truly decorative):
grep -rn '!\[\](' src/content

# Alt text that is just a file name:
grep -rhoiE 'alt="[^"]*\.(jpe?g|png|webp|gif)"' dist | sort | uniq

These are quick searches, not a full check: they won't catch alt text that is present but unhelpful, such as "image" or "photo".

3. Rebuild the page shell: language, titles, skip link, landmarks

Old themes often added a skip link, a page language and landmarks for you. A new hand-built or AI-built layout only has what you put in it. Set the page language once in the layout, give every page its own title, add a skip link, and use header, nav, main and footer. (WCAG 3.1.1, WCAG 2.4.2, WCAG 2.4.1, WCAG 1.3.1)

---
// src/layouts/Base.astro (Astro example; other tools use the same HTML)
const { title } = Astro.props;
---
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>{title} | Riverside Bakery</title>
  </head>
  <body>
    <a class="skip" href="#main">Skip to content</a>
    <header>
      <nav aria-label="Main">...</nav>
    </header>
    <main id="main" tabindex="-1"><slot /></main>
    <footer>...</footer>
  </body>
</html>
<!-- example business name, use your own -->

Don't block zoom in the viewport tag (no maximum-scale=1 or user-scalable=no). See page titles and language and skip links and focus outlines.

4. Check the headings came across as headings

Page builders often style big text without making it a heading, or make every bold line an H2. After a move, each page should have one H1 that says what the page is, and H2s and H3s that follow the real sections. (WCAG 1.3.1, WCAG 2.4.6) See heading structure.

# List each page's headings in order from the built site (example; adjust the folder):
for f in $(find dist -name '*.html'); do
  echo "== $f"; grep -oE '<h[1-6][^>]*>[^<]*' "$f" | sed -E 's/<(h[1-6])[^>]*>/\1: /'
done

5. Menus, focus outlines and colours in the new design

A new design brings a new menu, new colours and new button styles. Check that the mobile menu button is a real button with a name and an open/closed state, that the menu sits in the same place on every page, that you can always see where keyboard focus is, and that text and buttons still have enough contrast. (WCAG 4.1.2, WCAG 3.2.3, WCAG 2.4.7, WCAG 1.4.3)

<button type="button" class="menu-btn" aria-expanded="false" aria-controls="site-menu">Menu</button>
<ul id="site-menu" hidden>...</ul>
<script>
  const btn = document.querySelector('.menu-btn');
  const menu = document.getElementById('site-menu');
  btn.addEventListener('click', () => {
    const open = btn.getAttribute('aria-expanded') === 'true';
    btn.setAttribute('aria-expanded', String(!open));
    menu.hidden = open;
  });
</script>
<style>
  a:focus-visible, button:focus-visible { outline: 3px solid #1d4ed8; outline-offset: 2px; }
</style>

Use the free contrast checker on the new colours, and see accessible menus.

6. Forms that used to come from a plugin

Moving off WordPress often means replacing a form plugin with a form service, a serverless function or a builder's own form. Whatever you use, each field needs a visible label, errors need to be explained in words next to the field, and the "thanks, we got it" message needs to be announced to screen reader users. (WCAG 3.3.2, WCAG 3.3.1, WCAG 4.1.3)

<form action="/api/contact" method="post" novalidate>
  <label for="name">Your name</label>
  <input id="name" name="name" autocomplete="name" required>
  <label for="email">Email</label>
  <input id="email" name="email" type="email" autocomplete="email" required aria-describedby="email-err">
  <p id="email-err" class="err" hidden>Enter an email like [email protected]</p>
  <button type="submit">Send message</button>
  <p role="status" id="form-status"></p>
</form>
<!-- example endpoint, use your own -->

See accessible contact forms and embedded form builders.

7. Redirect old links, and keep a second way to find pages

Old links in emails, Google results, bookmarks and other sites will point to your old addresses. Redirect each old URL to its new page so people don't land on an error page. Many static sites also drop the old site search. If you remove it, keep a clear menu plus a site map page or search, so people have more than one way to find a page. (WCAG 2.4.5)

# _redirects (one rule per line: old path, new path, status code)
/order-cakes/   /order    301
/about-us/      /about    301
/blog/2019/*    /blog/:splat  301
# example paths, use your own

Hosts such as Cloudflare Pages read a _redirects file in this format. Other hosts and builders have their own redirect settings, so check your host's documentation. Make your error page helpful too: see 404 and maintenance pages and site search.

8. Embeds, videos and PDFs

Maps, booking widgets, videos and social feeds usually get pasted in again by hand. Give each embedded frame a title that says what it is, keep captions on videos, and check that any PDF menus or forms you moved still have their text and tags (or turn them into web pages). (WCAG 4.1.2, WCAG 1.2.2)

<iframe src="https://www.example.com/booking-widget" title="Book a table" loading="lazy"></iframe>
<!-- example widget URL, use your own -->

See PDFs and menus and video captions.

9. If an AI agent does the move

AI coding agents can move content quickly, but they copy what they see and rarely add what the old theme did quietly. Add something like this to your prompt (example wording): "Keep every image's alt text from the old site and flag any image without one. Set lang on the html element. Give every page a unique title. Add a skip link and header, nav, main and footer landmarks. Keep headings in order with one H1 per page. Every form field has a visible label, errors in words and an announced success message. Keep visible focus outlines. Write a redirect for every old URL." Then test the result yourself. See checking an AI-built website.

Platform notes

Common mistakes

A 5-minute check you can do today

  1. Open the new home page and press Tab once. Do you see a "Skip to content" link?
  2. Keep pressing Tab through the menu and one main task (booking, buying or the contact form). Can you always see where you are, and can you finish it?
  3. Open an old link from an email or a search result. Does it land on the right new page?
  4. Right-click an important photo and inspect it, or use our alt text checker. Is the description still there?
  5. Zoom to 200% on a phone-width window. Can you read everything without scrolling sideways? (WCAG 1.4.10)

What a scan can and can't check here

An automated scan finds only part of the barriers on the pages it visits. Run on the same pages before and after a move, it can show changes in missing alt text, missing page language, empty buttons, unlabelled form fields, low contrast and missing frame titles. It can't tell whether alt text is accurate, whether the new menu and forms work with a keyboard, whether old links redirect, or whether headings match the real sections, which is why the 5-minute check matters.

Moving several client sites? The agency 5-pack gives you five white-label reports to use within 12 months.

Related: client handoff checklist for web designers, WordPress fixes, checking an AI-built website, 404 and maintenance pages.

This is general technical guidance, not legal advice, and it doesn't certify compliance with the ADA or any law, or protect against claims.

Want the fixes written for you?

Start with a free homepage snapshot. The $149 Fix-Pack scans up to 10 pages and gives copy-paste fixes for your platform within 48 hours, with a 14-day refund promise. See a sample report first.

This is general technical guidance, not legal advice, and it does not certify compliance with the ADA or any law.

Related guides

All guides

This guide is general technical information, not legal advice. Following it does not certify ADA or any legal compliance. Automated checks find only part of accessibility barriers.

Check your own site, then decide

  1. Free homepage snapshot. Your top 3 issues in about a minute. No signup, no card.
  2. $149 Fix-Pack, if you want the full list. Up to 10 pages scanned, issues ranked by impact, copy-paste fixes for your platform, delivered within 48 hours, plus one re-scan after you apply them.

Get my free snapshot Order the Fix-Pack – $149

14-day refund promise. See a sample report first. A technical report, not legal advice; automated checks find only part of accessibility barriers.