Creating Accessible Oracle JET Pages

Content generated by Oracle JET is designed to conform to the WCAG 2.0 AA standards. However, many standards are not under the complete control of Oracle JET, such as overall UI consistency, the use of color, the quality of on-screen text and instructions, and so on.

A complete product development plan that addresses accessibility should include proper UI design, coding, and testing with an array of tools, assistive technology, and disabled users.

Note:

In most cases, end-user documentation for your application must describe information about accessibility, such as example keystrokes needed to operate certain components.

Topics:

Configuring WAI-ARIA Landmarks

WAI-ARIA landmarks provide navigational information to assistive technology users. Landmark roles identify the purpose of a page region and allow the user to navigate directly to a desired region. Without landmarks, assistive technology users must use the TAB key to navigate through a page.

The Oracle JET team recommends the use of WAI-ARIA landmarks to ensure page accessibility and provides examples you can use in the Oracle JET Starter Template collection. The following figure shows the run-time view of the Oracle JET Web Nav Drawer Starter Template. In this example, the page is organized into regions compatible with WAI-ARIA landmark regions, including regions for the banner, navigation, main, and footer landmarks.

The highlighted code in the following example shows the landmarks for the Web Nav Drawer Starter Template. Each landmark is placed on the HTML element that defines the landmark region: header for the banner landmark region, footer for the contentinfo region, and div for the navigation and main regions.

<!DOCTYPE html>
<html lang="en-us">
  <head>
    <title>Oracle JET Starter Template - Web Nav Drawer</title>
    ... contents omitted
  </head>
  <body>
    <div id="globalBody" class="oj-offcanvas-outer-wrapper oj-offcanvas-page">
      <div id="navDrawer" class="oj-contrast-marker oj-web-applayout-offcanvas oj-offcanvas-start">
        <div role="navigation" data-bind="ojComponent: {component: 'ojNavigationList',
          optionChange: navChangeHandler, navigationLevel: 'application',
          item: {template: 'navTemplate'}, data: navDataSource,
          selection: router.stateId, edge: 'start'}">
        </div>
      </div>
          ... contents omitted 
      <header role="banner" class="oj-web-applayout-header">
        <div class="oj-web-applayout-max-width oj-flex-bar oj-sm-align-items-center">
          ... contents omitted
        </div>
      </header>
      ... contents omitted
      <div role="main" class="oj-web-applayout-max-width oj-web-applayout-content" data-bind="ojModule: router.moduleConfig">
      </div>
      <footer class="oj-web-applayout-footer" role="contentinfo">
          ... contents omitted
      </footer>
      </div>
    </div>
  </body>
</html>

If your application includes a complementary region, add role="complementary" to the HTML div element:

<div role="complementary"></div>

For information about downloading the Oracle JET Starter Templates, see Downloading Oracle JET with a Starter Template. For details about working with the Oracle JET Starter Templates, see Create a Web Application Using the Oracle JET Starter Templates.

For additional information about WAI-ARIA landmark roles, see http://www.w3.org/WAI/PF/aria/roles#landmark_roles.

Configuring High Contrast Mode

High contrast mode is for people who require a very high level of contrast in order to distinguish components on the page. Operating systems such as Microsoft Windows and MacOS provide methods for users to run in high contrast mode.

The graphic below shows the effect of changing to high contrast mode on Oracle JET icon font images.

Oracle JET provides the oj-hicontrast class that you can use to configure high contrast mode in your application.

Topics:

Understanding Color and Background Image Limitations in High Contrast Mode

There are color and background image limitations in high contrast mode that your application may need to work around.

In high contrast mode the colors in the CSS may be ignored or overridden, including background, border, and text colors. Therefore, in high contrast mode you may need to find an alternative way to show state. For example, you might need to add or change the border to show that something is selected.

Also, your application may need to show alternate high contrast images that work on dark or light background color. Some operating systems, like Microsoft Windows 7, offer multiple display profiles for high contrast mode, including a black-on-white and white-on-black mode.

Consider providing an image that includes a background, so either black on a white background or white on a black background. That way it won’t matter what the background color is on the page since the contrast is in the image itself.

Finally, on Windows, background images don't appear in high contrast mode. Therefore, you cannot use background images to communicate anything informative. You can use a background image to make something look nice, but don't use it to communicate information like the status of a process or whether something is required.

Adding High Contrast Mode to Your Oracle JET Application

In most cases, you do not need to do anything to enable high contrast mode in your Oracle JET application. If you're using RequireJS to load Oracle JET component modules, Oracle JET will load a script that attempts to detect if a user is running in high contrast mode. If the script succeeds at detection, it will place the oj-hicontrast class on the body element.

There is a serious limitation to this method, however. There is no standard way to detect high contrast mode, and we can't guarantee that the script works in all cases on all browsers. For example, on Windows, the script does detect high contrast mode on Internet Explorer, Microsoft Edge, and Firefox browsers, but it does not detect high contrast mode on Chrome.

To be guaranteed that the .oj-hicontrast styles are applied, add a user preference setting for high contrast to your application and configure the application to add the oj-hicontrast class to the body element when the preference is set.

When the class is added, the .oj-hicontrast CSS styles are applied to the page where defined. The code below shows an excerpt from the Alta CSS which changes the outline-width to 3 on the ojButton component when the button has focus.

.oj-hicontrast .oj-button.oj-focus {
  outline-width: 3px; }

Note:

For disabled content, JET supports an accessible luminosity contrast ratio, as specified in WCAG 2.0 - Section 1.4.3 Contrast (Minimum), in the themes that are accessible. For more information on which Oracle JET themes are accessible, see CSS Files Included With Oracle JET.

Section 1.4.3 says that text or images of text that are part of an inactive user interface component have no contrast requirement. Because disabled content may not meet the minimum contrast ratio required of enabled content, it cannot be used to convey meaningful information. For example, a checkbox may still appear checked in disabled mode, but since the colors may not pass contrast ratio, you cannot rely on all users being able to see that it's checked. If the information is needed to interact with the page correctly, you must convey it using a different method, for example as plain text.

Adding High Contrast Images or Icon Fonts

To support high contrast image files, Oracle JET provides Sass mixins that you can use to generate the correct CSS in high contrast mode to:

  • Use an alternate image.

  • Use images without using background images.

The Oracle JET cookbook provides examples that you can use at: CSS Images.

You can also use icon fonts instead of image files to support high contrast mode. The limitation is that icon fonts use a single color. Since these icons are text, they will be guaranteed to contrast against the background color on systems that ignore colors in the CSS. However, if you use color to show state (for example, changing an icon to blue when selected), the colors may be ignored in high contrast modes. You may need to find an alternative like setting a border instead. The Oracle JET cookbook provides icon font demos at: Icon Fonts.

Testing High Contrast Mode

The recommended way to test high contrast mode in Oracle JET applications is to set high contrast mode at the operating system level on a Microsoft Windows platform. The Windows platform is recommended because Windows turns off background colors and images in high contrast mode. Also, the Google Chrome browser does not remove background images in high contrast mode, and unless this is the only browser you plan to support, you should test high contrast with Microsoft Internet Explorer or Firefox.

To turn high contrast mode on and off in Microsoft Windows, use the following key combination: Left Alt+Left Shift+PrtScn. You may need to refresh your browser to see the new mode.

Hiding Screen Reader Content

Sometimes you want to have some text on the page that is read to the screen reader user, but the sighted user doesn't see. Oracle JET provides the oj-helper-hidden-accessible class that you can use to hide content.

You can find the .oj-helper-hidden-accessible style defaults in the Oracle JET CSS file. For the Alta theme, the CSS file is: css/libs/oj/vxxx/alta/oj-alta.css. For additional information about theming and Oracle JET, see Theming Applications.