General best practices

Use the following best practices to guide your decisions as you design your survey:

CSS styling

Cascading style sheet (CSS) styles define how to render the content on the user's device, such as a visual browser, screen reader, or visual browser. On a web page or form, CSS styling is performed with style sheets or embedded in-line with the style attribute. For Experience Cloud surveys, styles heets are hosted on the Survey engine and are generated by the Base CSS and Theme CSS properties on Survey designs.

When defining CSS:

• Required:

  • Ensure the reading order of content and elements are logical when viewed without style sheets. Content that does not makes sense without a style sheet will also not make sense to screen reader users.

  • Provide text equivalents for icon fonts. For example, when showing an alert or warning symbol as a font, also include text that describes the condition. This information provides screen reader users context about the purpose of the icon.

  • Ensure containing elements allow text resize and reflow. This allows people with low vision to modify their display settings to better see the content.

  • Ensure screen reader specific content is rendered off-screen rather than hidden or not displayed. For example, using position elements to render the content outside the browser window. This usually does not add scroll bars to the window.

  • For decorative images (ones that do not provide content), use background images so screen reader users do not have to hear it.

• Avoid:

  • Using ::before and ::after, pseudo classes for non-decorative content because they are not always recognized by screen readers.

  • Background images behind text, which can cause contrast issues.

  • Size declarations on any portion of the box model (see the note below for more on CSS) because they all contribute to the overall size of the element and cannot be resized or reflowed.

  • Placeholder (placeholder) attribute without an aria-label attribute as some screen readers and speech-to-text programs do not recognize this text.

• Do not use:

  • In-line styles (style attribute) as they can prevent low vision, color-blind, and cognitively impaired users from modifying colors, font sizes, and other features to fit their needs

  • Title (title) attributes for textual content. Using screen reader, all the titles will be spoken so redundant title should be removed (from the link, not the image). As a rule of thumb, do not use title attributes on links or form elements or table cells or other elements because that can lead to screen-reader users hearing those announcements twice.

  • CSS to render content or provide functionality because screen readers ignore CSS.

  • Absolute units (such as in, cm, mm, pt, and pc) because these are intended for print media. Instead, use relative units (such as ems, percentages, or larger), or do not use units and let the agent use the default units. This lets the user to zoom and enlarge the content and provide proper wrapping and formatting.

See MDN's CSS: Cascading Style Sheets for an in depth discussion of CSS.

Images

Any image that conveys content must have an equivalent alternative description. The text must succinctly describe the element without being too verbose. When using an <img> tag, always include an alt attribute that describes the image. If the image is used in a link or some other user action, also describe the intended action. For example, if a survey uses a link and image to start the survey, the HTML might look like this:

<img name="Get_Started" alt="Start the survey."/>

For decorative images (those that do not provide content), use CSS background images instead so screen readers can ignore it. For example:

.brand_sparkle {
  background-image: url('/static/images/brand_sparkle.png');
  background-repeat: no-repeat;
  background-position: right top;
}

Then, in the HTML element, reference the image appropriately, similar to this:

<div class="brand_sparkle"></div>

When using images in surveys, note these best practices:

• If the image is for decoration only, use CSS background images. When the image cannot be rendered as a background image, leave the alt description empty (alt="") to hide it from screen readers.

• If the image provides content, use an <img> tag and include descriptive alternative text with the alt attribute. Further:

  • The image must have sufficient contrast to be legible by users with low-visibility.

  • When the image is the sole content of a link, describe the target, not the image.

  • When the image content describes a specific state (such as an icon that indicates incorrect input), describe the state instead of the image.

  • Avoid alt text descriptions that duplicate the adjacent text. For example, if text on the survey says Stop and it is immediately followed by an image link, make the image text more descriptive, such as, Terminate the survey.

When translating alt text, note that you might find images in:

• Emails — There is no specific automated tool to validate if an email is accessible. Typically, an email should be checked with a variety of assistive technologies (such as VoiceOver, JAWS, and NVDA) in multiple environments, (such as iPhone, tablet, desktop, Gmail, Outlook, Outlook in Office 365, IE, Firefox, and so on). Generally, the less complicated an email is, the easily all users are able to get to the information.

  The alt text on the image references in the HTML email must also be translated as part of the translation of the overall HTML email in Translations.

  When offering multiple languages in emails, use the multilang template and proper language conditioning to ensure scalability. Update the multilang template to add a phrase before the language links to say Available languages or Choose a different language.

  Warning: Multi-language email links do not work on Apple Mail on mobile devices (though they do work on Apple Mail on desktops). Sometimes double-tapping on the link activates the control.
• HTML elements — Images embedded in your survey.

Common feedback

Third party accessibility audits might result in feedback for accessibility improvements, primarily in surveys. Some feedback can be corrected using the guidelines provided in this topic (such as changes to color and contrast, image alt text, and so on), while other feedback might be targeted towards the underlying structure. Accessibility guidelines are often open to interpretation, especially with regards to how the guidelines are followed. Below are some common observations, followed by the recommended Medallia response:

ARIA landmark is not used to identify header section of the page.

Because Experience Cloud surveys use headers and footers, they do not necessarily need role = landmark. Including ARIA landmarks would result in duplication of content.

The text One or more items on this page require your attention. is not provided in container with role="main". It is placed out of landmark role main.

Originally, error messages were not considered to be part of the main content of the page. Medallia recognizes that this behavior is not as ideal, and will develop incorporating the error message inside role="main". Given the uncommon use of landmark navigation within a survey versus tabbing, this is not considered a WCAG failure.

The Next and Back buttons are not included in main region (role="main") of the page.

The buttons are not part of the main section of the page. They are part of the navigation.

The three links present in the footer of the page are not grouped under list.

From WebAIM, our accessibility vendor: This is a good idea if you have a grouping of links that essentially form a list. This can facilitate navigation and a screen reader would provide an indication of how many items are in the list. The links in the footer would be an <ol>, rather than <ul>. But if items are not visually presented as a list with bullets or numbers, there is not a WCAG requirement to mark them up as a list.

The radio buttons are coded using unordered list.

Accessibility best practice is to have all radio buttons in an unordered list so that the screen reader recognizes the group as a list.

Page contents are not announced by screen reader in a logical manner: screen reader is not announcing the text Powered by Medallia.

This is intended behavior and deemed as accessible because the Powered by Medallia logo does have associated text read by the screen reader (Medallia). If that is not fully in line with the client's accessibility standards, they can use a custom footer.

Form elements do not have descriptive labels to identify the purpose of the element.

Fieldset/Legend is intentionally used across all survey elements to ensure the survey taker can consistently navigate between both question and text elements.

A visible focus indicator is not present around the Next and Back buttons when they receive keyboard focus.

By default, v7 design template's Next button uses the arrow key that appears as the visual focus indicator. If needed, a border on-hover can be added using CSS.

Screen reader is announcing the legend twice for each and every question.

This might be browser and screen-reader dependent. Question text is incorporated into fieldset to ensure cross-browser compatibility (they are read once in some screen readers, while other screen readers read twice).

The label for text box which appears when user selects the Other radio button could be more descriptive.

Rename the Other option to either Other, please specify or Other Reason.

We should add hidden text in HTML to ensure that survey takers using Apple VoiceOver hear numbers like 4000 as Four thousand rather than Four zero zero zero, even if they configure the setting Read numbers as: Digits.

The hidden text would actually create an atypical experience for these users. This type of content should be presented in the formatting that makes the most sense visually, then the screen reader can interpret it based on their experience and settings, and can explore it letter by letter. Adding the off-screen text is overly complex and potentially introduces other issues, primarily having two versions of the number that could be accessed.

On submitting a form with invalid data, an error message is displayed, but as the error message is not in the label tag, the screen reader is not announcing it to the user.

The user is taken to a summary error message at the top of the page. The user can then use the tab key to progress through each question. When a user lands on the question with an error, the screen reader identifies the error.

Tabbing in Firefox proceeds through every number in a rating scale, while tabbing in Chrome the selects different ratings.

This is standard behavior for radio buttons in Firefox. It proceeds through all available radio buttons in a set until one is activated. After a radio button is selected, tabbing navigates only to that selected radio button. You are not prohibited from navigating by arrow keys to choose a radio button from the set. The intent of this behavior is to allow users to explore all of the radio button options by tabbing without actually selecting one. Because this is standard behavior for Firefox, this does not pose an accessibility issue.