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: moves focus 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.

Experimental examples

The APG site build process provides special treatment for example pages that document an ARIA feature that is not yet included in a W3C Recommendation (final standard), i.e., the feature is still a work in progress. APG pages with experimental content provide the accessibility community with an example it can use to develop support for the new feature while clearly indicating the content is intended to be used only for that purpose.

The design goals of the APG support for experimental content are:

1. Typical users will:
   • not unintentionally discover experimental content.
   • Not mistake experimental content for normal content
2. Anyone who needs to locate experimental content will be able to do so.

To achieve these goals, the treatment includes the following features:

1. Providing a different example usage warning that is open instead of closed by default under "Read This First".
2. Including the word "Experimental" in the page title and the first 3 headings.
3. Excluding the experimental content from the normal index tables and instead listing it separately at the bottom of the index page in a separate section.
4. Not providing links to experimental example pages from pattern pages or normal example pages.

Editorial requirements when adding anexperimental example page include:

1. Add the attribute data-content-phase="experimental" to the main element.
2. Use the word "Experimental" in the page title tag and H1 element.
3. Change the heading "About This Example" to "About This Experimental Example".
4. In the about this example section, lead with the objectives of the experimental content and estimated high-level timeline for maturity of the feature, if successful.
5. Change the "Example" heading to "Experimental Example".
6. Ensure that other pages that are not also experimental do not link to the experimental page.

Editorial requirements when changing an experimental example page into a non-experimental page:

1. Remove the attribute data-content-phase="experimental" to the main element.
2. Remove the word "Experimental" from the page title tag and H1 element.
3. Change the heading "About This Experimental Example" to "About This Example".
4. In the about this example section, revise the content to remove language describing the example or its features as experimental.
5. Change the heading "Experimental Example" to "Example".
6. Add links to the page from the related pattern and similar examples.