Accessibility.md file: Building accessibility checks into how government websites are developed

The problem

Government teams building websites and digital services manage many competing priorities. Developers working on these services may not have clear, standardised instructions on what accessibility rules to follow or how to test for them as part of their regular workflow. When accessibility guidance exists but is not built into the tools developers use day to day, it can be difficult to apply consistently across every project. The result is that accessibility problems sometimes only come to light after a website or service is already live, when they are more time-consuming to address and may already be affecting the people using the service.

This challenge has grown as the way software is built has changed. Today, code is written by two groups: people and AI coding assistants — tools like GitHub Copilot, Claude, and others that automatically suggest or generate code for developers. These AI assistants are increasingly influential in what ends up in a finished product, but they do not automatically know what a project's accessibility standards are. Without explicit instructions, they can generate code that introduces accessibility problems — for example, producing a form that a screen reader cannot navigate, or an image without a text description. This year’s WebAim Million report found that web accessibility got worse for the first time in six years. At present, most projects do not have a single, reliable place where either a human developer or an AI assistant can look up what the accessibility requirements are.

The solution

The Accessibility.md File is a set of documentation — written rules, examples, and templates — that gives a project a single, reliable place where its accessibility standards are defined. It follows the direction of an AGENTS.md file and is similar to a Claude Skill. Human-readable Markdown files.

It sets out what developers and their AI companions need to do to make a website or digital service accessible, highlighting key patterns which are key to the project, and how accessibility should be maintained as the project develops.

The file is designed to serve three audiences. For users of a website or service, it provides transparency: what accessibility standards the project meets, what known gaps exist, and how to report barriers. For developers and teams, it standardises how accessibility work is managed — how issues are categorised, what checks need to pass before code is published, and how accessibility problems are prioritised alongside other work. For agentic AI — where AI systems autonomously write, modify, or review code with minimal human oversight — it provides explicit instructions, so that these tools follow the project's accessibility standards.

For teams building or updating websites, it is already standard practice to use what is known as a continuous integration and continuous deployment (CI/CD) pipeline — an automated process that runs a series of checks every time a developer submits new code, catching errors and inconsistencies before changes go live. Accessibility checks can be part of this pipeline, but in practice they have often been overlooked.

The ACCESSIBILITY.md file helps address this by providing guidance, templates, and example code that teams can use to build accessibility testing into their existing pipeline. It does not enforce standards on its own — it is documentation that describes what checks to implement and how to set them up. The implementation itself is still done by developers or by agentic AI tools following the file's instructions.

The aim is to make the rules clear and specific enough that developers can act on them without needing to be accessibility specialists, and to automate the enforcement of those rules so they are applied consistently every time code is updated. The file addresses a gap that many government teams face: accessibility guidance may exist within an organisation, but if it sits in a separate document rather than being embedded in the tools developers use every day, it is easy to overlook. It should also be updated to align with the Design System and coding best practices of the organisation.

This gap has grown as AI coding assistants have become more widely used in development — without explicit instructions about how to build to WCAG and accessibility best practices, it will tend toward the mean. Most web pages are not very accessible today.

The Accessibility.md File is still in its early stages. The framework is open-source and publicly available for any team to adopt and test. What the documentation should contain, how it should be structured, and what steps will be taken to ensure measurably better accessibility outcomes. These are some of the things still being explored through ongoing feedback from practitioners.