Best Practices

Before starting a project, get to know the full list of requirements for WCAG 2.1 AA. Following the best practices below will help you satisfy this standard.

Page Elements


Both sighted and blind users navigate by scanning through links. Make sure your hyperlink text always explains where your user is going. Avoid link labels like “Click here,” which don’t give any information to screen reader users skimming through links.

When styling your links, do not use color alone to visually distinguish links from static text. Links should be underlined and bolded so that users who are color blind can identify them.

Page Titles

Each page should have a unique page title that tells the user where they are in the site map. For instance: “NYC Jobs | City of New York” or “Photo Gallery – MOPD”.

To test whether or not a page has a title, check the text that appears on the browser tab bar.


Sighted users navigate web pages by skimming text, unconsciously using headings, links, and formatting to pick out the information needed. People who rely on screen readers still need to skim, which headings help with.

With properly formatted headings, people using screen readers can skip to page titles, relevant sub-headings, or search results with just a few keystrokes. Without headings, they would have to start at the top of the page and listen to all of the navigation links, advertisements and other content until they find what they are looking for.

Be careful when using headings, though. Using too many headings may confuse both sighted and blind users. So, try to strike a balance between adding enough headings to aid in skimming the content, while not adding so many that the visual and screen reader experience of the content becomes overwhelming.

Note: Making the font size bigger and changing the style to bold does not create a heading. Proper heading tags require formatting like this: <h1>PageTitle</h1>.

Use headings (<h1> through <h6> HTML tags) in order, without skipping any. Below are examples of which heading levels to use and when.

  • h1 headings: Main page topic. Try to only use one <h1> per page. This heading typically appears at the top of the content area. Examples include, “Welcome to the Mayor’s Office for People with Disabilities,” “About MOPD” and “Contact MOPD.”
  • h2 headings: Subsection titles, such as the beginning of an area that contains articles, Programs, or Search results. Examples include, “Latest News,” “Showing 10 of 30 Search Results” and and “Programs and Initiatives.”
  • h3 headings: Article titles, program titles, search results, and other subsections.
  • h4 – h6 headings should progress in consecutive order, as subsections of the previous heading.

Because screen reader users often use headings to navigate content, you can make non-heading elements behave as headings in situations where using <h#> tags might be inappropriate. An element can be recognized as a heading by adding the role=“heading” and aria-level=“#” attributes, where the aria-level number would be the desired heading level.

Read more about Accessible Rich Internet Applications (ARIA) below.


Tables can be difficult for screen readers to interpret, and should not be used to set the layout of a web page. Types of data that belong in tables include primarily numerical information, such as the number of cars in service or the number of calls to 311.

In order to make tables accessible, the header cells need to describe the data cells they represent.

18F’s Accessibility Guide offers useful example code for accessible tables.


When creating form fields, it’s important to insure that they will be accessible to assistive technologies. All form fields should have the following:

  • Text labels
  • Required fields should have text alternatives such as use of * to mark required fields
  • Key board access: all fields need to be in the keyboard tab order
  • Error validation: all errors should have text alternatives
  • Form fields that have an image as a label should have proper alt-text

Checkout one of the contact forms from as an example.

For further guidance refer to the Webaim Creating Accessible Forms page.

Bold and Italics

Screen readers generally do not announce when text is emphasized using <b> or <i> tags. Instead, use text alternatives. Below are some examples.

  • Important: application deadline is due on August 1st.
  • **application deadline is due on August 1st**


Carousels and image slideshows shouldn’t auto-play. Let users start, pause, and skip screens.


Color Contrast

The color contrast—the contrast between your text and background colors—must be high enough so those with low-vision can distinguish the colors. Text and any element that is not purely decorative should have a ratio of 4.5:1 or greater with the background.

The WebAim Color Contrast Checker lets you check the accessibility level of different color combinations at different sizes.

Use of Color

Because individuals with low vision or colorblindness can have a hard time distinguishing colors, you should not use color alone to signify something or get users’ attention. (Screen readers also will not announce color.)

When you use color to call attention to something, combine it with a shape or pattern (such as an asterisk or warning icon). Without additional imagery, some users will not be able to understand the content properly.

Keyboard Access

A user must be able to get to every link, button, form field, and other content that may even be hidden using only the tab button on their keyboard. Types of hidden content include that which appears within expand/collapse functionality, carousel items that aren’t visually displayed, and or tool-tips. In general, all content that’s accessible to mouse users should be accessible to keyboard users as well.

Focus Indicators

The elements that users can navigate between using keyboards—links, buttons, and form fields—are automatically given a “focus indicator” (typically visible as a border when selected) by the browser. This is what enables keyboard access.

Focus indicators can be hidden by applying the CSS outline:0 or outline:none. Avoid using this styling.



All pictures, logos, and images must be described for those using screen readers. You can do this using alt-text. Alt-text descriptions don’t appear visually, but are read by a screen reader. Example code is below.

<img src="earthday.gif" alt="New Yorkers attend an Earth Day recycling event in Union Square.">

A good alt text focuses on the meaning of the image but is also succinct. They should be short and to the point. When writing alt-text, ask yourself the following questions to come up with a description:

  • Where is this taking place? It could be specific such as Cityhall or it could be general such as outside in a park.
  • When is it taking place? It could be specific such as the Fourth of July or The Sappolin Awards. It could also be general such as during the day time or during the evening.
  • Who is in the image? It could be a notable figure such as Mayor De Blasio. It could also be general such as a group of people with and without disabilities.
  • What are they doing? Are they smiling, shaking hands or marching at a rally?
  • Why are you posting this image? What point is the image conveying?

If the image is functioning as a link, then explain what clicking the link will do. For example, if an image links to a related press release, then the alt-text would be “Read the Disability Pride Parade press release.”

Please remember to spell check your alt text before adding it to your website, document or social media post.

For further guidance on how to describe images, refer to the MOPD Social Media Guide.



Links and buttons that activate videos must be clearly labeled. The link itself should have the word “watch,” “view,” or “video” in it, or the text around it should indicate that it’s a video.

Watch the State of the Union address.

Video Controls

Video controls must be accessible by screen readers and keyboards. This means that all controls need to be in the keyboard tab order and they must have text labels. When a page loads, videos should not play automatically. Once the video is playing, the controls should not disappear because screen reader and keyboard users will not be able to stop or pause the video. Avoid using flash based video players. Some popular video players that are accessible include Youtube and Vimeo.

Captioning and Transcripts


Open or Closed Captions should be available to make your videos accessible to Deaf or hard of hearing audiences. Closed captions can be turned on and off. Open Captions are embedded into the video and are always on. When creating captions for a video, include the following:

  • Dialogue
  • Sound Effects
  • Music

When designing captions, follow these rules:

  • Make sure that the text is easily viewable against the background of the video. We recommend white font with a thick black stroke or on a black background strip.
  • Whenever possible, only caption one sentence at a time. If the sentence is too long, break it up with a double dash (“–”) and complete it in a new caption.
  • When characters are speaking offscreen, include their name before the dialogue. For example, [Narrator]: Once upon a time…
  • Sound effects should be in parentheses. For example, (Loud explosion)
  • Music should be surrounded by music notes. For example, ♬ Happy Birthday ♬

To learn more about captions, download the Accessible Social Media and Videos Guide.

Add these sections after the captions section.

Audio Description

To make your videos accessible to the blind and low vision communities, add audio descriptions. Audio description is an extra narrative track added to a video that describes what’s taking place visually on the screen.

When describing a video, you don’t need to explain every single visual element. Instead, focus on the important moments, and be succinct.

Include information such as:

  • Scene time and settings: For example, “Nighttime in NYC ” or “In a courtroom”
  • Characters: Use their names whenever possible. If they don’t have one, use an identifying feature, such as “the person in black”
  • Whenever characters enter or exit a scene
  • Important character actions
  • Any events that are important to the plot

Below are three examples of audio described videos.

MOPD Becky Curran – NYC at Work Video Profile:

DOT Cycle Eyes:

NYCEM Ready New York –  A well planned escape:

To learn more about describing peerformances, presentations and news segments download the MOPD Audio Description Guide.


Transcripts, which can be read without having to play a video, are useful for people with hearing disabilities and those in noisy environments. They also allow your content to appear in Google searches. When creating a transcript, follow these tips:

  • Include all dialogue
  • Start each quote with the name of the speaker and the time that quote starts in the video

Descriptive Transcripts

To include folks who are deaf and blind, add descriptions in your transcript. Include information about important visual events, introduce characters and new scenes. Refer to the audio description section above for more guidance.


Avoid using content that flashes more than three times per second. Flashing and strobe-like features are dangerous for users with seizure disorders and distracting for other users. If creating GIFs, make sure they don’t flash more than three times per second either.

ARIA and Coding for Accessibility

One of the keys to building accessible web pages is making sure headings, lists, links, forms and other content is using standard HTML 5 tags. However, there is some complex content that cannot be accessible using standard HTML elements alone. To further enhance accessibility, ARIA (Accessible Rich Internet Applications) can be used. It is a set of attributes that can be applied to code to enhance accessibility. Examples include, labeling items, hiding irrelevant content, announcing content that has been added to the page as well as labelling form fields as required. Learn more about ARIA.

ARIA Landmark Regions

ARIA landmark regions can be used to increase efficiency of navigation for screen reader users. Common areas such as the banner, navigation, main content and footer can be labelled as such. This will give screen reader users the ability to understand where they are on the page as well as the option to skip from one region to another using screen reader keyboard shortcuts. Checkout the Landmark Regions WAI Tutorial to learn more.

ARIA Landmark Regions with Custom Labels

Sometimes there are multiple navigation sections or levels on a website. Aria-label and aria-Labeledby can be used to create unique labels for regions such as “Primary Navigation,” or “Secondary Navigation.” Note: if your region starts with a heading, aria-labelledby can be used to label the region after the heading. If the region does not start with a heading, aria-label can be used to create a label for the region. Find out more about labeling regions.

Pop-Ups and Modal Dialogues

Pop-ups and modal dialogues can be tricky because they add new content to the screen without loading a new page. This can confuse a lot of screen reader users if they are not properly alerted of this new content. In order to insure accessibility, keyboard and screen reader focus must shift to any new dialogues or pop-ups that require the user to perform an action. Below are two options on how to do this.
Alert and Message Dialogues
How to make Modals better for everyone – Smashing Magazine

Aria-live and Dynamic Content

Much like pop-ups and modal dialogues, sometimes messages or alerts appear on screen without loading a new page. For messages that do not intend to take the user away from their current task, aria-live attribute can be used to have assistive technologies announce the message. This could be used for announcing errors when filling out a form. Learn more about using the aria-live attribute.

The World Wide Web Consortium (W3C) offers additional context, background, and instructions for using ARIA.

Plain Language

When we write our content, we can make sure that it is readable by a wider audience by using plain language. Plain language is communication that your audience could understand the first time they read or hear it. It makes text more understandable to people with cognitive disabilities as well as people with limited English proficiency. Try to use shorter sentences and simpler words. It is recommended to write text at a fifth grade reading level. You can learn more about plain language in our content section or the Federal Plain Language Guidelines.