Transparency & Disclosure
Publish conformance level, assistive tech coverage, and known barriers.
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.
⚠️ Experimental — Validate Before Use
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.
Why ACCESSIBILITY.md?
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.
Repository Structure
This repository is organized to help you quickly find what to adopt vs. what to reference:
[Repository Root]
├── ACCESSIBILITY-template.md ← Start here: customise for your project
├── AGENTS.md ← AI agent instructions
│
├── examples/ ← Reference and adapt for 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:
📋 Reference and adapt: 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
The Framework
Operational Governance
Define issue taxonomy, severity triage, and accessibility Definition of Done. Decide whether a barrier's fix belongs locally or upstream with Upstream First, and track any temporary local fix until it is released and verified.
Automated Guardrails
Enforce checks in CI and pre-commit workflows with documented rule coverage.
Reference Examples
Testing and Automation
CI/CD Accessibility Best Practices
GitHub Actions, GitLab CI, axe-core, pa11y, Lighthouse CI, and AccessLint integration patterns for accessibility automation
Axe Rule Coverage
Complete reference of axe-core accessibility rules, categories, and WCAG mappings
Shift-left Automation
Move accessibility testing earlier in your development workflow to catch issues sooner
Manual Accessibility Testing Guide
Screen reader, keyboard, visual, Reflow, and focus testing techniques with step-by-step checklists
Behavioral Accessibility Automation
Reusable, tested Playwright checks for Reflow risk and Focus Visible, with CI integration and result schemas
Accessibility Bug Reporting Best Practices
Structured templates, JSON schema, and guidance for writing reproducible accessibility bug reports
Content and Media
Content Design Accessibility Best Practices
Plain language, page structure, readability, and content style guidance aligned with accessibility goals
Plain Language Accessibility Best Practices
Sentence length, active voice, reading level targets, and structure-first writing for cognitive accessibility
Image Alt Text Accessibility Best Practices
Alt text decision tree, decorative vs. informative images, and complex image descriptions
Audio/Video Accessibility Best Practices
Captions, transcripts, audio descriptions, and accessible media player implementation
SVG Accessibility Best Practices
Accessible naming, decorative SVG, structured alternatives, and transformation safety
Tables Accessibility Best Practices
Semantic table markup, responsive patterns, sortable columns, and layout-table remediation
Interaction and Navigation
Keyboard Accessibility Best Practices
Keyboard interaction patterns, focus management, and roving tabindex for composite widgets
Navigation Accessibility Best Practices
Landmark structure, skip links, aria-current, disclosure dropdowns, and breadcrumbs
Anchor Links Accessibility Best Practices
Descriptive link text, focus management, skip links, and smooth-scroll animation with prefers-reduced-motion
Forms Accessibility Best Practices
Labels, fieldsets, validation, error association, and accessible form patterns
Tooltip Accessibility Best Practices
ARIA tooltip pattern, keyboard interaction, and WCAG 1.4.13 compliance
ARIA Live Regions Best Practices
Polite vs assertive announcements, role="status" and role="alert" patterns, and framework timing
Touch and Pointer Accessibility Best Practices
Target size minimums, pointer cancellation, drag alternatives, and WCAG 2.5.x criteria
Speech Recognition Accessibility Best Practices
WCAG 2.5.3 Label in Name, visible-accessible name alignment, and voice command testing
Visual Design
Color Contrast Accessibility Best Practices
WCAG 2.2 AA contrast requirements, APCA introduction, forced-colors mode, and CSS patterns
Light/Dark Mode Best Practices
Color scheme support, contrast requirements, and system preference integration
User Personalization Best Practices
User preference controls, CSS media queries, and avoiding accessibility overlays
Print-Friendly Style Sheets Best Practices
CSS print media queries, page break control, link URL disclosure, and typography for paper
Modern CSS Theme Architecture
Semantic design tokens, browser-native features, and progressive enhancement for accessible theme systems
Data Visualization
Charts and Graphs Accessibility Best Practices
Accessible charts, text alternatives, color-independent encoding, and keyboard-navigable visualizations
Maps Accessibility Best Practices
Accessible static and interactive maps, keyboard-operable controls, and indoor wayfinding
Mermaid Accessibility Best Practices
accTitle, accDescr, structured alternatives, and transformation safety for diagrams
Progressive Enhancement and Quality
Progressive Enhancement Best Practices
Build accessible, resilient web experiences starting from a solid HTML foundation
Opquast Digital Quality Best Practices
245 rules across 14 categories covering accessibility, security, performance, privacy, and web quality
Resources
Trusted Sources Registry
Machine-readable source metadata for discovery and review, with automated monthly maintenance
Includes wai-yaml-ld for machine-readable WCAG standards
Examples Index
Browse all accessibility best practice guides and examples in this repository
Browser Support Policy
Evidence-based browser and assistive technology support matrix
Skills
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.
For deciding whether a fix belongs locally, in an installed capability, or upstream, see Upstream First.
How to Adopt
Follow these steps to implement ACCESSIBILITY.md in your project:
1. Start with the Template
Begin with ACCESSIBILITY-template.md, customise it for your project, and place it at your repository root. Link it from your README.
2. Set Up GitHub Workflows
Reference workflows from the examples/ directory. Test them in a branch or disposable repository before making them required. A11Y_SHIFT_LEFT_WORKFLOW.yml is an experimental reference — review and adapt it for your project.
3. Configure AI Agents
Install skills globally from the accessibility-skills repository in Codex, Claude Code, or other AI coding assistants. Or reference AGENTS.md / create .cursorrules for project-level configuration.
4. Add Pre-Commit Hooks
Reference PRE_COMMIT_ACCESSIBILITY_SAMPLE.yaml as a starting point. It is a minimal placeholder — review and adapt it for your project before use.
5. Reference Component Guides
Adapt the best practice guides for forms, SVGs, keyboard navigation, light/dark mode, user personalization, and diagrams from the examples directory to your project's needs.
6. Keep it Living
Update ACCESSIBILITY.md as your project evolves. Track metrics, document gaps, and maintain your commitment to accessibility.