APG Editorial Style Guidelines

Style conventions for the ARIA Authoring Practices Guide

When writing content for the APG, please use the following conventions.

Expressing Role, state, and property values

• Use a prepositional phrase and code tags.
• Do not quote the value.

Examples:

• set role to listbox
• aria-expanded changes to false

Using the KBD tag

Include modifier and key name in a single tag. example: Control + Left Arrow

Each ke should have its own tag. Example: Up Arrow and Down Arrow Not: Up and Down Arrow

Describing keyboard behaviors

When naming the keys:

• Put the complete name, including modifiers, in a KBD tag.
• Capitalize each word of the name.
• Include spaces between words of the name rather than writing a single camel case word.

Examples:

• Tab
• Shift + Tab
• Control + Shift + Up Arrow

When expressing the behavior of a key:

• Use present tense.
• State what happens in the UI with a clear action and object of that action Examples:
• "moves focus to the next element"
• "activates the button that has focus"
• "executes the command associated with the button" Do not word like:
• Up Arrow: will move to the previous item.
• Not: Up Arrow moves you up.

When making a list of key behaviors in a design pattern:

• Formatted as a list.
• each list item starts with a single key name followed by a colon.
• Do not include the tab key in the list of keys unless tab key is part of the widget operation (e.g., multi-thumb slider). Tab may or may not move focus in and out of a widget; it depends on context.
• Example: Up Arrow: moves focus to the previous item.