| title | ACCESSIBILITY.md |
|---|
A simple, open format for documenting a project’s accessibility posture, automation, and contributor expectations.
Think of ACCESSIBILITY.md as a README for accessibility: a predictable place for humans and AI coding agents to find your a11y standards.
See full ACCESSIBILITY-template.md
# ACCESSIBILITY.md
- Target: WCAG 2.2 AA
- axe-core checks in pull requests
- Fail build on critical a11y regressions
- Keyboard and screen-reader checks required
No unresolved blockers in merged PRs
This project is still experimental. Most of the content on this site was generated with AI assistance and has not yet been fully validated in real-world conditions. Impacts may vary significantly depending on where and how it is implemented.
Do not expect that simply adding an ACCESSIBILITY.md file will make your digital tool accessible.
What it can do is signal to developers that accessibility matters, and make explicit what your development
processes are and how they affect accessibility.
People with direct experience conducting studies on the accessibility impact and cost implications of AI-assisted workflows should be involved before drawing conclusions from this work.
Please share your experience — positive or negative — in the issue queue. Include links and references so claims can be examined and discussed by the community.
README files are for broad project onboarding. ACCESSIBILITY.md adds a dedicated layer for accessibility status, known gaps, and enforcement workflows.
Keeping this guidance explicit improves transparency for users, clarity for maintainers, and reliability for AI coding agents.
This repository is organized to help you quickly find what to adopt vs. what to reference:
[Repository Root]
├── ACCESSIBILITY-template.md ← Start here: Copy this template
├── AGENTS.md ← AI agent instructions
│
├── examples/ ← Copy these to your project
│ ├── A11Y_SHIFT_LEFT_WORKFLOW.yml
│ ├── PRE_COMMIT_ACCESSIBILITY_SAMPLE.yaml
│ ├── TRUSTED_SOURCES.yaml
│ ├── Component best practices (SVG, forms, keyboard, diagrams)
│ └── Automation guides (axe-core, shift-left testing)
│
├── .github/workflows/ ← This repo's automation (reference)
├── _layouts/, _config.yml ← Jekyll site (for documentation)
└── README.md ← Complete adoption guide
Key:
✅ Copy to your project: ACCESSIBILITY-template.md, files in examples/
🤖 Install globally in AI agents: see accessibility-skills
📖 Read for guidance: README.md, AGENTS.md, CONTRIBUTING.md
🛠️ Jekyll/docs site: _layouts/, _config.yml, assets/, index.md
GitHub Actions, GitLab CI, axe-core, pa11y, Lighthouse CI, and AccessLint integration patterns for accessibility automation
Complete reference of axe-core accessibility rules, categories, and WCAG mappings
Move accessibility testing earlier in your development workflow to catch issues sooner
Vetted accessibility resources with automated monthly maintenance
Includes wai-yaml-ld for machine-readable WCAG standards
Descriptive link text, focus management, skip links, smooth-scroll animation with prefers-reduced-motion, and WCAG criteria for in-page links
Captions, transcripts, audio descriptions, and accessible media player implementation
Plain language, page structure, readability, and content style guidance aligned with accessibility goals
Alt text decision tree, decorative vs. informative images, complex image descriptions, and WCAG 1.1.1 compliance guidance
Browse all accessibility best practice guides and examples in this repository
Color scheme support, contrast requirements, and system preference integration
WCAG 2.2 AA contrast requirements for text, non-text elements, and focus indicators; APCA introduction; forced-colors mode; and CSS patterns for accessible color palettes
User preference controls, CSS media queries, and avoiding accessibility overlays
Screen reader, keyboard, and cognitive testing techniques with step-by-step checklists
Structured templates, JSON schema, and guidance for writing reproducible accessibility bug reports optimised for automated tools and AI agents
Accessible static and interactive charts, text alternatives, color-independent encoding, keyboard-navigable data visualizations, and WCAG 2.2 compliance guidance
Accessible static and interactive maps, keyboard-operable controls, text alternatives, and indoor wayfinding guidance
ARIA tooltip pattern, keyboard interaction, WCAG 1.4.13 compliance, mobile considerations, and design system references
245 rules across 14 categories covering accessibility, security, performance, privacy, ecodesign, and web quality — based on the Opquast Digital Quality Checklist
CSS print media queries, page break control, link URL disclosure, typography for paper, and WCAG guidance for accessible printed documents
Build accessible, resilient web experiences starting from a solid HTML foundation
Polite vs assertive announcements, injection timing, role="status" and role="alert" patterns, and framework-specific timing for dynamic content updates
Landmark structure, skip links, aria-current, disclosure dropdowns, breadcrumbs, pagination, and mobile hamburger navigation
Sentence length, active voice, reading level targets, abbreviation expansion, and structure-first writing for cognitive accessibility
Semantic table markup with th scope, captions, responsive patterns, sortable columns, and accessible layout-table remediation
Target size minimums, pointer cancellation, drag alternatives, motion actuation, and WCAG 2.5.x criteria for touch and pointer interactions
Ready-to-use AI prompts for common accessibility tasks in development workflows
Structure AGENTS.md for GitHub Copilot agent mode: dual-audience templates, WCAG-grounded task patterns, stopping conditions, and PR output format
Interactive tool to generate accessibility prompt templates for AI coding assistants
Practical accessibility workflow guide
Our accessibility standards and metrics
Digital sustainability and AI usage guidelines
AI coding assistant guidance for this project
Portable .skill archives for global installation in Codex, Claude Code, and other AI coding assistants
Browser version support guarantees
How to contribute to this project
Section 508 compliance requirements for government contracts and RFPs
Analysis of different approaches to accessibility documentation
AI agent skills have moved to a dedicated repository:
accessibility-skills.
Topic-specific .skill archives (forms, keyboard, maps, SVG, and more) are available
there for global installation in Claude Code, Codex, and other AI coding assistants.
Follow these steps to implement ACCESSIBILITY.md in your project:
Start with ACCESSIBILITY-template.md, customize it for your project, and place it at your repository root. Link it from your README.
Copy workflows from the examples/ directory. Start with A11Y_SHIFT_LEFT_WORKFLOW.yml for automated accessibility testing on every PR.
Install skills globally from the accessibility-skills repository in Codex, Claude Code, or other AI coding assistants. Or copy AGENTS.md / create .cursorrules for project-level configuration.
Copy PRE_COMMIT_ACCESSIBILITY_SAMPLE.yaml to catch issues before they're committed. Optional but highly recommended.
Add relevant best practice guides for forms, SVGs, keyboard navigation, light/dark mode, user personalization, and diagrams from the examples directory.
Update ACCESSIBILITY.md as your project evolves. Track metrics, document gaps, and maintain your commitment to accessibility.
For detailed instructions, see the step-by-step adoption guide in the README.