Skip to content

Latest commit

 

History

History
249 lines (152 loc) · 17 KB

top-extensions-accessibility.md

File metadata and controls

249 lines (152 loc) · 17 KB
Raw

Accessibility

Accessibility is about making the portal usable by people who have limitations that prevent or impede the use of conventional user interfaces. For some situations, accessibility requirements are imposed by law. However, Microsoft requires all blocking accessibility issues to be addressed regardless of legal requirements so the portal caters to the largest possible audience. The Framework team has taken an inclusive design approach in incorporating keyboard, programmatic, and visual design support throughout the Portal. Extensions are responsible for any graphics, styling, and custom HTML templates they provide.

What the framework provides-

  1. The Framework provides reusable tiles, parts, forms, and controls that are fully accessible. Using the Form creation helper, your form will be fully accessible.

    • All Portal:

      • Chrome
      • Panes
      • Sidebar
      • Top nav
      • Context menus
      • Widgets

    • Keyboard shortcuts are provided and are listed within the Help Menu in the Portal. The shortcuts must work when using your extension content.

    • A fully accessible default theme (Blue). When using the blue theme, the contrast ratio for all text must meet the AAA guidelines that are located here.

    • The Portal supports HighContrast mode and should display controls and chrome accordingly.

  2. Focus management is handled by the Framework and follows those rules, unless the focus is changed by the user first.

    • Focus moves to newly opened blade in the content section.
    • Focus moves to context pane when opened.
    • Focus should move freely across all elements visible in the Portal, except in the following cases:
      • ContextMenu captures focus in a loop
      • DropMenu captures focus in a loop

NOTE: Currently, the focus is on the first focusable element.

Accessibility Checklist

There are items for accessibility whose absence may result in bugs for the Framework team. In an effort to reduce the number of bugs, some guidelines are listed below -

  1. Extensions should update to SDK version 1240 or more recent.

  2. Extension should update to use supported controls. An inventory of the latest, fully supported controls is located here. NOTE: DiffEditor, DatePolyFills, and PairedTimeline are not supported by Framework.

  3. Extensions should ensure theming support in both Light and Dark mode when using custom colors.

  4. Extension should not interfere with High Contrast theming. A common mistake is to use a <div> element instead of an <a> element for a link.

  5. When introducing user-actionable areas that are not based on supported controls, extension should use the fxClick knockout binding as documented. The click knockout binding is not supported.

  6. Extensions that create custom implementation of supported controls should be identified.

  7. Images and logos that are part of the Narrator Items mode should be labelled properly, or marked as aria-hidden if not significant.

  8. Review all controls and ensure that labels are being used. If labels are omitted, then use aria labels in the ViewModel. NOTE: The aria-label is one tool used by assistive technologies like screen readers. However, it is not natively supported on browsers and has no effect on them. It will not be of use to the population that is served by WCAG, except screen reader users.

  9. Verify keyboard accessibility of your blade content and forms. Navigate to your content in the Portal and ensure focus is captured to your content in the expected way. Autofocus on open provided by the framework.

  10. Screen items have titles that are displayed on hover. If text or labels are missing from the screen, use the TITLE attribute to display them. If the TITLE attribute cannot display the information, use aria-label. For more information about HTML attributes, see https://www.w3schools.com/html/html_attributes.asp.

  11. Screen contrast has a minimum value. If the contrast is too low, use the WCAG color contrast tool that is located at https://leaverou.github.io/contrast-ratio/ to adjust colors.

Before testing

  1. KEROS testing

    • Use Keros tool to address accessibility issues: Here's what you need to get started:
    • Install it from the Chrome store.
    • Watch a three minute video to learn about running a FastPass, using automated checks, and testing tab stops.
    • Questions: if you or someone from your team believes Keros is producing a false positive, contact (KerosSupport)

  2. Email C+E Accessibility Core Team to confirm that KEROS testing has been completed and that issues have been resolved.

  3. C+E accessibility team will schedule vendor testing.

  4. Vendor testing occurs. Vendors will open bugs directly to extension team's backlog.

  5. Follow Bug triage process.

  6. After all bugs are in Closed State extension team can go to GA.

C&E accessibility team governs all extensions compliance status and coordinates all vendor testing. Any questions regarding accessibility compliance should be routed to C+E Accessibility Core Team.

Testing for accessibility

When testing extensions, a report is created and made available to the extension team.

  • Ibiza provides a list of common patterns that are not issues, with justifications/explanations
  • Ibiza provides a list of external product bugs that are not issues to fix with justifications and bug links.

High-contrast

Windows High Contrast Mode (WHCM) has native support for Internet Explorer and Microsoft Edge. Other browsers do not support WHCM natively, and neither do other operating systems, therefore a custom theme is provided in the settings pane of the Portal.

NOTE: The custom theme is a good approximation of WHCM behavior and can be used to quickly verify compliance. To properly verify, use High Contrast settings option 2 with Microsoft Edge.

Screen reader

Compliance with Narrator/Microsoft Edge are screen reader requirements.

Accessibility test engines

The following Websites provide accessibility test engines.

Name Purpose
aXe: the Accessibility Engine An open source rules library for accessibility testing
Accessibility testing in Chrome Developer Tools Chrome plugin
aXe Developer Tools Firefox plugin
Accessibility engine for automated Web UI testing axe-core (unit testing)

Troubleshooting issues

After developing and testing an extension for accessibility, if there are still issues, they may be known by the Framework team. Review this site to determine whether there are any known issues. If this is a new issue, you can file a Framework bug here on controls owned by the Framework.

Accessibility Planning

Ibiza has streamlined the process of handling accessibility issues. When we resolve bugs, we send out updates for folks to be aware of progress, in addition to regressing testing updates from vendor teams. Please reach out to ibiza-accessibility@microsoft.com if there are any other questions or concerns.

  1. If a scenario results in multiple issues, you should separate those issues in separate bugs. Bugs with multiple issues cannot be resolved reliably.

  2. Ensure that attachments, like .img, and .png files, contain screenshots with highlighted problem areas. Videos alone have not been helpful.

  3. Screen reader issues, like alt-text and aria-attr labels, should be reported from testing with Microsoft Edge using Narrator, or Firefox using NVDA. Other combinations will be deferred.

  4. Screen reader fixes will be done for Microsoft Edge using Narrator on Windows 10 Creators Update, and Firefox with NVDA. Regression testing should take those consideration into account.

  5. Iframes are outside of the scope of the Framework, and do not have any dependencies on the Framework. Developers are responsible for testing and fixing these scenarios.

  6. Legacy controls are being deprecated, and extensions should move to the updated version of the control in order to meet accessibility standards. A list of legacy controls is located here.

  7. Use this bug template to file bugs with the Azure team.

Bug Tagging

About 95% of issues can be separated into eight categories. All bugs that you feel are framework issues need to be assigned to Paymon Parsadmehr. If you feel that a bug falls into more than one category, please add all corresponding tags to the bug. If the bug does not fit any category, reach out to Paymon Parsadmehr to assess the issue.

The following is a description of the eight tags and their categories. There are also examples of each bug class to help you determine what tags to use if you still need to file a bug.

  1. Alternate Text

    ERROR: Screen reader reads the text content, but the output is not helpful, or the output needs to be more descriptive, or no output is read except the control type.

    TAG: AltText

    • Example: Screen reader cursor is on a part and all the part content is read instead of expected text.
    • Example: Screen reader cursor is on an option picker control and all the options are read instead of a label.
    • Bug example: RDBug 8105335: Azure API Management Service: More Services: Name Property is Empty for "Search the Market Place" edit box

    NOTE: Fixing bugs in this category may require downstream code changes. This is a top priority for the Ibiza team. We will send updates as we release SDK’s with updated controls.

  2. Aria-attribute

    ERROR: Functionality not exposed to screen readers.

    TAG: Aria-attr

    • Bug example: RDBug 8259873: Accessibility: MAS40B: Inspect: "Name" property is empty for 'Create' group.[Scenario: Creating NameSpace]

  3. Contrast-Ratio

    ERROR: Contrast ratio of text color against background is insufficient (high contrast is a different issue).

    TAG: ContrastRatio

    • Example: Text does not have a contrast ratio of at least 7:1 on button in the “Azure” theme.
    • Bug example: RDBug 8091694: [Accessibility] Luminosity contrast ratio is less than 4.5:1 for "Support" link in feedback pane under "Blue Alt" theme

  4. High Contrast

    ERROR: All issues related to High Contrast mode.

    TAG: Highcontrast

    • Example: Focus not visible while using High Contrast Black-on-White mode in Microsoft Edge on buttons.
    • Bug example: RDBug 8133287: Ibiza Portal: Accessibility: High Contrast - Black: Data Lake: All Resources: Previous Page button is not visible in High Contrast - Black Theme

  5. Focus-management

    ERROR: Focus set at an unexpected place, or focus is lost, or focus is trapped.

    TAG: Focus-management

    • Example: Focus lost when switching value in dropdown via keyboard.
    • Example: Cannot focus away from button once it captures focus.
    • Bug example: RDBug 8679020: [Keyboard Navigation - KeyVault -Select Principle ] Focus order is not logical on the "Select Principle" blade.

  6. Keyboard Accessibility

    ERROR: Activation and interaction via keyboard not working as expected or is inconsistent, or the item cannot be accessed via keyboard.

    TAG: KeyboardAccess

    • Example: Cannot tab to button.
    • Example: Cannot activate button with spacebar key.
    • Bug example: RDBug 8220516: [Ibiza Portal]: Accessibility: MAS36: KB: Unable to access the Add to Favorites button (star button) for (Service Bus, Event Hubs, Relays) when navigated from "More Services -> Search Filter -> Service Bus/Event Hubs/Relays".

  7. Grid

    ERROR: All issues related to Grid, regardless of the previous issues mentioned.

    TAG: Grid

    • Example: Grid does not expose the column header on the cell (would be Aria-attr, yet triages as Grid).
    • Bug example: RDBug 8882413: Ibiza Portal:[B2A][E2A][E2E][V2A]Accessibility: Inspect :MAS40B: Name property is Inappropriate for column header items in 'Jobs' page of Azure Portal.

  8. ListView

    ERROR: All issues related to ListView, regardless of the previous issues mentioned.

    TAG: ListView

    • Example: ListView does not read any content when focus is set on an element (would be AltText, yet triage as ListView).
    • Bug example: RDBug 8133284: Ibiza Portal: Usability: Narrator: Intune Data Lake: New: Narrator announces Contains 0 items for a list of 3 or more items

For more information

For more information about developing extensions with accessibility, see the following publications -

Best Practices

  1. Design and code your extension with accessibility in mind

  2. Use Portal tiles/parts, forms, and controls whenever possible, as those are designed to be accessible

  3. Use HTML semantics when using custom HTML, as described in https://www.w3schools.com/html/html5_semantic_elements.asp. For example, create buttons with the BUTTON tag instead of a styled DIV tag.

  4. Avoid using aria-* attributes. If you find yourself using those attributes, review your design and try to use HTML semantics as much as possible.

  5. Provide concise, meaningful instructions for user input.

  6. Scrub your content for consistent terminology and iconography before releasing it to the public

  7. Always use multiple sensory cues to convey information. Never use the position, orientation, size, shape, or color of a UI element alone to communicate important information to the user.