Skip to content

mgifford/ACCESSIBILITY.md

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

340 Commits
.github
.github
 
 
_layouts
_layouts
 
 
agents
agents
 
 
assets
assets
 
 
examples
examples
 
 
.gitignore
.gitignore
 
 
.lighthouserc.json
.lighthouserc.json
 
 
ACCESSIBILITY-template.md
ACCESSIBILITY-template.md
 
 
ACCESSIBILITY.md
ACCESSIBILITY.md
 
 
AGENTS.md
AGENTS.md
 
 
BRANCH_MERGE_STATUS_REPORT.md
BRANCH_MERGE_STATUS_REPORT.md
 
 
BROWSER_SUPPORT.md
BROWSER_SUPPORT.md
 
 
COMPARISON_WITH_KREERC.md
COMPARISON_WITH_KREERC.md
 
 
CONTRIBUTING.md
CONTRIBUTING.md
 
 
Gemfile
Gemfile
 
 
Gemfile.lock
Gemfile.lock
 
 
INSTALL.txt
INSTALL.txt
 
 
LICENSE
LICENSE
 
 
README.md
README.md
 
 
STYLES.md
STYLES.md
 
 
SUSTAINABILITY.md
SUSTAINABILITY.md
 
 
_config.yml
_config.yml
 
 
action-playbook.md
action-playbook.md
 
 
index.md
index.md
 
 
prompt-generator.md
prompt-generator.md
 
 
search-index.json
search-index.json
 
 
search.md
search.md
 
 

Repository files navigation

ACCESSIBILITY.md

The open standard for project accessibility transparency, governance, and AI-assisted inclusion.

Just as SECURITY.md defines how to handle vulnerabilities, ACCESSIBILITY.md defines the inclusive state of a project. It is a human and machine-readable manifest that tracks a project’s commitment to accessibility (a11y) through metrics, guardrails, and automated enforcement.

Looking for the Claude Skills approach? If you want to add accessibility guidance to a project via an AGENTS.skills, see the companion repo: mgifford/accessibility-skill.

Warning

⚠️ 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.

🚀 Quick start

New to this project? Here's what you need:

  1. Copy the template → Start with ACCESSIBILITY-template.md
  2. Add CI workflows → Copy from examples/ directory
  3. Configure AI agents → Use AGENTS.md as a guide
  4. Read the framework → Continue below to understand the approach

Looking for specific files? See the Repository Structure below.

Additional resources:

📁 Repository structure

This repository is organized to separate content you adopt from project documentation:

[Repository Root]
├── ACCESSIBILITY-template.md       ← Start here: Copy this template
├── ACCESSIBILITY.md                ← Our own accessibility commitment
├── AGENTS.md                       ← AI agent instructions (copy/adapt)
├── CONTRIBUTING.md                 ← How to contribute to this project
├── SUSTAINABILITY.md               ← Sustainability policy
├── BROWSER_SUPPORT.md              ← Browser support guidelines
├── COMPARISON_WITH_KREERC.md       ← Comparison with similar projects
├── README.md                       ← This file
│
├── examples/                       ← Copy these to your project
│   ├── A11Y_SHIFT_LEFT_WORKFLOW.yml          ← GitHub Actions workflow
│   ├── PRE_COMMIT_ACCESSIBILITY_SAMPLE.yaml  ← Pre-commit hooks
│   ├── TRUSTED_SOURCES.yaml                  ← Vetted a11y resources
│   ├── AUDIO_VIDEO_ACCESSIBILITY_BEST_PRACTICES.md ← Component guides
│   ├── ANCHOR_LINKS_ACCESSIBILITY_BEST_PRACTICES.md
│   ├── CI_CD_ACCESSIBILITY_BEST_PRACTICES.md
│   ├── COLOR_CONTRAST_ACCESSIBILITY_BEST_PRACTICES.md
│   ├── CONTENT_DESIGN_ACCESSIBILITY_BEST_PRACTICES.md
│   ├── SVG_ACCESSIBILITY_BEST_PRACTICES.md
│   ├── FORMS_ACCESSIBILITY_BEST_PRACTICES.md
│   ├── KEYBOARD_ACCESSIBILITY_BEST_PRACTICES.md
│   ├── LIGHT_DARK_MODE_ACCESSIBILITY_BEST_PRACTICES.md
│   ├── USER_PERSONALIZATION_ACCESSIBILITY_BEST_PRACTICES.md
│   ├── MANUAL_ACCESSIBILITY_TESTING_GUIDE.md
│   ├── MERMAID_ACCESSIBILITY_BEST_PRACTICES.md
│   ├── AXE_RULES_COVERAGE.md                 ← Automation reference
│   ├── SHIFT_LEFT_ACCESSIBILITY_AUTOMATION.md
│   └── README.md                             ← Examples index
│
├── .github/workflows/              ← This repo's automation (reference)
│   ├── link-check.yml              ← Weekly link validation
│   └── maintain-trusted-sources.yml ← Monthly TRUSTED_SOURCES maintenance
├── _layouts/                       ← Jekyll theme (for documentation site)
├── _config.yml                     ← Jekyll config (for documentation site)
├── assets/                         ← Site assets (for documentation site)
├── index.md                        ← Landing page (for documentation site)
├── prompt-generator.md             ← Interactive prompt builder
└── action-playbook.md              ← Practical workflow guide

Key:

  • ✅ Copy to your project: ACCESSIBILITY-template.md, files in examples/
  • 📖 Read for guidance: README.md, AGENTS.md, CONTRIBUTING.md, COMPARISON_WITH_KREERC.md
  • 🛠️ Jekyll/docs site: _layouts/, _config.yml, assets/, index.md

🚀 Why this exists

Modern software is built by two groups: Humans and AI Agents. Currently, neither has a reliable place to look for a project's accessibility "Source of Truth."

  1. For Users: It provides transparency on what works, what doesn't, and how to report barriers.
  2. For Maintainers: It standardizes how a11y debt is tracked and how contributors are expected to code.
  3. For AI Agents: It provides explicit "System Instructions" for LLMs (like Copilot, Cursor, or GPT-4) to ensure they don't generate inaccessible code patterns.

🛠 The framework

An effective ACCESSIBILITY.md file acts as a Living Commitment, covering three core pillars:

1. Transparency and disclosure

  • Conformance Level: Current WCAG status (e.g., 2.2 AA).
  • Known Gaps: Honest disclosure of current barriers.
  • Assistive Tech: Actively tested with.

2. Operational governance

  • Taxonomy: Standardized labels for issues (e.g., accessibility, color-contrast).
  • Definition of Done: Requirement that no PR is merged without passing a11y linting.
  • Severity Matrix: How a11y bugs are prioritized compared to feature requests.

3. Automated guardrails (the AI bridge)

📊 The "living metric" table

We recommend including a dynamic table in your file to track progress. This turns a static statement into a measurable pulse.

Metric Status / Source
A11y Issue Health Open: 12 / Closed (Last 30d): 8
Automated Pass Rate 96% (via GitHub Actions)
CI/CD Enforcement 🛑 Strict (Build fails on a11y errors)
Contributor Guide Read the A11y Guide

📖 How to adopt this in your project

This repository provides templates and guidance to help you implement ACCESSIBILITY.md in your own projects.

Step 1: Add ACCESSIBILITY.md to your repository

Option A: Start with the template

  1. Copy ACCESSIBILITY-template.md to your repository root
  2. Rename it to ACCESSIBILITY.md
  3. Customize the sections to match your project's current state
  4. Link it from your README.md

Option B: Use the interactive prompt generator

Step 2: Set up GitHub workflows (CI/CD automation)

Copy the workflows that match your needs from the examples/ directory:

Basic setup:

# Copy the main accessibility workflow
cp examples/A11Y_SHIFT_LEFT_WORKFLOW.yml .github/workflows/

Additional workflows:

  • Browser testing: Copy examples/BROWSER_TESTING_WORKFLOW.yml for multi-browser a11y checks
  • Link checking: See .github/workflows/link-check.yml (already in this repo) as a reference

Workflow features:

  • ✅ Runs axe-core accessibility tests on every PR
  • ✅ Fails builds on critical accessibility issues
  • ✅ Provides detailed reports for fixing issues

Learn more: SHIFT_LEFT_ACCESSIBILITY_AUTOMATION.md

Step 3: Configure AI coding assistants

Help your AI tools (GitHub Copilot, Cursor, Claude, Codex, etc.) respect accessibility standards:

For project-level configuration:

For Cursor or similar tools:

  1. Copy AGENTS.md to your repository root
  2. Or create .cursorrules with instructions from AGENTS.md
  3. Customize component-specific guides as needed

For GitHub Copilot:

  • Add ACCESSIBILITY.md reference to your project documentation
  • Copilot will automatically read it for context

What AI agents get:

  • WCAG 2.2 AA compliance requirements
  • Component-specific best practices (forms, SVGs, diagrams, keyboard, light/dark modes)
  • Asset optimization guidelines
  • Testing requirements

See the full guide: AGENTS.md

Step 4: Add pre-commit hooks (optional but recommended)

Catch accessibility issues before they're committed:

# Copy the pre-commit configuration
cp examples/PRE_COMMIT_ACCESSIBILITY_SAMPLE.yaml .pre-commit-config.yaml

# Install pre-commit (if not already installed)
pip install pre-commit

# Install the hooks
pre-commit install

Step 5: Add component-specific best practices

Copy relevant guides to your project's documentation:

Step 6: Reference trusted sources

Copy the vetted accessibility resources list:

cp examples/TRUSTED_SOURCES.yaml docs/

This provides:

Resources for this repository

Contributing to this project:

Building the documentation site:

  • INSTALL.txt: Local setup and Jekyll build instructions

Reference materials:

🔄 Automated quality maintenance

TRUSTED_SOURCES.yaml monthly maintenance

The TRUSTED_SOURCES.yaml file is automatically maintained via a monthly GitHub Action that:

  • Validates URLs: Checks for 404 errors with a two-strike removal policy
    • First 404 → marked as "not active"
    • Second 404 → removed from the list
  • Enriches metadata: Automatically fills in missing owner, license, and freshness information
  • Quality checks: Validates YAML structure and ensures data consistency
  • Creates PRs: All changes are reviewed by maintainers before merging

This ensures the trusted resources list remains high-quality and up-to-date without manual maintenance overhead.

📖 Full maintenance documentation

🤖 AI agent integration

To ensure your AI coding assistant respects your accessibility standards, add this to your .cursorrules, AGENTS.md, or system prompt:

"Before modifying or creating UI components, read ACCESSIBILITY.md. Ensure all changes comply with WCAG 2.2 AA standards and follow the component-specific best practices in the examples directory. Optimize assets and use AI judiciously."

For a comprehensive guide on AI agent instructions for this project, see AGENTS.md.

Machine-readable standards for AI

For LLMs to provide more accurate, standards-grounded accessibility guidance, consider using wai-yaml-ld as a structured source of truth. This repository provides machine-readable YAML/JSON-LD artifacts of W3C WAI standards (WCAG, ATAG, UAAG, ARIA, HTML, CSS) that help AI agents:

  • Map implementation choices to specific standards relationships
  • Separate normative vs informative references
  • Produce auditable, standards-aligned recommendations
  • Explain the reasoning behind accessibility advice

Research: AI and digital accessibility

For a broad view of where AI intersects with accessibility research, Robert Dodd's analysis of 137 academic papers is a useful starting point:

The Current State of Digital Accessibility Research and AI: What 137 Papers Tell Us — Robert Dodd surveys the academic literature to map research trends, gaps, and opportunities where AI tools are being applied to digital accessibility.

🧩 AI Agent 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.

We will do our best to keep the instructions consistent whichever way you use this.

🤖 AI Disclosure

This section documents which AI tools have been used in the development and maintenance of this repository, and in what capacity. Per this project's AGENTS.md and SUSTAINABILITY.md, AI usage must be disclosed transparently.

This project is a documentation and template repository. No AI runs at runtime when users read or adopt these files, and no browser-based AI is embedded in the project itself.

LLMs used to build this project

Tool Provider Used for
GitHub Copilot Coding Agent GitHub / Microsoft (Claude models via Anthropic) Creating and maintaining documentation files, adding best-practice guides, refactoring content, managing pull requests, and performing repository maintenance tasks

Notes

  • Runtime AI: None. This is a static documentation project; no AI is invoked when users read or use the files.
  • Browser-based AI: None. No client-side or browser-based AI features are embedded in this project.
  • Human oversight: All AI-generated content is reviewed by the repository maintainer before merging. The README already notes: "Most of the content on this site was generated with AI assistance and has not yet been fully validated in real-world conditions."

How to update this disclosure

If you use an AI tool when contributing to this repository, please add or update the entry in the table above in your pull request. See AGENTS.md for the full instruction.

🤝 Contributing

We are looking for feedback on the taxonomy and automation workflows.

  • Read the guide: See CONTRIBUTING.md.
  • Found a gap? Open an issue.
  • Have a better workflow? Send a PR.
  • Using this? Let us know so we can add you to the "Adopters" list.

Related Projects

📄 License

This project is licensed under the MIT License.

Would you like me to generate a sample specification.md next to define the exact Markdown headings and data structures for this standard?

About

ACCESSIBILITY.md — a simple, open format (aligned with AGENTS.md) for guiding coding agents to be more accessible

mgifford.github.io/ACCESSIBILITY.md

Topics

ai accessibility a11y web-accessibility agents ai-agents llm

Resources

Readme

License

MIT license

Contributing

Contributing
Activity

Stars

40 stars

Watchers

2 watching

Forks

6 forks
Report repository

Contributors

Languages