Important note: This Wiki page is edited by participants of the EOWG. It does not necessarily represent consensus and it may have incorrect information or information that is not supported by other Working Group participants, WAI, or W3C. It may also have some very useful information.


From Education & Outreach
Jump to: navigation, search

Related: W3C Manual of Style


This WAI Style Guide sets guidelines for writing material for the WAI website. The purpose is to support consistency and support better translations. This is a living document that will be updated.

Please send any questions or comments to


WAI content should convey these qualities:

  • Knowledgeable, Authoritative, Reliable, Credible
  • Clear, Straight-forward
  • Welcoming, Encouraging, Inspiring
  • Modern, Up-to-date

Different types of documents have different tone, for example:

  • Technical standards and most Policy resources: formal
  • Standards support documents (WCAG Techniques, Understanding SCs, etc.): narrative tone, conversational
  • Stories of people with disabilities and accessibility intro documents: friendly, explanatory tone that invites exploration and engagement
  • Tutorials and how-to documents: concise and direct, also supportive and encouraging

Generally avoid humor since it often does not work internationally.



  • comma before conjunction, e.g.: apples, oranges, and bananas.
  • punctuation outside quoted terms
    • e.g.: This accessibility requirement is sometimes called sufficient "color contrast"; however, that is incorrect — technically it's "luminosity contrast".
    • (Note: Many American-English style guides, including the Chicago Manual of Style, recommend periods and commas inside quotes. Most British-English style guides recommend punctuation outside quotes. Coding requires proper nesting. Because most of our audience is more focused on proper code syntax than on America-English syntax, we chose punctuation outside quoted terms.)
  • Commas after introductory prepositional clauses, especially in sentences that are a bit long or complex.
  • Comma (or colon) after "for example," and "e.g.,". Note: for Recommendations and other formal docs, probably better to use "for example" instead of "e.g.".
  • Titles, headings, labels, menu items do not have terminal punctuation unless a question mark is required.
  • "For example," OK as own sentence, even if not full sentence. This is generally easier to read, even though not formally correct.
    Usually best:
    Ensure that your design can accommodate visible alternatives for images and media as needed. For example, links to transcripts of audio, text with icons and buttons, and captions and descriptions for tables or complex graphs.
    Only when need to be grammatically correct:
    Ensure that your design can accommodate visible alternatives for images and media as needed; for example, links to transcripts of audio, text with icons and buttons, and captions and descriptions for tables or complex graphs.

See Lists section for punctuation of list items.


  • Titles, h1s, and menu items use headline-style capitalization (the first letter of major words is capitalized), unless otherwise noted below
    • For EOWG Resources and most WAI pages:
    • For WCAG Understanding and Techniques documents:
      • All headings use headline-style capitalization
      • Exception: WCAG Techniques titles and h1 use sentence-style capitalization (since they are long phrases)
  • web/Web capitalization
    • web - lowercase as adjective, such as "web accessibility", "web page", "web application"
    • Web - can capitalize when referring to the World Wide Web, or leave lower case for consistency within a document
  • WCAG success criteria (lowercase)
  • Working Groups, Task Forces
    • XYZ Working Group - capitalize when talking about a specific working group, including, "the Working Group" without the name of the WG in the phrase.
    • working groups - lowercase when talking generically about working groups. However, OK to capitalize if seems better for consistency within a doc.
    • if in doubt, capitalize.
    • same for Task Forces.
  • URI (not URL) - based on W3C Manual of Style

See Lists section for info on capitalization of list items.


Spelling: We generally use US spellings. One exception: "ageing". (ageing background)

  • dialogue / dialog
    • dialog for dialog box
    • dialogue for conversation, e.g., audio in transcriptions, captions, subtitles


  • Punctuation — no punctuation after bullet/list items that are not complete sentences. (except in very formal documents)

    This include things like:

    • people using assistive technology
    • people using adaptive strategies
    • people using other things

    instead of This includes things like:

    • people using assistive technology,
    • people using adaptive strategies,
    • people using other things.
  • Capitalization — can be either lowercase or initial caps, depending on the type of information. Most are lowercase — generally:
    • if the bullets could be in a single sentence, then lowercase
    • if it is a heading (e.g., in-page contents), then initial caps
    • if the bullet item is a full sentence or multiple sentences, then usually initials caps

    This includes people using:

    • assistive technology
    • adaptive strategies
    • other things

    The sections below address:

    • Assistive technology that people use
    • Adaptive strategies that people use
    • Other things that people use
  • Spacing — optionally, no space before lists, e.g., in Contacting Orgs
    Style the p and ul or ol like this:
    <p class="listintro">...such as:</p>
    <ul class="listwithp">

    to get:

    This includes people using:
       * assistive technology
       * adaptive strategies
       * other things

    instead of:

    This includes people using:
       * assistive technology
       * adaptive strategies
       * other things

One word, two word, hyphenation

  • website - one word

People first language

  • Use: "people with disabilities", "people with physical impairments", "people who are blind", etc.
  • Generally avoid: "disabled people," "the disabled," "blind people", "handicapped," etc.
  • NOTE: WAI understands that some groups, especially advocates for blind people, disagree with this language construction. For that reason, WAI provides a degree of editor's discretion. WAI trusts editors to use language respectfully and does not insist on people-first in every instance. Rather we defer to the editor's sense of narrative flow, clarity, and plain language.

Editorial style

Simple language

Use simple, clear language as appropriate for the content. For most resources, try for lower secondary education reading level.

Avoid "wall of text', that is, dense paragraphs without anything breaking them up. Use bullets, graphics, and headings.

More info:

Active Voice

Use active voice, that is, the subject of sentence performs the action.

Avoid passive example:


Revised to be active:


Specific words

  • "for example" instead of "for instance" usually
  • "conformance" is a complicated word. (readability comment) Consider using a simpler form ("conform"), or "meets", or another word when appropriate. When need to use "conformance", consider defining it.

Instead of "conformance":

Ensure conformance to WCAG.


Ensure that your application meets WCAG.

  • Avoid "but" and word positively.

Avoid "but":

This benefits not only users, but also stakeholders.


This benefits users, and also stakeholders.

Document links in sentences

  • whenever feasible, put linked documents at the end of sentences. Several EOWG folks feel this improves reading flow for visual readers, makes it easier for screen reader users to know where the document title ends, etc. For example:
For guidance on making the whole Web accessible, see Awesome Document on Web Accessibility.
instead of: See Awesome Document on Web Accessibility for guidance on making the whole Web accessible.

Front-load conditional sentences

For example, instead of:

Use empty alternative text when an image is purely decorative.


For images that are just decorative, use empty alternative text.

Use strong action statements

For example, instead of:

Try to write link text so that it describes the content of the link target in a meaningful way.


Write link text so that it describes the content of the link target in a meaningful way.

Simplify sentence construction

For example, instead of:

Some audiences, such as in doctors or engineers, require complex terminology, but still seek opportunities to simplify.


Use language suited to your audience needs, especially where the topic might include complex terminology.

Remove superfluous words

For example, instead of:

Provide text alternatives for all images.


Provide text alternatives for images.

Avoid subjective adjectives

For example, instead of:

Policies will vary greatly across organizations.


Policies will vary across organizations.

Document Titles


Two options:

  • Option 1 (descriptive) – Name the article with a descriptive name so that people will know what the article is going to be about before they start reading it.
  • Option 2 (creative) – Name the article with a creative, catchy name so that people are intrigued to start reading it to find out what it is about.

Neither is preferred, however “how to” articles lend themselves better to Option 1, more general articles to Option 2.

General Good Practice

Abbreviations and acronyms

  • Write out abbreviations and acronyms the first time you use it on a page. Then you can use the abbreviation or acronym for all other references. WCAG Technique G97
    • First use: World Wide Web Consortium (W3C)
    • Second use: W3C
  • If the abbreviation or acronym is very well known by the target audiences (e.g., HTML), you don't need to spell it out and can just use <abbr>. If in doubt, spell it out.
  • Don't use the <abbr> element for all instances of the abbreviation or acronym.


  • Use words for numbers that start a sentence, and for numbers up to one hundred (guidance based on documents where descriptive or narrative text is predominant and numbers are not the significant focus)
  • Used a mixture of words and numbers when mixing uses of numbers, such as "Enter two 3s."
  • Numbers over 3 digits get commas:
    • 999
    • 1,000
    • 150,000
  • Write out big numbers in full. Don’t use abbreviations (e.g. 1,000 not 1 k).

Appendix: Edit Examples

  1. Instead of:
    WAI materials should be created and edited with emphasis of brevity and use of bullets over paragraphs of text. Graphics, icons, and other such cues may be used to create visual anchors and break up presentation to avoid subjecting users to a "wall of text".
    Edit to active voice:
    Avoid "wall of text", that is, dense paragraphs without anything breaking them up. Use bullets, graphics, and headings.
  2. Instead of:
    Your feedback to an organization can help improve the accessibility of websites for you and many other people who use the websites. Website owners have many priorities for changes and improvements, and the more an organization hears about accessibility from people who use their website, the more likely it is that accessibility will become a higher priority. Positive feedback is useful, as well as critical feedback.
    Reduce 66 words to 30.
Your input helps organizations understand the importance of accessibility to you and other site visitors - understanding that may encourage them to prioritize accessibility improvements. Positive feedback can be especially useful.


Language Tools

Important: W3C does not endorse specific tools. These are just tools that some editors have found useful. No endorsement implied!

reading level and "accessibility"

The word "accessibility" generally increases the automatically-calculated reading level of WAI documents; however, give our topic and audience, it functionally does not increase the reading level that much.

As an experiment, I took the main content of Accessibility - W3C and replaced the 33 instances of "accessibility" with "dog" and the reading level reported by HemmingwayApp went down a grade level. Other content with another tool yielded the same results: 1 grade-level lower.

ageing background

Background from Judy:

This word is slightly different than others with different UK and US spelling--specifically, people who haven't see the "other" version previously sometimes don't seem to recognize the word, rather than just thinking that is is spelled oddly, like color and colour. So what we did for a while was to use one followed by the other in parentheses the first time.

In principle the solution should be to switch to the US spelling, but when we used only that we got complaints and a bit of derision from the Europeans, and then vice versa.

...If you want to swap back I just recommend putting the UK spelling in parens.


Listed below are substantive things that have changed since October 2018. It does not include all additions or minor tweaks.

e-mail -> email

Proposed change from hyphenated "e-mail" to not hyphenated "email".

Rationale: Chicago Manual of Style, AP Style Guide, and several others.

Con: Maybe harder for some people with language processing disabilities and non-native speakers to process it without the hyphen.

Document Info

Status: Fairly stable. Updated periodically.

Editors: Shawn Lawton Henry, Sharron Rush. Contributors: Kevin White and participants of EOWG. Developed by the Education and Outreach Working Group (EOWG).

Questions and feedback welcome to (a publicly archived list)