Accessibility is often discussed in the context of application UI, but the project itself also needs to communicate how accessible it is and where users can report accessibility problems.
For open-source projects, internal tools, documentation repositories, and public software projects, an accessibility statement can give users a clear place to understand the project's accessibility approach.
A GitHub repository is often the first place developers look for information about a project. Adding accessibility information to the repository makes that information easier to discover and gives contributors a defined process for reporting accessibility issues.
An accessibility statement does not make an application accessible by itself. It is part of a broader accessibility process that includes testing, documentation, issue management, and ongoing improvements.
This article explains what an accessibility statement should contain, where it can be placed in a GitHub repository, and how development teams can maintain it as the project changes.
What Is an Accessibility Statement?
An accessibility statement is a document that explains the accessibility status and approach of a software project.
It can describe:
The project's commitment to accessibility
Accessibility standards or guidelines being followed
Known accessibility limitations
Supported accessibility features
How users can report accessibility problems
How accessibility issues are handled
Where users can find additional accessibility information
For example, a repository might contain:
README.md
CONTRIBUTING.md
SECURITY.md
ACCESSIBILITY.md
LICENSE
The ACCESSIBILITY.md file provides a dedicated location for accessibility information.
The exact filename is not important. What matters is that users can find the information easily.
Why Add Accessibility Information to a GitHub Repository?
A repository can serve several different audiences.
Developers
Contributors
Users
Maintainers
Organizations
Accessibility reviewers
Each group may have different questions.
A user may want to know:
"How do I report an accessibility problem?"
A contributor may want to know:
"What accessibility standards should I follow when submitting UI changes?"
A maintainer may need to know:
"Where should accessibility issues be tracked?"
A dedicated accessibility statement gives everyone a common reference point.
It also prevents accessibility information from being scattered across README sections, issue discussions, project documentation, and release notes.
Accessibility Statement vs Accessibility Testing
These two concepts should not be confused.
An accessibility statement communicates the project's accessibility position.
Accessibility testing verifies whether the software actually meets the expected requirements.
For example:
Accessibility Statement
|
v
Explains standards, scope, limitations,
and reporting process
Accessibility Testing
|
v
Checks keyboard navigation,
screen readers, contrast,
focus behavior, labels, etc.
A project can have a well-written accessibility statement and still contain accessibility defects.
The statement should therefore describe the current state honestly.
Avoid claiming that a project is fully accessible unless the team has evidence to support that claim.
Decide Where to Store the Statement
There are several reasonable options.
Dedicated Accessibility File
A file such as:
ACCESSIBILITY.md
is useful for projects where accessibility information is substantial.
The file can be linked from the repository README.
README Section
For smaller projects, accessibility information may fit directly into:
README.md
For example:
## Accessibility
We aim to make this project usable with keyboard navigation
and common assistive technologies.
If you encounter an accessibility issue, please report it
through the project's accessibility issue process.
Documentation Section
Large projects may already have a documentation structure.
In that case:
docs/
accessibility.md
can work well.
The important consideration is discoverability.
A user should not need to search through unrelated documentation to find accessibility information.
What Should an Accessibility Statement Contain?
A useful statement should answer practical questions rather than simply say that accessibility is important.
A basic structure can be:
Accessibility Statement
1. Commitment
2. Scope
3. Standards and guidelines
4. Current accessibility support
5. Known limitations
6. Testing approach
7. Reporting accessibility issues
8. Response process
9. Maintenance
Each section should contain information that applies to the actual project.
Start With a Clear Accessibility Commitment
The opening section should explain the project's approach.
For example:
This project aims to provide an accessible experience for users
with different accessibility needs. Accessibility is considered
during feature development, testing, and maintenance.
Keep this statement realistic.
Avoid vague claims such as:
"Our application is accessible to everyone."
A software project can have accessibility goals without being perfect.
The statement should describe the team's current approach rather than make an absolute claim.
Define the Scope
Explain which parts of the project the statement covers.
For example:
This statement covers the web application and its primary
user interface.
It does not currently cover third-party services embedded
within the application.
This distinction is important because applications often depend on external systems.
A project may control its own UI but not the accessibility behavior of:
Clearly identifying the scope prevents confusion.
Document Accessibility Standards
If the project follows a specific accessibility standard, document it.
For web applications, teams may use recognized accessibility guidance such as WCAG.
For example:
Accessibility targets include keyboard navigation,
semantic HTML, focus management, text alternatives,
color contrast, and screen-reader compatibility.
If a specific conformance level is being targeted, the project should document that accurately.
Do not claim compliance simply because some automated tests pass.
Accessibility conformance generally requires more than automated scanning.
Explain Current Accessibility Support
Users should understand what the application currently supports.
For example:
Current support includes:
- Keyboard navigation for primary workflows
- Visible focus indicators
- Labels for form controls
- Alternative text for meaningful images
- Accessible error messages
- Semantic page structure
Only list features that the project has actually implemented and tested.
This section is particularly useful for users who depend on assistive technologies.
Document Known Limitations
This is one of the most important sections.
If the project has known accessibility limitations, document them.
For example:
Known limitations:
- Some complex charts do not yet provide equivalent
text-based data.
- Certain legacy dialogs have inconsistent focus behavior.
- Some third-party components have accessibility limitations.
Being transparent about limitations is more useful than presenting an unrealistic accessibility claim.
It also gives maintainers a starting point for future improvements.
Explain How Accessibility Is Tested
Describe the project's testing approach.
Accessibility testing can include:
Automated testing
+
Keyboard testing
+
Screen-reader testing
+
Manual UI review
+
Regression testing
Automated tools can identify certain issues, such as missing labels or some contrast problems.
They cannot reliably determine whether every workflow is understandable or usable with assistive technology.
A practical testing process may include:
Automated Checks
Run accessibility checks during development or CI.
For example:
Build
|
v
Unit Tests
|
v
Accessibility Checks
|
v
Integration Tests
|
v
Deployment
Keyboard Testing
Verify that users can:
Reach interactive controls
Move through the interface logically
See the current focus
Open and close dialogs
Submit forms
Recover from validation errors
Screen Reader Testing
For important workflows, test with the screen readers supported by the project.
Check whether:
Headings are meaningful
Buttons have useful names
Form controls have labels
Errors are announced appropriately
Dynamic content changes are communicated
Provide a Clear Reporting Process
Users need to know what to do when they find an accessibility problem.
A statement should provide a clear reporting path.
For example:
If you encounter an accessibility issue, open an issue
using the project's accessibility issue template and
include the affected page, workflow, and steps to reproduce.
If accessibility issues require private reporting, the project should provide an appropriate private contact mechanism instead of asking users to publish sensitive information publicly.
The reporting method should match the project's privacy and security requirements.
Create an Accessibility Issue Template
A GitHub issue template can make reports more consistent.
For example:
## Accessibility Issue
### Affected area
<!-- Page, component, or workflow -->
### Problem
<!-- Describe the accessibility problem -->
### Steps to reproduce
1. Open ...
2. Navigate to ...
3. Select ...
### Expected behavior
<!-- Describe the expected accessible behavior -->
### Actual behavior
<!-- Describe what currently happens -->
### Assistive technology
<!-- Optional: screen reader, keyboard-only usage, etc. -->
### Additional information
<!-- Screenshots or other relevant details -->
This gives maintainers the information needed to investigate the issue.
Avoid requiring users to provide unnecessary personal or sensitive information.
Connect Accessibility Issues to Development Workflows
Accessibility should not become a separate process that disappears after an issue is reported.
A useful workflow is:
Accessibility Issue
|
v
Triage
|
v
Severity Assessment
|
v
Development
|
v
Accessibility Testing
|
v
Code Review
|
v
Release
|
v
Regression Testing
The exact workflow depends on the project, but accessibility defects should enter the same engineering lifecycle as other important defects.
Include Accessibility in Pull Request Reviews
Accessibility should be considered when UI-related code changes are reviewed.
For example, a pull request that adds a new form should prompt reviewers to check:
Form labels
Keyboard navigation
Focus behavior
Validation messages
Error identification
Semantic controls
Screen-reader behavior
A simple checklist can be added to pull requests:
### Accessibility
- [ ] Keyboard navigation tested
- [ ] Focus behavior checked
- [ ] Form controls have accessible names
- [ ] Error messages are accessible
- [ ] Relevant automated accessibility checks pass
This makes accessibility part of normal development rather than a final-stage activity.
Handle Third-Party Components Carefully
Modern applications often use component libraries.
A team may assume that a component is accessible because the library claims accessibility support.
That assumption should still be validated against the application's implementation.
For example:
Accessible Component
+
Custom Configuration
+
Application Integration
=
Actual User Experience
An accessible component can become inaccessible when:
Required labels are removed
Focus behavior is overridden
Custom styling reduces contrast
Keyboard handlers are replaced
ARIA attributes are misused
Review accessibility at the integration level.
Keep the Statement Updated
An accessibility statement should not become a static document that is forgotten after the repository is created.
Update it when:
Accessibility standards change
Major UI components are replaced
Known issues are resolved
New limitations are discovered
Testing practices change
Reporting processes change
Project scope changes
A stale statement can be worse than having no statement because users may rely on information that is no longer accurate.
Example Accessibility Statement Structure
A project can use a structure similar to this:
# Accessibility
## Commitment
We aim to make this project accessible and consider
accessibility during development, testing, and maintenance.
## Scope
This statement applies to the web application maintained
in this repository.
## Standards
The project follows applicable accessibility guidance
and evaluates important user workflows using automated
and manual testing.
## Current Support
- Keyboard navigation for primary workflows
- Accessible names for interactive controls
- Visible focus indicators
- Text alternatives for meaningful images
- Accessible validation messages
## Known Limitations
Some legacy components may have incomplete keyboard
or screen-reader support.
## Reporting Issues
Report accessibility problems through the project's
accessibility issue process.
## Testing
Accessibility is checked through automated tests,
keyboard testing, and manual review of important workflows.
## Maintenance
This statement is reviewed when major accessibility
changes or application changes are introduced.
The actual content should be adapted to the project's real accessibility status.
Common Mistakes
Claiming Full Accessibility Without Evidence
Avoid absolute claims unless they are supported by an appropriate assessment.
Relying Only on Automated Testing
Automated tools are useful, but they cannot replace manual accessibility testing.
Hiding Known Limitations
Known problems should be documented honestly and tracked for resolution.
Making the Reporting Process Difficult
Users should not have to search through the repository to discover how to report an accessibility problem.
Forgetting Third-Party Dependencies
External components and services can affect the overall accessibility experience.
Never Updating the Statement
Accessibility information should change as the application changes.
Best Practices
Keep the accessibility statement easy to find.
Clearly define the scope of the statement.
Document the accessibility standards or guidance being used.
Describe actual accessibility support.
Document known limitations honestly.
Provide a clear reporting process.
Use an accessibility issue template where appropriate.
Include accessibility checks in pull request workflows.
Combine automated and manual testing.
Review third-party components as part of integration testing.
Avoid absolute accessibility claims without evidence.
Update the statement when the application changes.
Advantages
A repository-level accessibility statement can provide several benefits:
Makes accessibility information easier to discover.
Gives users a clear reporting path.
Helps contributors understand project expectations.
Makes accessibility part of the development process.
Documents known limitations.
Creates a reference point for accessibility testing.
Improves transparency around project accessibility.
It also gives development teams a practical place to document accessibility responsibilities.
Disadvantages
There are also limitations:
A statement does not guarantee an accessible application.
Documentation requires ongoing maintenance.
Accessibility claims can become inaccurate if testing is not kept current.
Third-party dependencies may remain outside the project's direct control.
Some accessibility issues require manual assessment and cannot be captured completely through automation.
The statement should therefore be treated as part of an accessibility program, not as a substitute for accessibility engineering.
Production Checklist
Before publishing an accessibility statement for a GitHub repository, verify:
The document has a clear and discoverable location.
The project scope is defined.
Accessibility goals are documented.
Applicable standards are identified.
Current accessibility support is described accurately.
Known limitations are documented.
Accessibility testing methods are explained.
Users have a clear issue-reporting process.
Accessibility issues can enter the normal development workflow.
Pull request reviews include relevant accessibility checks.
Third-party components are considered.
The statement has an owner or maintenance process.
The document is reviewed when significant application changes are introduced.
Summary
An accessibility statement gives a GitHub project a clear place to explain its accessibility approach, current support, known limitations, testing practices, and issue-reporting process.
The statement itself does not make software accessible. Its value comes from connecting documentation with actual engineering practices.
For a useful implementation, keep the statement honest, define its scope, explain how accessibility is tested, provide a straightforward reporting process, and include accessibility checks in normal development workflows.
For small projects, the information can live in the README. Larger projects can use a dedicated ACCESSIBILITY.md file or documentation section.
The most important principle is consistency: accessibility information should reflect the actual state of the project and evolve as the software evolves.
Join the conversation! Your thoughts help the community grow.