WAI-ARIA: Authoring Practices Guide
This repository maintains the WAI-ARIA Authoring Practices Guide (APG).
- Published at: w3.org/wai/aria/apg
- Developed by the Authoring Practices Task Force of the ARIA Working Group.
- Staff contact: Michael Cooper.
Please do not provide commit access to this repository without coordination.
How the work is organized
- Work is planned and prioritized in our milestones. Each milestone corresponds to a working draft or release published to w3.org.
- Work is organized by topic in our projects. Each project corresponds to a type of design pattern or section of guidance.
- The scope of work and roadmap are described in the project wiki.
- Comment in an existing issue or raise a new issue, expressing your willingness to help and briefly summarizing the nature of your proposed resolution.
- An editor will confirm there are no conflicting plans and, if needed, provide guidance.
- Be sure you have linters installed and configured as described below.
- Read our wiki page about submitting pull requests.
- Do some fabulous work and submit a pull request.
Note: Please feel free to ask questions either through an issue or on the Authoring Practices Task Force mailing list.
- Make sure that you have Node.js installed, which comes with node package manager (npm)
- Open the directory that contains your
aria-practicesrepository in a terminal
The HTML validator also requires the installation of a JDK in order to run. If you don't already have a JDK installed, download the latest JDK from Oracle.
It is also highly recommended that you use a code editor that supports these tools and EditorConfig.
HTML is validated against the NU HTML Validator.
Should a warning or error occur because a future ARIA feature is not yet implemented, it will be added to the .vnurc file, allowing the error to pass through.
npm run lint:html
NOTE: on commit, stylelint will be run on staged CSS files. If errors are found that can be automatically fixed with the --fix flag, they will be fixed and the changes committed.
npm run lint:css
NOTE: on commit, eslint will be run on staged CSS files. If errors are found that can be automatically fixed with the --fix flag, they will be fixed and the changes committed.
npm run lint:js
Test and fix your code
- Open a terminal window to the directory that contains the
npm test. Note: this may take a few minutes to run and will open several browser windows during the test that will gain focus.
- Many errors can be fixed automatically with the command
npm run fix.
- After running fix, test again to see what you need to fix manually.
When the linter encounters errors, it will report them in the console.
The error report will contain the file name and line number, and it will
indicate the character or place in the line that raised the style violation. To
fix an error, satisfy the change that the violation indicates.
For example, here is an error for an invalid variable name style. Variables must
follow a camelCase convention.
/Users/user1/Documents/github/aria-practices/examples/slider/js/text-slider.js 19:8 error Identifier 'value_nodes' is not in camel case camelcase
The error occurred in
examples/slider/js/text-slider.js, on line 19 and the
offending character is indicated by the number
8 after the colon. Change the
valueNodes in your source file to eliminate this
To see the complete list of style rules that are applied by ESLint, review the .eslintrc.json file in the root of the project.
ARIA Roles, Properties and States Referenced in Guidance and Examples(Also known as APG Coverage Report)
APG Coverage Report includes information on number of guidance and example references in the WAI-ARIA Authoring Practices for each ARIA role, property and state.
As of January 11, 2022, APG has examples of
- CSV Files of Role, Properties and States Coverage
- Roles with no Guidance or Examples (29)
- Roles with at Least One Guidance or Example (13)
- Roles with More than One Guidance or Example (36)
- Properties and States with no Examples (12)
- Properties and States with One Examples (8)
- Properties and States with More than One Example (28)
- Example Coding Practices