At WordCamp Europe Torino ’24, Joe Dolson asked Rian Rietveld to review the documentation about accessibility on the WordPress.org website. What she found was that the information was hard to find, scattered all around the place, with duplicated and incomplete information.
At WordCamp Basel ’25, we worked out a plan to improve the documentation for WordPress’ accessibility.
Last year we centralized, reviewed and updated this documentation, creating one source of truth: The WP Accessibility Knowledge Base on wpaccessibility.org.
The goal is for WordPress community to have consistant, easy to find, reliable, and up-to-date information about what is important to create sites, blocks, themes, admin functions, or plugins everyone can use.
Thank you Kinsta, Human Made, GoDaddy and Aiwos for sponsoring Joe and Rian to work on this documentation.
Last year: Reorganize, review, update and extend
Accessibility team Handbook
The Accessibility Team Handbook on WordPress.org now only contains information about the accessibility team, the WordPress accessibility coding standard and about how to contribute.
The advantage of updating everything is that you get new insights. Instead of 7 working groups, the team now has 3 focus groups: The accessibility of WordPress, The accessibility-ready program and Documentation and education. With each group its own contact person.
Theme accessibility-ready guidelines
Amber Hinds and Joe Dolson updated the theme accessibility-ready guidelines. These new requirements aare now published in the WP Accessibility Knowledge Base.
WP Accessibility Knowledge Base
All information about accessibility itself, originally in the handbook, has been moved to the WP Accessibility Knowledge Base on wpaccessibility.org. The content is written in markdown and lives on the GitHub pages of the repository wp-a11y-docs, owned by the accessibility team. Many people helped getting this documentation out there, thank you!
The WP Accessibility Knowledge Base now contains info about:
- Start with accessibility, with an introduction to WCAG, 7 quick wins, the business case, how to get training and eduction and also our opinion about overlays.
- Accessibility-ready program, with the theme requirements, testing process and how to find accessibility-ready themes.
- Standards and best practice, for content & images, design & user experience, frontend code, web forms, legislation and how to document accessibility.
- Test for accessibility, about automated testing, checks for content, design and frontend, WordPress plugins for accessibility testing, how to test with a keyboard and with a screen reader and links to complete WCAG checklists.
- WordPress and Accessibility, about WordPress, WCAG and compliance, links to the accessibility team and team handbook and an overview of plugins that help support accessibility.
We are still in the process of updating and extending the content, but much of it is done or almost done.
Work in process
The Accessibility Handbook will move to a GitHub repository on the WordPress organisation later this year.
When all the documentation in the Knowledge Base has been reviewed and updated, the relevant documentation will be copied to a new section called “Accessibility” on developer.wordpress.org. So, in fact, we return the updated info to wordpress.org, where it belongs and also will be easier to find.
After this, all the old documentation about accessibility on make.wordpress.org needs to be updated to point to this new accessibility section.
Proper documentation is an ongoing job, we need to keep updating, reviewing and extending. The web, WordPress itself, support for HTML, CSS and ARIA, assistive technology, the way people use the web, the use of AI, it all changes. It’s a work in progess.
How can you help
Read what’s there, on wpaccessibility.org, and give us feedback. We are writing this for you, please let us know if you can understand and use it.
WordCamps are the best. Last WordCamp Europe, at the contributor day, a table full of people reviewed the Knowledge Base and came back with useful feedback. When you are at a WordCamp contributor day, please join the accessibility table to give feedback on wpaccessibility.org.
Request content. Do you need information about a specific topic? Are there discussions on how to handle a specific topic or component? Ask us for help and documentation, resources, or what else you need. Open an issue in the wp-a11y-docs GitHub repository with your request or ping @rianrietveld in WordPress Slack.
Are you a core developer? Help us with examples, or point us to good examples to add to the docs.
WordPress agencies: consider sponsoring Joe and Rian. Or give your developers, designers or content creators time to work on the documentation.
But most off all: you can help us by using the documentation for your work, let’s make WordPress usable for everyone.