Best Practices


Commonwealth agencies are required to produce accessible websites in compliance with the Digital Accessibility Policy (ITP-ACC001). While the Americans with Disabilities Act and Section 504 of the Rehabilitation Act already require the Commonwealth to ensure accessibility, the Digital Accessibility Policy establishes specific standards and encourages agencies to address accessibility proactively.

Authoring Accessible Content

The Keystone Design System is built around the Digital Accessibility Policy requirements, however it is imperative that you follow general author considerations that will make your experience even more inclusive. Your web page will not pass the requirements if you do not take responsibility in making your authored content accessible. Below is a set of authoring principles that will help you adhere to accessibility requirements and create web pages that are easy for everyone to use, navigate and enjoy. Review the Adobe Experience Manager (AEM) Authoring Guide and Editorial Style Guide for an in-depth examination of best practices and detailed instructions on creating accessible components and page templates within the AEM environment.

You need to be conscious of what you assume about a user’s ability when it comes to the language you choose. 

Here are some examples of why certain words and phrases are preferred, and why some should be avoided:




View, Show, Go to all

See all, View all

Not everyone is “seeing,” and the “do” options (“Display,” “Show,” “Go to all”) have more nuance in meaning.

Play video

Watch video

Be descriptive. Not everyone is “watching” the video.

Select the correct answer from the options below.

Choose the correct answer by clicking an option below.

Changing this language from “click” to “select” doesn’t assume the method of interaction.


Headings communicate the organization of the content on the page. Web browsers, plug-ins, and assistive technologies can use them to provide in-page navigation.

  • Do
    • Use headings to provide a page structure or outline.
    • Use headings to indicate sections of content.
    • Nest appropriately in a hierarchy – avoid skipping levels.
  • Don’t
    • Use headings purely for visual appeal or emphasis.
    • Over-use. If there’s no paragraph text below a heading, then it shouldn’t be a heading


Tables are excellent tools for displaying data sets. To be accessible to all users, tables should have designated headers and simple structure.

It’s best to keep your table design simple. Use only one column header and/or one row header. Don’t merge the cells. And, if your data set is complex, split it up into multiple tables.

All tables must have column headers; some tables will require both column and row headers. Users can navigate from cell to cell within a table while hearing the screen reader announce the corresponding column header and/row header. Without designated headers, this wouldn't be possible. 


Lists can make large chunks of text easier to read. Here are some strategies to help you make sure your list is accessible:

  • Use the List Component or built-in list tool in the Rich Text Editor.
  • Be mindful of the types of bullets used within the list. When creating a secondary list within an established list, make sure to use a different bullet for the secondary list. This helps distinguish between the two.

Alternative text (or alt text) is text that describes an image. It makes it possible for people using assistive technologies to access the information conveyed by an image. It also helps search engines better understand the purpose of the image.

When you're writing alternative text, first consider if you intend the image to be a decoration. An image is a decoration if you could remove it and it wouldn’t change the meaning of the section. Decorative images don’t require alt text. When adding a decorative image to a component in AEM, you can identify an image as decorative.

For images that are not decorative, these convey a meaning that needs to be described:

  • describe the image as if you were describing it to someone over the phone
  • use as few words as possible
  • limit the text to around 140 characters (including spaces)
  • don't provide more information than the sighted user can see on the page
  • don't use "image of..." or "graphic of..." to describe the image; screen readers do this already
  • Avoid using images that contain meaningful embedded text except for logos. For logos, provide alternate text that is the same as the logo. Do not use the word “logo” in the alt text.
  • If using an image with embedded text is unavoidable, the alt attribute should exactly match the text embedded on the image, unless that text is already available in adjacent text.

Long descriptions explain information that is presented in complex infographics or images. You must provide a long description if you can't describe the content and function of the image in less than 140 characters. For example, for a complex chart or diagram, you can display the tabular data used to create the visualization in a table below the image.

If a detailed and equivalent explanation of the image appears in the text immediately before or after a complex image, you don't have to provide a long description, and the image can be considered decorative.

Long Description Example

A balanced scorecard showing how business activities align with an organization's vision and strategy to monitor key performance indicators. Extended description available below.

A balanced scorecard is a strategic planning and management system used worldwide to align business activities with an organization's vision and strategy.

Business activities are grouped into 4 perspectives, all of which are interdependent and come from the vision and strategy. These are learning and growth, internal business processes, financial, and customer. Each has a question associated with it.

  1. Learning and growth: To achieve our vision, how will we sustain our ability to change and improve?
  2. Internal business processes: To satisfy our shareholders and customers, what business processes must we excel at?
  3. Financial: To succeed financially, how should we appear to our shareholders?
  4. Customer: To achieve our vision, how should we appear to our customers?

Each perspective can be monitored using the following 4 components:

  • objectives
  • messages
  • targets
  • initiatives

When crafting copy for a call-to-action link (CTA), use clear, actionable language in 2 to 3 words to explain what the link does or what action you want the user to take.

  • Don’t:
    • Click Here
    • Download Now
    • Get Help
  • Do:
    • Submit your information
    • Apply for benefits
    • Explore our services

To ensure the videos you produce and post on are accessible and conform to guidelines, they should have accurate captions that include proper punctuation, speaker identification, and the identification of sounds other than speech. Captions must be synchronized and appear around the same time that they would be heard in the audio. Captions do not need to be a word-for-word version of the audio but should be a concise equivalent. Audio description is required when important information is visually shown on the screen that cannot be observed by a blind or vision-impaired individual.

Transcript pages should be created in AEM for any videos that do not already have a transcript provided through YouTube or Vimeo. Note that closed captions do not replace a transcript.

  1. Create a new page, using either the Content Page or a specific Agency Content Page template as needed. Title the page “Transcript: *name of video*.
  2. On the new page, use the Text component to type out the transcript of the video.
  3. On the Video Player component, reference the transcript page in the Video Transcript Link field.

Additional Resources

The Department of Justice issued final regulations under Title II of the ADA requiring state and local government websites and mobile apps to conform to the Web Content Accessibility Guidelines (WCAG 2.1) A and AA. The Commonwealth of Pennsylvania aims to meet the most recent version of the Web Content Accessibility Guidelines, WCAG 2.2 A and AA.