I think this is good but to be effective we will need to to define how the keyboard format is specified. Do you have a spec. for that?

Dominic, I will help push for its inclusion if you can provide me with that.

I added some proposed text that defines the keyboard shortcut formatting here:

https://www.w3.org/WAI/PF/Group/track/issues/711

@Dominic, adding you proposal here, as PF tracker is currently member only.

Possible names for this attribute: aria-key, aria-shortcut, aria-keyboardshortcut - or it could be plural: aria-keys, aria-shortcuts, aria-keyboardshortcuts

Proposed text:

**aria-key (property)**

Indicates keyboard shortcuts that can be pressed to activate widgets, such as a button, link or menuitem. Any widget that has a default activation behavior when clicked can have a keyboard shortcut.

Adding the aria-key attribute to an element does not change the behavior of the user agent by mapping the specified keyboard shortcuts to the triggering of the element's activation function. It is still up to the application to implement support for the keyboard shortcuts. The aria-key attribute exposes the fact that these shortcuts exist so that assistive technologies can communicate this information to users.

Keyboard shortcuts are assumed to be global. If a button is present in a document and it is visible and enabled, and it exposes a keyboard shortcut, it is assumed that as long as the document has focus, pressing that keyboard shortcut will activate that button. If the button or other element is not currently available to be activated normally, for example because it's currently invisible or hidden, or explicitly marked as disabled, that implies that the keyboard shortcut is unavailable too.

The value of the aria-key attribute is a space-separated list of keyboard shortcuts that can be pressed to activate the command widget. Each shortcut consists of one or more tokens delimited by the plus sign ("+") representing zero or more modifier keys and exactly one non-modifier key that must be pressed simultaneously to activate the given shortcut.

Modifier keys must be specified exactly according to the DOM Level 3 KeyboardEvent key Values spec: http://www.w3.org/TR/DOM-Level-3-Events-key/ - for example, "Alt", "Control", "Shift", "Meta", or "AltGraph". Note that Meta corresponds to the Command key on Apple computers.

The valid names for non-modifier keys are any printable character such as "A", "B", "1", "2", "$", "Plus" for a plus sign, "Space" for the spacebar, or the names of any other non-modifier key specified in the DOM Level 3 KeyboardEvent key Values spec: http://www.w3.org/TR/DOM-Level-3-Events-key/ - for example, "Enter", "Tab", "ArrowRight", "PageDown", "Escape", or "F1".

When modifier keys are part of a shortcut, they must come first. The non-modifier key is required and must come last. The order of the modifier keys is not otherwise significant, so "Alt+Shift+T" and "Shift+Alt+T" are equivalent, but "T+Shift+Alt" is not valid because all of the modifier keys don't come first, and "Alt" is not valid because it doesn't include at least one non-modifier key.

When specifying an alphabetic key, both the uppercase and lowercase variants are considered equivalent: "a" and "A" are the same, as are "ü" and "Ü".

When specifying a key on the keyboard that changes when you hold down a modifier key other than an alphabetic key, you must specify the unmodified key name. For example, on most U.S. English keyboards, the percent sign "%" can be printed by pressing Shift+5. The correct way to specify this shortcut is "Shift+5". It is incorrect to specify "%" or "Shift+%". However, note that on some international keyboards the percent sign may be an unmodified key, in which case "%" and "Shift+"%" would be correct on those keyboards.

If the key that needs to be specified is illegal in the host language or would cause a string to be terminated, use the string escaping sequence of the host language to specify it. For example, the double-quote character can be encoded as " in HTML.

Examples of valid keyboard shortcuts include:

"A"
"Shift+Space"
"Control+Alt+."
"Ctrl+%quot;"

Examples of valid values for the aria-key attribute, which can include more than one space-delimited shortcut, include:

aria-key="Alt+Shift+P"
aria-key="/ Ctrl+F"
aria-key="Meta+C Meta+Shift+C"

**Characteristics of aria-key**

Used in Roles:
command
checkbox
option
gridcell

Inherits into roles:
button
columnheader
link
radio
rowheader
menuitem
menuitemcheckbox
menuitemradio
treeitem

Value:
string

How should conflicts with native keystrokes be resolved?

For example, if the author specifies "Ctrl+S" does it override the native "save" option, does it give the user a choice, or is it ignored?

For example:

    document.addEventListener('keydown', function(e)
    {
        console.log(e.keyCode);

        if(e.metaKey && e.keyCode == 83)
        {
            console.log('Meta+S');
            
            e.preventDefault();
        }

        if(e.metaKey && e.keyCode == 32)
        {
            console.log('Meta+Space');
            
            e.preventDefault();
        }

    }, false);

So I'm using a Mac with QuickSilver installed and I already have Meta+Space configured as the QuickSilver shortcut, as well as pre-existing native Meta+S for "save page". In the firs case, preventDefault overrides the native save option and the keystroke can be handle by my application. But in the second case, the system action overrides the scripted action and it doesn't fire at all. There are probably also edge cases where both will fire.

So although aria-key doesn't do anything, doesn't it still need to know in advance whether the scripted keystroke will be honoured, so that it can communicate that information to the user?

It's a good question and in fact it might be a great idea for there to be a spec allowing web developers to query what modifier keys are available, what keyboard shortcuts are unavailable, and which ones are available but would necessarily shadow an existing browser shortcut.

However, I think this is out of scope for ARIA and it's really orthogonal to this proposal. Web developers are already implementing keyboard shortcuts and working around browser-specific and platform-specific limitations, this just gives them a way to expose this information to assistive technologies in a well-defined, structured way rather than only as text.