How to Build an Accessible WordPress Theme

Published: | No Comments

Reading Time: 8 minutes

WordCamp London 2019

In April 2019 I attended WordCamp London 2019 – a conference organised by, and for, the WordPress community.

During the conference I gave a presentation entitled ‘How to Build an Accessible WordPress Theme’. The aim of the presentation was to outline a series of ‘tips and tricks’ that developers can use to help them make their WordPress themes as accessible as possible.

Irrespective of whether they are building the theme for their own website, or a client’s website, an accessible theme will provide a good foundation that will allow as many users as possible to access the site.

This blog post contains a link to the slides I used during the conference, and I will soon be embedding a video of my presentation when it becomes available, and is captioned.

I’ve also included a list of points that I covered during the presentation, and some information about the Accessibility Checklist that I published to go along with the presentation.

The presentation slides

The slides are available on Slideshare.


Video of the presentation

When the video becomes available I will add it here.


Points I covered in the presentation

Why accessibility is important

Photo by Kari Leigh London

In this brief section I talked about two aspects – inclusion and legal implications.


The web should be for everybody – irrespective of people’s ability or disability. A more accessible website won’t exclude site visitors and should help to improve sales of products or services.

The legal aspect

The requirement for accessible websites is written into law in the UK, the US, and many other countries in Europe and around the world.

Whilst there is not much obvious legal action in the UK, the US has seen an explosion in lawsuits around web accessibility. One of the more high profile cases involved a successful prosecution of Dominos Pizza in early 2019.

So it makes sense to treat accessibility as a website requirement – even if your client doesn’t specifically ask for it.

When to think about accessibility

Many companies leave thinking about web accessibility to the last minute – often just before or after websites or apps go live.

This is a huge mistake as retro-fitting accessibility can be an expensive challenge and is not always possible within a website design.

So since accessibility is a project requirement it should be considered at all stages within the development of an accessible WordPress theme – from design, through build and testing.

It’s also worth making sure that content authors understand have an understanding of what they need to do.

Designing your accessible WordPress theme

During 2017 I delivered a presentation called ‘Designing for Accessibility’ to a number of WordCamps and WordPress meetup groups. I referred people to the slides for this Designing for Accessibility presentation and the video of the presentation.

So I only briefly covered a few points this time:

  • The importance of colour contrast.
  • Defining keyboard focus styles as well as hover styles for links and buttons.
  • Making links look like links
  • Problems with fully justified text


Building your accessible WordPress theme

This was the main part of the presentation so I covered subjects in more detail. I will be blogging about many of these topics in coming months and I will add the links here when they are published.

WordPress theme review guidelines

Even if you are not going to submit your theme to the WordPress Theme Repository it’s definitely worth following these guidelines – both for code quality and for the additional guidelines on accessibility. Links to these:

  • WordPress theme review coding standards
  • WordPress theme review accessibility guidelines

Semantic markup

It’s important to always use the correct semantic HTML elements when building pages/templates. Whilst sighted users may not appreciate this, users of screen readers and other assistive technologies rely greatly on the semantics.

Indicating page language

This is important for screen readers to ensure that they choose the correct language packs and pronounce content correctly to users. Meaning can be significantly impaired if this doesn’t happen.

Use the lang attribute on the <html> element to do this. You can find a list of language codes here.

Heading strategy

Headings within pages are important for screen reader users – to help them find sections they may be interested in reading. They can use the headings as in-page navigation.

Whilst most headings in a website will be put there by content authors, a WordPress theme will certainly specify some headings – the top level heading at the top of the main content, and headings for navigation and sidebar/widget areas.

I wrote a blog post on using headings correctly many years ago.


Landmarks are also being increasingly used by screen reader users to help them identify regions within web pages, and jump to those regions is required.

Using HTML5 sectioning elements such as <header>, <footer>, <main>, etc properly is enough to add landmarks to a page. The aria-label attribute can be used to provide more information to screen readers where necessary.


Some links are obviously placed in pages by content authors, but a WordPress theme will place many navigational and other links into pages and posts to help the user get around the site.

The main requirement here is that the link text should be informative enough on its own. This is because screen readers offer functionality whereby the links within a page can be presented as a list without the surrounding context.

So multiple ‘Read more’ links on a blog list page are not very useful. Also pagination links that are just numbers could do with more context.

‘Skip links’ at the top of pages which allow users to jump down directly to the main content are also very useful – especially for sighted keyboard-only users.

I wrote a blog post on skip links many years ago.


If logo images are used at the top of pages to link to the site’s home page, then the alternate text of the logo image should describe the destination – for example ‘Home page’.


Where icons are used as links or buttons, accessible text needs to be included for screen reader users.

Featured images

Setting appropriate alternate text for featured images is important for screen reader users. What appropriate means will depend on whether the image is a link to the blog post or not.

See my blog post on setting alternate text for featured images.

Text resizing

Some users with poor eyesight like to make text larger on a web page so that it is easier to read.

When building a theme it’s important to allow users on all browsers to do that without it breaking the design of the site, and impacting readability of the pages.

It’s also important to ensure that zooming on smartphones is not disabled.

Keyboard interaction

Many people who can’t, or choose not to, use a mouse or trackpad will rely on keyboard interaction to browse websites.

So it’s important that any actionable elements on pages must be able to get keyboard focus, and show visibly that they have focus. This includes dropdown navigation if present in a theme.

Forms in themes

Some WordPress themes may change the default way of presenting a comments form, or may add a contact form to a website.

It is important to ensure that all input fields have an appropriately marked up label for screen reader users, and that any validation error messages are also accessible by screen reader users.

I wrote a series of blog posts about forms and labels some time ago.

Other build points

  • Say “No” to title attributes
  • Avoid accesskey attributes
  • Avoid opening new windows without warning users – sighted and screen reader
  • Avoid tabindex values greater than zero
  • Avoid movement on pages, or allow users to stop it easily.


Problems when adding plugins

Even when you’ve built the most accessible WordPress theme, there is a risk that adding plugins to a site can seriously impact accessibility.

Although plugins need to go through an approval process before they are accepted in to the WordPress Plugin Repository, there is no consideration of their impact on the accessibility of any website that might use them

I outlined some examples where plugins can adversely affect accessibility:

  • Lightbox plugins where there was no warning that links would open overlays, and where keyboard focus wasn’t transferred into the overlays when they opened. All this could make life difficult for sighted keyboard users and screen reader users.
  • Form plugins where the labels were not attached to the input fields, and any error messages were difficult or impossible for screen reader users to access.
  • Carousel plugins where the movement cannot be stopped, or the interaction ‘breaks’ when accessed by keyboard only users.
  • Cookie warning plugins that put links and buttons and important privacy information at the very end of the page content – difficult to reach for sighted keyboard and screen reader users.

There are many other examples.

What to tell the content authors

Having built an accessible WordPress theme and activated it on a website, those who add or amed the content on the site can have a detrimental impact on the accessibility of the site. This is why WordPress themes from the repository can only be ever marked as ‘Accessibility ready’.

In this section I briefly covered:

  • The importance of using headings in content and keeping the heading hierarchy sensible.
  • The importance of adding links with meaningful link text – avoiding links that just say ‘click here’.
  • The importance of adding appropriate alternate text when adding images into content.
  • The importance of using list elements when presenting a list of items.

I mentioned that some CSS I’d created to help content authors when previewing their content has been turned into a WordPress plugin. See Content Author Accessibility Preview plugin. It’s also available on GitHub and open for suggestions and contributions.

The Accessibility Checklist

Right at the end of my presentation I announced details of an Accessibility Checklist I’d created and published on this site for anyone to use.

The checklist can help theme developers remember all the numerous things they need to think about during the design and build process. There is more in the checklist than I covered in this presentation.

At the end of the checklist I also have repeated the list of things that it’s worth telling your content authors and editors.

The Accessibility Checklist can be found here.

Any questions or comments?

If there are things you’re not sure about, or comments that you wish to make then please use the Comments section below. I’ll try and answer any queries.

Other posts on building accessible WordPress themes

Share this page (Links open new windows/tabs)

  • Share this page on LinkedIn (opens new window)
  • Share this page on Delicious (opens new window)
  • Share this page on Digg (opens new window)
  • Share this page on Posterous (opens new window)
  • Share this page on Reddit (opens new window)

There are no comments yet - would you like to leave one?

Like to leave a comment?

Please note: All comments are moderated before they will appear on this site.

Previous post:

Next post: