WAI-ARIA Authoring Practices Guide (APG)

The common directory serves as a central repository for resources shared across multiple ARIA specifications.

Usage Guidelines

• Shared Resources: Place images, CSS, or scripts in the common directory if they are (or are likely to be) used by more than one specification.
• Specification-Specific Resources: Place resources that are unique to a single specification, or CSS intended to override common styles, directly in that specification's own directory.
• Organization: To maintain consistency, use the following sub-directory structure within both common and specification-specific directories:
  • img/
  • css/
  • script/

To set up the local development environment, ensure you have Node.js and npm installed. Navigate to the repository directory in your terminal and run the installation command.

Note: The HTML validator also requires a JDK to be installed on your system.

npm install

To ensure the JavaScript examples are working correctly, you can run the test suite. This script tests all JavaScript files within the examples directory.

Note: Running tests may take several minutes and will open multiple browser windows that will take focus.

To fix errors:

1. Run npm test to identify issues.
2. Run npm run fix to attempt automatic repairs of many errors.
3. Re-run npm test to identify remaining manual fixes.

To include the common set of term definitions from terms.html into a specification, use a div element with the data-include and data-oninclude attributes. Using data-oninclude="restrictReferences" ensures that only the terms actually referenced within your specific specification are output, preventing unnecessary bloat.

Note: Content must be updated in the source w3c/aria-common repository. Changes made in local copies will be overwritten during the next sync.

<div data-include="../common/terms.html" data-oninclude="restrictReferences"></div>

ARIA publications use a shared bibliography stored in biblio.js. To use these entries in a Respec-based specification, follow these two steps:

1. Load the biblio.js script at the top of your file using the remove class to prevent it from being treated as a standard script by the processor.
2. In your respecConfig object, assign the localBiblio property to the biblio object created by the script.

Note: Content must be updated in the source w3c/aria-common repository. Changes made in local copies will be overwritten during the next sync.

<script src="../common/biblio.js" class="remove"></script>

// Inside respecConfig
localBiblio: biblio,

The project uses ESLint with the Flat Config format (eslint.config.mjs). The configuration applies different rules and environments based on file patterns:

• General JavaScript (**/*.js): Uses ecmaVersion: 2021, sourceType: 'script', and includes globals.browser. It enforces jsdoc recommendations (with specific overrides) and prohibits console.log.
• Tests (test/**/*.js): Uses ecmaVersion: 'latest', sourceType: 'commonjs', and includes globals.node. It uses the ava plugin and restricts the use of findElements in favor of t.context.queryElements().
• Scripts (scripts/*.js, .link-checker.js): Uses @babel/eslint-parser with ecmaVersion: 'latest' and globals.node. no-console is disabled here.
• HTML (**/*.html): Uses eslint-plugin-html and enables the sourceCode global.
• ES Modules (**/*.mjs): Sets sourceType: 'module'.

The repository uses static analysis tools to ensure code quality. Pull requests with linting errors will not be merged. You can run these tools locally using the following commands:

• HTML: Validated against the NU HTML Validator.
• CSS: Validated by stylelint using stylelint-config-standard. Many issues can be automatically fixed.
• JavaScript: Validated by ESLint using the project's .eslintrc.json configuration. Many issues can be automatically fixed.

npm run lint:html
npm run lint:css
npm run lint:js

When linting files in test/**/*.js, the following specific rules and restrictions apply:

• Uses ava recommended configurations.
• Restricted Property: The property findElements is restricted.
  • Error Message: Please use t.context.queryElements().
• strict mode is turned off.
• Environment is set to node with commonjs source type.

rules: {
  ...ava.configs.recommended.rules,
  'no-restricted-properties': [
    2,
    {
      property: 'findElements',
      message: 'Please use t.context.queryElements().',
    },
  ],
  strict: 'off',
}

The following files and directories are explicitly ignored by ESLint:

• **/*.min.js
• common/
• content/patterns/landmarks/examples/js/visua11y.js
• content/shared/js/highlight.pack.js
• content/shared/js/skipto.js