This repository maintains specifications and related publications for the Accessible Rich Internet Applications suite of technologies. This is developed by the ARIA Working Group. The W3C staff contact is Daniel Montalvo. Please do not provide commit access to this repository without coordination.
If you have a local clone, run the following commands to update the name of the default branch.
$ git branch -m master main
$ git fetch origin
$ git branch -u origin/main mainThis repository contains the main deliverable of the ARIA Working Group, Accessible Rich Internet Applications (ARIA), and should be used for issues related to the ARIA spec and and issues that involve both the ARIA spec in conjunction with other specifications maintained by the ARIA working group. All other specifications maintained by ARIA can be found in this repository as well, however, we have separate issue tracking repos for these separate specifications.
In addition to these specifications, there are other deliverables of the ARIA Contribution page. Please file issues in the repository specific to the specification or deliverable to which the issue applies.
Please review the ARIA Process Document for information about how the working group tracks issues and pull request.
Only formally designated editors have commit access to this repository. Editors are designated by the Working Group Chair and make the following commitments:
Working Group participants and members of the public without commit privileges may contribute to this repository in the following ways:
Issues can be assigned to people who are members of the ARIA Contributors team. Editors can add people to this team.
When preparing GitHub pull requests:
When a pull request is accepted by the Working Group, an editor will integrate changes. Pull requests and issues that are accepted by the working group will be merged into the source documents and the commenter will receive a notification from GitHub that the pull request was accepted.
Documents in this repository use the Respec preprocessor.
The ARIA spec allows easy generation of links to roles, states, and properties, with the right link and styling. Simply enclose the name of the role, state, or property in the following elements:
<rref> for roles<sref> for states<pref> for propertiesNote: this only works in the ARIA spec. Other specs must use cross references as defined below.
Links with special class attributes allow cross references into other specs in the suite, which are transformed by the script to be the appropriate target for the given publication, so editors' drafts point to other editors' drafts, and TR publications point to other TR publications. This requires some configuration options in the respecConfig and use of special class attributes.
First, for each document that might be referenced, a set of URLs is provided. The URLs are indexed by values of the respec spec status, which ensures the target at the same level of maturity as the current version is used. A typical set of values for the main ARIA spec is:
// Spec URLs
ariaSpecURLs: {
"FPWD": "http://www.w3.org/TR/wai-aria-1.1/",
"ED": "http://w3c.github.io/aria/aria/aria.html",
"WD" : "http://www.w3.org/TR/wai-aria-1.1/",
"REC": "http://www.w3.org/TR/wai-aria/"
},Note that even though some of these URIs are redundant, they must all be defined to work in all circumstances. If a document is a First Public Working Draft but the FPWD variant isn't defined, there won't be a match with the specStatus and the links won't work.
The following properties for cross references are currently available (todo: we should add versions for the other docs):
ariaSpecURLs: for the main ARIA speccoreMappingURLs: for the Core AAMaccNameURLs: for the AccName AAMhtmlMappingURLs: for the HTML AAMdpubModURLs: for DPUB ARIAgraphicsModURL: for Graphics ARIAgraphicsMappingModURL: for Graphics AAMpracticesURL: for PracticesThe task of fixing up links is done by a script that needs to be hooked in via the following line in the respecConfig:
preProcess: [ linkCrossReferences ]Once all this is defined in the respecConfig, use the class attribute on the links to activate the script for that link. The value of the href should be the fragment you want to target, i.e,. the hash tag and fragment ID. For example, a link to the list of roles in the ARIA spec would be:
<a href="#role_definitions" class="specref">ARIA roles</a>If you want to target the main spec, leave the href blank (but present). If you want other classes on the link, e.g., for styling, provide them after the script-hooking class, for instance class="specref role-reference".
The set of class values currently defined are:
role-reference: role definitionsstate-reference: state definitionsproperty-reference: property definitionsspecref: other targets in the main ARIA speccore-mapping: the Core AAMhtml-mapping: the HTML AAMaccname: the AccName AAMTodo: we should add versions for the other docs
When referencing other W3C specifications such as <a
href="https://html.spec.whatwg.org/">HTML and <a
href="https://dom.spec.whatwg.org/">DOM, we can take advantage of ReSpec’s
xref feature to
automatically generate canonical links in context.
In the text below, for example, xref will automatically convert “[^button^]”
into a link to the definition of the <button> element in the HTML
spec:
A [^button^] performs an operation when pressed.When authoring text for the ARIA spec, you can search xref’s collection of
exported terms to find the correct syntax for the
desired specification. By default, the ARIA spec’s xref configuration will
attempt to resolve terms for the following specs:
If you wish to reference a spec that is not included in ARIA’s default xref
configuration, you must specify it with a data-cite attribute. For example,
the following markup references “nullable
type” and
“DOMString” from the Web IDL spec:
<section data-cite="webidl">
<p>
All ARIA attributes reflect in IDL as [=nullable type|nullable=]
{{DOMString}} attributes.
</p>
</section>In some cases, a term may be defined in multiple specifications with the same
xref syntax. For example, “[=range=]” is defined in both the DOM and
Internationalization Glossary specs. The
data-cite attribute can also be used in these cases to disambiguate and target
the intended spec.
For more information, please refer to xref’s auto-linking external references
guide.
The ARIA repositories share a common set of resources to reduce redundancy. Shared resources are in the aria-common repository, and copied to a "common" folder in this and other ARIA repositories. It is important to make edits in the aria-common repository; making edits in the common folder of another repository will allow the edits to be overridden.
Todo: special characteristics table classes etc. used by the script
Official editors' drafts are published to [https://w3c.github.io/aria/]. This URI is suitable for public references. Documents published to that location are static snapshots from the Respec processor. This is to minimize load time for consumers of these drafts. Editors' drafts are automatically updated (if there are no errors) by a Travis-CI service run when commits are pushed to the master branch.
An extension spec is one that defines additional roles, states, and / or properties that augment the collection defined in the core ARIA specification (aria/aria.html). Extension specs must be built in conjunction with the W3C ARIA WG if any new roles are to be in the default vocabulary space (http://www.w3.org/1999/xhtml/vocab).
When building an extension spec, use the boiler plate provided in aria/template.html as a basis.
Note that this template uses the aria/script/ariaChild.js script. That script knows how to incorporate information from the core ARIA specification into the extension spec so that new roles, states, and properties are well integrated into the overall ARIA taxonomy.
The ariaChild.js script relies upon an input script (aria/script/roleInfo.js). As of today, that file is not automatically generated. If you want to ensure the file is up to date, access the core ARIA spec with the special query string "#saveRoles" from a browser on a client that has write access to the copy of the extension spec you are editing. When the dialog appears, click the save button and tell your browser to save the roleInfo.js file into the aria/script directory.
The scripts to support extension modules are stored in the aria-common repository. Therefore, updates to roleInfo.js must be saved and committed to that repository, even though they are generated from content in this repository.
In general, but particularly when preparing documents for TR publication, editors should check the following quality points:
There was some automated checking available, previously run by XSLT. This feature may be restored. This report helped determine the following potential issues: