Accessibility in Cloudscape

Cloudscape Design System provides you guidelines and tools to help you build accessible interfaces, such as semantic markup and use of appropriate ARIA attributes. We strive to build Cloudscape components with accessibility in mind.

To help you build an accessible user interface (UI), we have the following suggestions:

  • Follow the accessibility guidelines section for each component on alternative text and ARIA regions, located in the usage tab of each component article.

  • Define ARIA labels that are aligned with the language context of your application.

  • Don't add unnecessary markup to components for roles and landmarks. Follow the guidelines for each component.

  • If you build a custom component, refer to accessibility standards and best practices for usability.

General guidelines

Keyboard interaction

All functionality provided by interactive elements must be operable by a keyboard interface when no Assistive Technology (AT) is in use. Users must be able to tab to each control or navigate to it another way and operate it by using a keyboard. Users who use keyboard navigation or screen readers depend on a logical focus order. Ensure that your content is easy to access and organized in a meaningful order.

  • Provide keyboard functionality to all interactive elements of the available content in a logical and predictable order. The flow of information should be meaningful and make sense.

  • Ensure that your web application can be fully operated with keyboard only. Test your application for keyboard traps.

  • Design with a clear hierarchy and a predictable focus order.

  • Ensure that input focus follows the visual order of the layout.

  • Provide a visible focus indicator for all interactive elements on keyboard focus.

  • Don't make users hover to reveal content. All hover elements should also be accessible with a keyboard on focus.

  • If a region of the page is scrollable, users must be able to scroll it by using a keyboard.

  • When character-only keyboard shortcuts are used, make sure the user can turn on, turn off, or remap shortcuts to include at least one non-character key (For example: ALT or CTRL).


Headings are elements that help users understand the structure of content on the screen. For users with disabilities, headings can be especially helpful. Headings describe sections of content, provide an outline for the contents of the page, and help users navigate the page faster. If you make text big and bold, it will look like a heading, but it won't act as a heading unless you put heading tags around it. If a text labels a section of content, it's a heading. If you style text only to increase visibility, it's not a heading and shouldn't be coded as a heading.

  • Headings must accurately describe the content they are associated with.

  • Heading semantics must be used appropriately and also communicate the relationship between headings.

  • We recommend using one H1 per page and avoiding multiple H1 headings on a page.


All form elements, such as text inputs, buttons, text areas, radio buttons, dropdowns, and check boxes, must have visible labels. Missing labels can prevent users with disabilities from entering necessary setup information, choosing important service options, or proceeding to the next step in a wizard, among other potential issues. Follow the accessibility and writing guidelines for each component.


Links must be written in a meaningful way. Follow the guidelines for using links in typography.

  • Every link must be able to have focus and also have a visible focus indicator that is different from the non-focus state.

  • Don't repeat the URL as part of the link text.

  • The text for each link should clearly describe the purpose.

  • Don’t rely on only color to communicate information visually.

  • When writing friendly text for a link, don’t use “Click here.”

  • Make link labels concise and meaningful.

  • Make sure that links are unambiguous. The link text should accurately describe the link destination.

Alternative text

Alternative text (or alt text) is a textual aid for any visual element (for example: images, icon, buttons). It’s used by screen readers and generally not displayed visually. However, it replaces images when they can't be loaded.

  • Ensure that the alternative text you set is accurate and specific.

    • For example, on an image of a Venn diagram, use this: X Venn diagram overlapping the three dimensions of A, B, and C highlighting the Y dimension.

    • Instead of this: A picture of the Venn diagram.

  • Make your alternative text clear and succinct. All elements on your interface will be read by screen readers. Short text (fewer than 100 characters) allows for faster interaction and increases findability.

  • Write all alternative text in the locale of the user interface.

    • For example: If the interface is in French, alternative text should also be written and read in French.

  • Every image on the screen must have an alt attribute. For images that are strictly decorative, provide empty or null alt text (alt="").

  • Don't use words like "button", "link", or "image of" in alternative text. Screen readers automatically provide that information to the user.

Icons and images

Informative images and icons must have a meaningful alternative text. The alternative text should always include text that describes the function or purpose of the image. Make sure to follow the accessibility and alternative text guidelines for each component.

  • Provide a text alternative for all non-text content that is presented to the user. The text alternative must serve the equivalent purpose and be programmatically determinable.

  • Every icon must have an alternative text that is meaningful to the user. Don’t rely solely on the icon name.

  • All meaningful icons and graphical objects should meet or exceed the minimum color contrast of 3:1.

  • Don’t provide unnecessary alternative text. When using icons inside a Cloudscape component, rely on the alternative text of that component.

  • Ensure that every image has alternative text or is properly designated as decorative. Alternative text is faster to appear than any image loaded on the browser. Good alternative text for an image describes both its content and function with under 100 characters.

  • Use action verbs to state what the icon does rather than what is depicts.

  • Don't state the type or current state of the control in icon alternative text. Rely on the browser reading the states.

    • For example: Checked or unchecked.

Color contrast

Background and foreground colors combinations must have a contrast ratio that meets or exceeds 4.5:1 for normal text and 3:1 for large text. Large text is defined as 14 point (typically 18.66px) and bold or larger, or 18 point (typically 24px) or larger. Meaningful graphics, meaningful parts of complex graphics (like graphs), user interface components, and state indicators such as focused, selected, and checked must have a contrast ratio that meets or exceeds 3:1. To get optimal contrast ratio in your UI, follow the colors combinations from our colors article.

  • Think about how your color choices and combinations can affect the legibility and accessibility of your content.

  • Ensure that color is not the only visual way of conveying information. Relying on color only to provide information prevents users with color perception or other vision issues from understanding the full content.

  • Ensure that there is sufficient contrast between background and foreground elements.

Announcing updates with ARIA live regions

When there are updates to the current page, for example a status message being displayed, it’s important to notify people that use assistive technology like screen readers. To do this, use ARIA live regions and the aria-live attribute. You can define various levels of politeness, with polite and assertive being the most common. assertive immediately interrupts the screen reader when invoked, so only use this for critical errors. In other cases, we recommend polite. To make sure that the updated region is announced when a users navigates to a page, we recommend that you have the ARIA live region available in the DOM before you change the content. If you don’t, some screen readers might not announce the text at all.