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.
• Link to the role definition in the ARIA spec the first time the role is used within the section
  • set class to role-reference
  • set href to #[role name] eg. href="#note"
• Link to state and property definitions the first time they are used in a section
  • set class to property-reference
  • set href to #[property name] eg. href="#aria-owns"

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
• Capitalize each word of the name.
• Include spaces between words of the name rather than writing a single camel case word. Example: Control + Shift + Up Arrow not Control + Shift + UpArrow
• Each key should have its own tag. Example: Up Arrow and Down Arrow not Up and Down Arrow

Describing keyboard behaviors

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"
• Good phrasing: "Up Arrow: will move to the previous item."
• Bad phrasing: "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.