Table of Contents
|Table of Contents|
Provide Alternative Description for Images
Provide meaningful Alt text for images. This helps users who rely on assistive technology such as a screen reader to understand the meaning of the image. The screen reader will read out the ALT description to the user.
Example: <img src="../images/womens_history_month_hero_image.png" alt="View the 2019 Women's History Month Opening Ceremony">
Examples of descriptive/meaningful Alt text
alt=”About the Neighborhood Emergency Response Team
alt=”Mayor Announces Budget Plan for 2019”
Examples of non-descriptive Alt text:
Decorative images that don’t present important content should have null alt text. Example: (alt=""). Screen readers will ignore these images all together.
Here are some general guidelines to follow when providing Alt text. Alt text should:
Be succinct. Typically no more than a few words or a short sentence.
NOT be redundant or provide the same information as text within the context of the image.
NOT use the phrases "image of ..." or "graphic of ..." to describe the image. It is usually apparent to the user that it is an image.
For complex diagrams, charts, maps and graphs a text based equivalent needs to be provided either within the context of the page, such as in an adjacent data table. The alternative text can also be provided by linking to a separate web page that provides the longer description of the complex image.
Additional Information on Writing Effective Alt Text
Color and Color Contrast
Color Contrast Between Text and Background Color
Provide sufficient color contrast between foreground and background, text and background color.
The contrast ratio between text and background, using regular body text, should be at least 4.5:1.
Large-scale text (24 pixels or 18 pixels bolded) should have a contrast ratio of at least 3:1.
Test your contrast level using this color contrast checker for WCAG AA compliance https://webaim.org/resources/contrastchecker/
Color Contrast Between a) Link Text and Background Color and b) Link Text and Surrounding Body Text
There should be a contrast ratio of at least 4.5.1 between link text and background color. This applies to regular body text (or 3:1 for large text) .
There must be a 3.1 contrast ratio between link text and surrounding text.
Use this link contrast checker to test color contrasts for links https://webaim.org/resources/linkcontrastchecker/
When designing for color blindness, make sure that colors are not your only method of conveying important information.
Use this filter to test web pages for color blindness https://www.toptal.com/designers/colorfilter/
If the purpose of posting the content is to communicate something about the colors in that image or web page, then it is important to provide some other way of understanding the information.
Reds and greens are often indistinguishable
This is not normally a problem except in cases where the colors convey important information. Under these circumstances you will need to either change the content or graphic or provide an additional means of obtaining the same information. For example, provide an explanation in the text itself.
Color and Alert/Error Messaging
Don’t rely on color to convey critical information such as alerts and error messages. See more info about this under the Alert/Error Messaging section.
Create a Logical Reading Order for Sighted and Vision Impaired Users
Page Structure and Headings
Create a logical reading order by using appropriate headings, <h1> <h2> <h3> <h4> <h5> <h6>.
Build the structure of the page using semantic markup. Markup that has meaning to browsers and screen readers. A web page should be able to stand on its own without the help of a style sheet.
Sighted users often scroll the page quickly and look for headings to get an idea of the structure and content of the page. Screen reader and other assistive technology users also have the ability to navigate web pages by heading structure, assuming true headings are used (as opposed to text that is styled to be big and/or bold). This means that the user can view a list of all of the headings on the page, or can read or jump by headings, or even navigate directly to top level headings (<h1>), next level headings (<h2>), third level headings (<h3>), and so on.
Do not use text formatting, such as font size or bold to give the visual appearance of headings - use actual headings (<h1> - <h6>) for all content headings
There should only be one <h1> heading per page and should be applied to the page title to indicate to the user that this is where the content area begins.
Pages should be structured in a hierarchical manner.
Proper nesting of headings.
HTML lists - <ul>, <ol>, and <dl> - also convey a hierarchical content structure.
Lists should be used to display actual list items. They should not be used for layout purposes.
Skip Repetitive Navigation and Provide Skip to Main Content Link
This allows screen reader users to skip repetitive navigation menu links and go straight to the main content area.
Make sure a “skip to main content” link has been incorporated to all site pages.
The link also needs to be visible when using the tab key for keyboard users.
The link should be placed at the very top of the page and link to the beginning of the main content area.
Create Accessible Data Tables for Screen Reader Users
The purpose of data tables is to present tabular information in a grid, or matrix. Someone that cannot see the table cannot make the visual association between data in the table and their appropriate row and/or column headers. So proper markup must be used to make a programmatic association between elements within the table. When the proper HTML markup is in place, screen reader users can navigate through data tables one cell at a time, and they will hear the column and row headers spoken to them.
Provide table headings
Provide a table caption that describes the content in the table
Avoid using tables for layout purposes
<table> <caption>2018 Asset Limits and Requirements Per Household</caption> <thead> <tr> <th> </th> <th> </th> </tr> </thead> <tbody> <tr> <td> </td> <td> </td> </tr> </tbody> </table>
Forms need to be accessible to both screen readers and keyboard-only users.
Screen reader users typically navigate through a form using the Tab key to jump from form control to form control. Associated form labels are read for each form control when the user navigates to them. Any non-label text content between the form controls is usually skipped over. Be sure to include important cues or instructions in associated labels or at the beginning of the form.
The <label> element is used to associate a text label to a form control. This allows a screen reader to read the associated label text when the user navigates to the form control.
All form controls need to include an “id” that associates the form control with the respective form label.
The “id” attribute needs to match the “for” attribute in the form label.
<label for=”name” class="control-label">Name</label> <input placeholder="" id="name" formtype="c02" name="name" type="text">
Group Lists of Form Controls When There are Multiple Options to Select From
Group the list of options with a “fieldset”
Use a “legend” to describe the list of form control options.
Use checkboxes instead of radio buttons when more than one option can be selected
User should be able to select text labels
Please see example below.
<fieldset> <legend>Name</legend> <input id=”equityapplicant” type="checkbox" name="authorization" value="equityapplicant"> <label for="equityapplicant"> I am an Equity Applicant </label><br/> <input id=”equityincubator” type="checkbox" name="authorization" value="equityincubator"> <label for="equityincubator"> My business is an Equity Incubator</label><br/> <input id=”signedaffidavit” type="checkbox" name="authorization" value="signedaffidavit"> <label for=”signedaffidavit”> I registered my business with the Office of Cannabis and have signed an affidavit</label><br/> <input id=”temporarypermit” type="checkbox" name="authorization" value=”temporarypermit”> <label for=”temporarypermit”>I have a temporary cannabis permit</label><br/> </fieldset>
Add a Title Attribute to Form Controls with No Labels
<input class="form-control" title=”Search Regulations” placeholder="Search regulations" name="q" type="text">
Add Required Information to Form Controls
Include the word ‘required’ in the form element to indicate mandatory form fields for screen reader users.
<label for="fname">Family Name *:</label> <input type="text" name="familyname" id="fname" aria-required="true" required>
Accessible Autocomplete Forms
When the form field gains focus:
Tell screen reader users that the input field is an auto-suggest.
Tell screen reader users they can select from the suggestion list or type their own input.
Tell screen reader users the number of suggestions that are available
Allow screen reader users to scroll through the list of suggestions by using the arrow keys.
When suggestions are arrowed through they are spoken aloud.
Add ARIA Labels
Add role=”combobox” to the <input> field to tell screen reader users that the input field is an auto-suggest.
Default text is “Edit Combo”
Add aria-autocomplete=”both” to the <input> field to tell screen reader users they can select from the suggestion list or type their own input.
This is the default text: “To set the value use the arrow keys or type the value”
You can customize this text by using the aria-describedby="initInstr"
Screen reader users can’t use the arrow keys until the autocomplete starts.
You may want to use a more customized message such as “When autocomplete results are available use up and down arrows to review and enter to select.”
Add aria-live=”assertive” to announce the number of results available. The content of the <div>, which isn’t visible on screen, updates every time the list length changes.
Add aria-owns to the <input> field to link the suggestion list to the input field.
Add role=“listbox“ to the suggestion list <div> to tell screen reader users it contains a list of selectable items.
Add aria-activedescendant to the <input> element and populate it with the id of the currently highlighted list item. The aria-activedescendant value changes as the user presses the Up and Down arrows.
Add role=“option“ to each suggestion item, along with a unique id. That id is used by the aria-activedescendant attribute of the <input> element, whose value changes as users move through the list items with the arrow keys.
Add aria-expanded=”true” to indicate that the popup list is displayed.
Here is an example of what the code would look like
<form action=""> <div data-widget="accessible-autocomplete"> <label for="name">Name:</label> <input type="text" id="name" class="autocomplete-search-field" aria-describedby="initInstr" aria-owns="results" role=”combobox” aria-expanded=”true” aria-autocomplete="both" aria-activedescendant="suggestion-1"> <div id=”results” class="autocomplete-list" role=”listbox”> <div class=”autocomplete-suggestion” id=”suggestion-1” role=”option”> Christina Lutz</div> </div> <span id="initInstr" style="display: none;">When autocomplete results are available use up and down arrows to review and enter to select.</span> <div aria-live="assertive" class="screen-reader-text">Two suggestions found, use up and down arrows to review</div> </div></form>
Keyboard accessibility is one of the most important aspects of web accessibility. Many users with motor disabilities rely on only using a keyboard to access content. Screen reader users who are blind or vision impaired will also use the keyboard to access and interact with content. Here are some general best practices.
Users Should Have the Ability to Navigate Using Only the Keyboard
Natively-Accessible Keyboard Elements:
By default, users can navigate to links, buttons, and form controls with a keyboard. These elements are natively-accessible by using the following keystrokes.
Tab: Navigate to links and form controls.
Shift + Tab: Navigate backwards.
Enter: Activate links and buttons.
Spacebar: Activate checkboxes and buttons.
Arrow keys: Radio buttons, select/dropdown menus, sliders, tab panels, autocomplete, tree menus, etc.
Keystrokes Accessible Only Through a Screen Reader:
In addition to the natively-accessible keystrokes, screen reader users have many other keystrokes available to them to help them navigate through a webpage. For example they can use the “H” key to tab through all the headings on a page.
Landmarks and Roles
Break the web page into areas/regions and assign landmark roles. Use HTML 5 in combination with ARIA roles.
Assistive technologies such as screen readers provide shortcut keys to navigate through page elements that have been defined as landmarks and roles, or to jump to specific structural elements (for instance, S for search, B for buttons), and/or provide a list of all structural elements in the document.
Here is an example:
<header role="banner"> <p>Put company logo, etc. here.</p> </header> <nav role="navigation"> <ul> <li>Put primary navigation here</li> </ul> </nav> <main role="main"> <p>Put main content here.</p> </main> <footer role="contentinfo"> <p>Put copyright, and footer related content , etc. here.</p> </footer>
Common Landmarks and Roles
Provide other landmarks and roles as needed to specify areas/sections on a webpage.
Site-orientated content, such as the name of the web site, title of the page, and/or the logo.
<header role="banner"> </header>
The main or central content of the page.
This section contains the search functionality for the site.
Stand-alone content that makes sense out of context from the rest of the document.
Supporting content for the main content. For example, related links in a sidebar.
Informational child content, such as footnotes, copyrights, links to privacy statement, links to preferences, and so on.
Buttons and Role Attribute
Most HTML elements have a default role that is presented to assistive technology. For example, a button has a default role of "button" and a form has a default role of "form".
Always use the native button role so that keyboard only users are able access/select the buttons by using the tab and enter keys.
<form action="/action_page.php" method="get" id="form1"></form> <button type="submit" form="form" value="Submit">Submit</button>
But there are also buttons that are created that are not using a form element, just a regular hyperlink. Add a role attribute to those types of button links to help screen reader users identify the purpose of the link and for them to quickly be able to tab to all the buttons on the page by clicking on the “B” key.
<a href="#" role="button" onclick="" class="btn btn-primary"><span>Apply Online</span></a>
Add Keyboard Focus Indicator to Menu Items, Buttons, Links, Form Elements
A keyboard user typically uses the Tab key to navigate through interactive elements on a web page—links, buttons, fields for inputting text, etc. When an item has keyboard "focus", it can be activated or manipulated with the keyboard.
A sighted keyboard user must be provided with a visual indicator of the element that currently has keyboard focus. For example a border or outline.
Browsers will by default provide a visual border around these elements when they are in focus. Usually a blue border or dotted outline. However the default style may not provide enough color contrast between foreground and background. In other cases the outline may not be visible as the element may have already been styled with a specific border or outline or made invisible.
Apply a keyboard focus outline that has sufficient color contrast by using the following CSS attribute,
Testing for Keyboard Accessibility Using Natively-Accessible Keystrokes
Configure macOS/OS X for Keyboard Accessibility
By default, macOS™/OS X® is not configured to use the TAB key to navigate to all items in your browser. If you are using Apple® Safari®, you also need to configure it to use TAB to navigate to all items on the page.
Configuration is also needed for Firefox on macOS
Configuration is not needed for Chrome on macOS
Navigate to most elements
Shift + Tab - navigate backward
Keyboard focus indicators must be present.
Navigation order should be logical and intuitive.
Enter or Spacebar
Ensure elements with ARIA role="button" can be activated with both key commands.
TAB - Use the tab key to navigation between checkboxes Spacebar - check/uncheck a checkbox
Checkboxes should be used when one or more options can be selected.
↑/↓ or ←/→ - select an option.
Tab - move to the next element.
Radio buttons should be used when only one option from a group can be selected.
Select (dropdown) menu
↑/↓ - navigate between menu options
Spacebar - expand
You can also filter by typing letters, but this behavior varies by browser. Some will filter as you type, like autocomplete. Others will only sort by first letter. E.g., in a list of US States, hitting A then R may take you to Arizona, or it may take you to Alabama and then Rhode Island.
Type to begin filtering
↑/↓ - navigate to an option
Enter - select an option
Esc - close
Modal dialogs should maintain keyboard focus.
Non-modal dialogs should close automatically when they lose focus.
When a dialog closes, focus should usually return to the element that opened the dialog.
↑/↓ or ←/→ - increase or decrease slider value
Home/End - beginning or end
For double-sliders (to set a range), Tab/Shift + Tabshould toggle between each end.
In some sliders PageUp/PageDown can move by a larger increment (e.g., by 10).
↑/↓ - Previous/next menu option
←/→ - expand/collapse submenu
Not all menus should have these controls. Simpler menus should usually rely on Tab/Enter.
Tab - once to navigate into the group of tabs and once to navigate out of the group of tabs
↑/↓ or ←/→ - previous/next tab.
This is for 'application' tabs that change without loading a new page. If a menu looks like a group of tabs, but is actually a group of links to different pages, Tab and Enter are more appropriate.
The tab content should update automatically when pressing the arrow keys. You should not hit Enter to activate the tab.
↑/↓ - Navigate Previous/next menu option
←/→ - expand/collapse submenu, move up/down one level.
↑/↓ - scroll vertically
←/→ - scroll horizontally
Spacebar/Shift + Spacebar - scroll by page
Minimize horizontal scrolling.
Just like webpages, PDF documents also need to be accessible to everyone, including users who rely on assistive technology such as screen readers.
Following are some basic steps to take in order to ensure your PDFs are accessible.
Make sure the PDF is in text based format.
Create a logical reading order by providing a main heading and subheadings.
Tag your document in Microsoft Word
Build the document structure and apply headings <h1>, <h2>, <h3>, <h4>, <h5>, etc.
The <h1> heading should be reserved for the document title
Add paragraphs <p>
Add ALT text (alternative text) for images in Microsoft Word or in Adobe Acrobat
Complex charts and graphics that are embedded in the PDF can’t be accessed by screen reader users. In these cases a summary or long description of what the chart/graphic conveys needs to be provided.
Make sure there is enough color contrast between text and background
Do not use color as the ONLY way to convey informatio
Provide a table of contents for long document
Save your Word or PDF document as a tagged PDF.
Test your document in Adobe Acrobat for accessibility compliance. (please see link below for reference)
Creating accessible Smart PDFs with forms
Following are links to various resources on making your PDF documents accessible.
Alert and Error Messaging
Make sure that error and alert messages are accessible to screen reader users.
Do not rely on color alone to convey the error or alert message when something is not completed correctly or missing.
Provide a description of the nature of the error message as well as an anchor link to the location of the error message. Example: “Please provide the correct date of birth. The primary applicant must be 18 years of age or older”.
Non-Compliant Error Message Treatment
Compliant Error Message Treatment
Accessible Inline Error Messages
Make inline error messages accessible to screen reader users by adding ARIA labels.
Most screen reader and browser combinations announce a form control as “required” when using the required attribute.
Prevent screen readers from announcing required form controls as invalid by default, by using aria-invalid="false".
Update the aria-invalid attribute to “true” if the current value (or lack of value) of a required control does not pass validation.
Wait to declare form controls as invalid and display inline error messages once the control has lost focus, or there has been an adequate delay in key presses (a few seconds)
Use aria-describedby on required form controls to point to an element that will contain any necessary inline error messaging.
Can’t always rely on browser’s client-side error validation to be accessible.
Create a custom client-side validation script and helpful messaging by suppressing the browser’s default validation message by adding the novalidate attribute to the form element.
Default Error Message Treatment
<form novalidate> <label for="name"> Name:</label> <input id="name" hrequired aria-invalid="false"> </form>
Invalid Error Message Treatment
<form novalidate> <label for="name"> Name:</label> <input id="name" required aria-describedby="name_msg" aria-invalid="true"> <span id="name_msg">Please enter your name.</span> </form>
<form novalidate> <label for="Email"> Email:</label> <input id="Email" required aria-describedby="emal_msg" aria-invalid="true"> <span id="email_msg">The email address entered is invalid.</span> </form>
Audio and Video Related Content
Users who are deaf, hard of hearing, or having trouble understanding the audio information must be provided with a text based alternative.
Video Content with Audio
Captioning should be provided for the audio portion of a video. The captioning must be synchronized with the audio so that someone reading the captions could also watch the speaker and associate relevant body language with the speech.
Audio-Only Content with No Video
Audio files with no video are not considered multimedia. However, since audio is a non-text element one of the following text-equivalents must be provided for deaf or hearing impaired users.
HTML based transcript
A text or HTML summary
Writing Content for Screen Readers
General Writing Guidelines
Acronyms: Whenever possible try and steer away from using acronyms and symbols. Screen readers try to pronounce acronyms, if there are sufficient vowels/consonants to be pronounceable. Otherwise, they will try to spell out the letters.
Spell out “CA” as “California”. Screen readers will read out CA as “KA”
Spell out “BR” as “Bedroom”.
Spell out months, instead of “Dec.” say “December”
Instead of “$75,000/year” say “$75,000 per year”
Instead of “1-3 people” say “1 to 3 people”
Instead of “9:00am - 12:00pm” say “9:00am to 12:00pm”
Instead of “(415) 444-8989” say “415-444-8989”
Links: Ensure that all links are informative, and meaningful when read out of context. Link text should be a meaningful representation of the link target.
Screen-reader users may be unable to easily access contextual information related to a link.
Single word links represent small targets for persons who have difficulty controlling a pointing device due to motor impairments. Placing long lists of text-based links close together in rows or columns increases the probability of a mouse error.
Avoid the use of single word links (“Here”, “More”, “Go”). Links should be clear, descriptive and able to stand alone.
Avoid enclosing text links in brackets, braces, parentheses.
Avoid “Click Here”
Non-Compliant Link Examples
Compliant Link Examples
Contact the County Clerk
Contact the County Clerk
Click here to visit the Mayor’s website
Visit the Mayor’s website
How Screen Readers Read Content in General
Screen readers pause for:
Screen readers read letters out loud as you type them, but say “star” or “asterisk” for password fields.
Screen readers announce the page title (the <title> element in the HTML markup) when first loading a web page.
Screen readers will read the alternative text of images, if alt text is present. JAWS precedes the alternative text with the word “graphic.” If the image is a link, JAWS precedes the alternative text with “graphic link."
Screen readers ignore images without alternative text and say nothing, but users can set their preferences to read the file name.
If an image without alternative text is a link, screen readers will generally read the link destination (the href attribute in the HTML markup) or may read the image file name.
Screen readers announce headings and identify the heading level. NVDA and JAWS, for example, precede <h1> headings with “heading level 1.”
Some screen readers announce the number of links on a page as soon as the page finishes loading in the browser.
JAWS says “same page link” if the link destination is on the same page as the link itself and “visited link” for links that have been previously accessed.
Screen readers in table navigation mode inform the user how many rows and columns are in a data table.
Users can navigate in any direction from cell to cell in table navigation mode. If the table is marked up correctly, the screen reader will read the column and/or row heading as the user enters each new cell.
Screen readers inform users when they have entered into a form. Users have the option to enter form navigation mode.
Screen readers can be thrown off by homographs. For example, the word read can be pronounced “reed” or “red,” depending on the context: “I’m going to read the newspaper” vs. “I already read the newspaper.” A sentence such as “I read the newspaper every day” is ambiguous to all readers—humans and screen readers alike. The word content is another example: “I feel content” (meaning satisfied, with the emphasis on the second syllable [con-TENT]) vs. “sf.org has some really awesome content” (meaning the subject matter, with the emphasis on the first syllable [CON-tent]).
Screen readers may or may not read out punctuation, depending on the user’s verbosity setting. Ensure that your intended meaning will be conveyed in either case. To appreciate the value of punctuation, consider these sentences:
Let’s eat, grandpa!
I’d like to thank my parents, the mayor, and the president.
He finds inspiration in cooking, his children, and his cat.
Testing with Screen Readers
The following are the most common screen reader/browser combinations used among vision impaired users.
NVDA (this is a free, open source, Windows based software) + Firefox - 72%
JAWS (Windows based) + Internet Explorer, Chrome or FF - 61%
VoiceOver (iOS) + Safari - 47%
JAWS is not compatible with Microsoft Edge.
All screen readers share similar functionality and capabilities. However, keyboard shortcuts, voices, and ways of calling out links, images, and so on, vary between them. Since users will be accustomed to their preferred screen reader’s conventions, these differences don’t typically impact coding practices. The key is to adhere to accessibility standards and generally-accepted accessibility techniques.
How to enable VoiceOver on the Mac
Per the City and County of San Francisco’s Language Ordinance, site content should be available in the following languages.
JAWS Screen Reader and Languages
JAWS provides language switching with any supported speech synthesizer. When a Web page author indicates the language of an entire page, or just part of a page, if the synthesizer in use supports that language, JAWS uses the language specific version of the synthesizer to speak the text. The synthesizer must support the language of the information. If the synthesizer does not support the language specified for a page or part of a page, JAWS still indicates the language of the information. For example for Chinese JAWS will say, “heading level 2 , Chinese”
The languages that are spoken by JAWS depends on the synthesizer currently in use. If you are using the default Eloquence synthesizer that is installed with JAWS, the following languages are available:
Latin American Spanish
French, French Canadian
Links and New Windows
From an accessibility perspective, the preference would be to always open links within the same window rather than opening them up in a new window.
The reason for this is that some users, especially screen reader users, can get confused or disoriented with the new windows or tabs. If a new window or tab is opened a screen reader user should be notified of this ahead of time. Newer screen readers will alert the user when a link opens a new window, but this only happens after the user clicks on the link. Older screen readers don’t alert users at all. Sighted users with cognitive disabilities may also have difficulty interpreting what just happened when a new tab/window is opened. Then when they try to click on the browser Back button nothing happens, because there is no previous link to go back to in a new window or tab.
Popups and modal windows are not a good user experience for keyboard-only/screen reader users and as a rule of thumb we should steer away from using them. Instead we should try and find a different solution.
When a popup appears it does not have keyboard focus which means that keyboard only/screen reader users are unable to tab to the content within the popup. Screen reader and keyboard-only users can easily become distracted and disoriented.
If there is absolutely no other solution than a popup/modal, it must be programmed in a way that allows for the following.
The modal dialog or popup needs to trap the keyboard. When a modal dialog/popup box is triggered, the keyboard focus needs to immediately move to the first actionable element in the popup/modal.
The keyboard user needs to be able to access all controls in the popup/modal window.
The keyboard user needs to have the ability to close the popup/modal window.
Once the popup has been closed the keyboard focus needs to be restored to the main webpage
Color Contrast Checker by WebAIM
Color Blindness Filter by Toptal
Use this filter to test web pages for color blindness https://www.toptal.com/designers/colorfilter/
Accessible PDFs - Adobe Acrobat Pro and Microsoft Word
How to make your Microsoft Word document accessible by Microsoft:
Web Accessibility Testing Tools
WAVE by WebAim http://wave.webaim.org/
SortSite by Powermapper https://www.powermapper.com/products/sortsite/checks/accessibility-checks/
Writing Effective ALT Text for Images