WCAG 2 style guide

Any updates to WCAG guidance should follow the WAI Style Guide and W3C Manual of Style, which specifies Merriam-Webster's online dictionary as the primary source for spelling, and the Chicago Manual of Style as the arbiter of style (online subscription necessary, but pick up a used copy in used bookstores anywhere).

For commonly used constructs not covered in the WAI guide, the following style and word usage guides have been started. These should be considered draft; they have not been vetted or adopted. However, they follow the most established conventions currently used in documents.

Style

Code

Class is not necessary for inline code

The only thing needed is <code> tags (with no attributes).

Class in not typically needed for code blocks

Use <pre><code>...</code></pre> to get syntax highlighting on code blocks.

Highlight.js typically detects the language correctly by itself. If it doesn't, you can force it by adding e.g. class="language-html" or class="language-javascript" to the code tag.

To avoid applying syntax highlighting to a code block, use only <pre> (without <code> inside).

Figures and illustrations

In figure captions and references, spell out the word figure, numbering illustrations sequentially within the document. Separate the figure number from the captions only by a space, then capitaliz the first word of the caption. Captions are generally written as sentences with terminating punctuation. Do not use a period if the caption is only a sentence fragment.

Example

Figure 4 A customized checkbox with light grey check (#E5E5E5), which has a contrast ratio of 5.6:1 with the purple box (#6221EA)

References

Links to definitions

If there is a definition, simply enclose the definition term in anchor tags and it will be properly formed on publish, e.g., <a>web page</a>

See https://github.com/w3c/wcag#definitions for more details.

Outside references in Related resources

The link should use the same wording as the target title and add in the source in parentheses, where useful. For instance:

Web fonts (MDN)

Archived references in Related resources

Any external links to the wayback machine or other preserved versions of pages should have "(archived page)" appended in addition to the source, where used, e.g., "Web fonts (MDN, archived page)"

Word usage

Since the terms section of the W3C guide is sparse, WCAG-specific word usage is being begun here.

S

success criterion, success criteria

Both the singular and plural terms should only be used capitalized in combination with the number of a success criterion, which frequently occurs as part of a link name (e.g., "Refer to Success Criterion 2.2.1"). Where either term stands along (without the number), use lower case (e.g., "This success criterion is...")

W

web

lowercase when used by itself, including as an adjective (such as "web accessibility", "web page", "web application") and a noun ("making the web accessible"). See

website, but web page