This repository has been archived by the owner on May 22, 2024. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 50
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
[terra-clinical-detail-view] Added terra-clinical-detail-view accessi…
…bility guide (#878)
- Loading branch information
1 parent
14ca4ee
commit d238bdd
Showing
4 changed files
with
176 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
173 changes: 173 additions & 0 deletions
173
...l-view/src/terra-dev-site/doc/clinical-detail-view/AccessibilityGuide.2.doc.mdx
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,173 @@ | ||
| import { Notice } from "@cerner/terra-docs"; | ||
| import { Badge } from 'terra-clinical-detail-view/package.json?dev-site-package'; | ||
| import DetailViewDivided from '../example/DetailViewDivided?dev-site-example'; | ||
|
|
||
| <Badge /> | ||
|
|
||
| # Accessibility Guide for Terra Clinical Detail View | ||
|
|
||
| ## Why is this important? | ||
|
|
||
| Terra Clinical Detail View allows you to create a view with text at different levels of importance. Improper usage of this component may prevent end users from understanding content and necessary context to interact with the page. | ||
| > | ||
| > Pages with well-structured content are essential for many web users, for example: | ||
| > - **People with cognitive and learning disabilities** can more easily find and prioritize content on the page. | ||
| > - **People using screen readers** can skip to the main content directly and navigate to sections that are important to them. | ||
| > - **Keyboard users** can browse pages and their sections more efficiently. Otherwise, users have to press the tab key multiple times to navigate through all links in each section. | ||
| > - **People using software that only shows the main content** of a web page, such as people with cognitive disabilities, will receive better results if the page structure is correctly marked up. | ||
| > - **People with visual impairments**, including people with low vision, have cues that provide orientation on the page and in the content. | ||
| > - **Mobile web users** often have access to a so-called “reader” or “reading” mode that will only show the main content of the page if it is correctly marked up. | ||
| > - **People using certain browser plugins** can use landmark roles to jump to specific sections on a page. | ||
| > | ||
| > _ — excerpt from [Page Structure Concepts (W3C: Web Accessibility Tutorials)](https://www.w3.org/WAI/tutorials/page-structure/)_[<sup>[1]</sup>](/components/terra-clinical-detail-view/clinical-detail-view/accessibility-guide#linked-references) | ||
|
|
||
| ## Accessibility Considerations | ||
|
|
||
| ### Code Considerations | ||
|
|
||
| #### Maintaining a hierarchical content structure on the page: | ||
|
|
||
| > Sighted users perceive structure and relationships through various visual cues — headings are often in a larger, bold font separated from the content they represent. | ||
| > | ||
| > _ — excerpt from [W3C: Info and Relationships (Level A)](https://www.w3.org/WAI/WCAG21/Understanding/info-and-relationships)_ | ||
| > Visual readers can identify headings by scanning pages for text of a larger size or a different color/font face. Blind users/users with low vision on a screen reader are not able to see these visual distinctions, so increasing the font size is not a sufficient cue. Instead, the headings must be semantically "tagged" so that a screen reader can identify headings, navigate the page and provide structure as a page or document table of contents | ||
| > | ||
| > _ — excerpt from [Accessibility and Usability at Penn State: Heading tags](https://accessibility.psu.edu/headingshtml/)_ | ||
| The Clinical Detail View component creates a view with text at different levels of importance. The HTML heading tag is used to create the structure of the page. It is critical to screen reader users that the `level` [prop](https://engineering.cerner.com/terra-ui/components/terra-clinical-detail-view/clinical-detail-view/clinical-detail-view#detail-view-props-table) be appropriately set to a value that best represents the placement of the main Clinical Detail View heading in the existing structure of the page. Think about headings as creating the outline of a page. Each heading level should be set to represent that outline structure. Screen reader users rely on the heading levels to understand the structure of information on the page. | ||
|
|
||
| <Notice variant="important" ariaLevel="5"> | ||
|
|
||
| It is highly recommended to utilize the `level` [prop](https://engineering.cerner.com/terra-ui/components/terra-clinical-detail-view/clinical-detail-view/clinical-detail-view#detail-view-props-table) to set the appropriate heading level of the Title to match the hierarchical structure of the page. The `level` [prop](https://engineering.cerner.com/terra-ui/components/terra-clinical-detail-view/clinical-detail-view/clinical-detail-view#detail-view-props-table) will also set the SecondaryTitles and the `title` of the Detail List structures to the appropriate heading level to ensure a hierarchical content structure. | ||
|
|
||
| Code Example: | ||
| ```jsx | ||
| const item1 = (<LabelValueView label="Start Date" textValue="12/12/12 00:00AM" isChildOfDescriptionList />); | ||
|
|
||
| <DetailView | ||
| title="Multiple Ingredients" | ||
| level={4} | ||
| secondaryTitles={['M. V. I. Adult 10 mL = 10 mL', 'Sodium bicarbonate 8.4% 50 mL', 'Dextrose 5% in Water 1000 mL']} | ||
| details={[ | ||
| ( | ||
| <DetailView.DetailList title={detail1title} key="Indicators" isLabelValuePairList> | ||
| <DetailView.DetailListItem item={item1} /> | ||
| </DetailView.DetailList> | ||
| ), | ||
| ]} | ||
| /> | ||
| ``` | ||
|
|
||
| </Notice> | ||
|
|
||
| #### Named Section Behavior: | ||
|
|
||
| All of the content related to the Clinical Detail View should be understood as a section and the `title` prop is used to programmatically create a label for the region. It is critical to screen reader users that the title [prop](https://engineering.cerner.com/terra-ui/components/terra-clinical-detail-view/clinical-detail-view/clinical-detail-view#detail-view-props-table) be set to a value that best represents the region that groups the details in the section within the page. Screen reader users rely on the title to know the beginning and end of a region, and to navigate to the specific region on the page. Leaving the title off of the section hurts the accessibility of the component by removing the programmatic indication of the region on the page. The region/section won't be announced by Assistive Technology (AT) if there is no programmatically associated label. | ||
|
|
||
| #### Caption for graphs: | ||
|
|
||
| The `graph` [prop](https://engineering.cerner.com/terra-ui/components/terra-clinical-detail-view/clinical-detail-view/clinical-detail-view#detail-view-props-table) is used to set visualization content such as graphs, or images based on the data. This graph [prop](https://engineering.cerner.com/terra-ui/components/terra-clinical-detail-view/clinical-detail-view/clinical-detail-view#detail-view-props-table) is wrapped in an [`<figure>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/figure) element. | ||
| Figure captions help the users understand and correctly interpret the visualization. | ||
| It is critical to screen reader users that the caption be set with [`<figcaption>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/figcaption) element as the first, or the last element to provide the caption for the figure. | ||
|
|
||
| ``` | ||
| Note: figcaption content is not a replacement for the alt text that needs to be supplied for images in the figure element. | ||
| ``` | ||
|
|
||
| When using figcaption element, which requires a parent element, it is necessary to wrap the elements within a `<React.Fragment>` block. | ||
|
|
||
| <div aria-label="Example demo"> | ||
| <DetailViewDivided /> | ||
| </div> | ||
|
|
||
| #### Associate label-value pairs: | ||
|
|
||
| The DetailList sub-component is often used to create a list of items associated together. An HTML unordered list or a description list is used to create the visual and programmatic association of the list. Content that is supplied for description lists includes `<dt>` list item content and `<dd>` list item content. `<dt>` and `<dd>` content must be logically connected. With label-value pairs in description lists, the `<dt>` holds the “label” and the `<dd>` holds the “value” associated with the label. The two are always together. | ||
|
|
||
| <Notice variant="important" ariaLevel="5"> | ||
|
|
||
| It is highly recommended that the `isLabelValuePairList` [prop](https://engineering.cerner.com/terra-ui/components/terra-clinical-detail-view/clinical-detail-view/clinical-detail-view#detail-view-props-table) is set to true when the list contains label-value pairs. By setting this prop to true, we use the HTML description list to create the programmatic structure of the label (a term) to a value (a definition). This semantic structure is critical to support users of assistive technology so that they can properly relate information in the list together. The DetailList should be understood as a description list when it contains label-value pairs and the DetailList should be understood as an unordered list when it contains other HTML elements passed in by the consumer. | ||
|
|
||
| Code Example: | ||
| ```jsx | ||
| const detail1item1 = (<LabelValueView label="Age of onset" textValue="38 years" isChildOfDescriptionList />); | ||
| const detail1item2 = (<LabelValueView label="Reviewed" textValue="07/10/2012 10:00AM" isChildOfDescriptionList />); | ||
|
|
||
| const detail2item1 = (<LabelValueView label="Start Date" textValue="12/12/12 00:00AM" isChildOfDescriptionList />); | ||
| const detail2item2 = (<LabelValueView label="Stop Date" textValue="12/12/12 10:00AM" isChildOfDescriptionList />); | ||
|
|
||
| const detail3item1 = ( | ||
| <div className={cx('indicator-container')}> | ||
| <div className={cx('icon')}> | ||
| <IconCritical a11yLabel="Critical Icon" /> | ||
| </div> | ||
| <div className={cx('text')}> | ||
| Immediate Priority | ||
| </div> | ||
| </div> | ||
| ); | ||
| const detail3item2 = ( | ||
| <div className={cx('indicator-container')}> | ||
| <div className={cx('icon')}> | ||
| <IconPharmacyReview a11yLabel="Pharmacy Review" /> | ||
| </div> | ||
| <div className={cx('text')}> | ||
| Pharmacy Review | ||
| </div> | ||
| </div> | ||
| ); | ||
|
|
||
| <DetailView | ||
| title="Mother" | ||
| level={3} | ||
| subtitles={['Martha (58 years)', '[second line for subtitles]']} | ||
| details={[ | ||
| ( | ||
| <DetailView.DetailList title={detail1title} key="order-info-1" isLabelValuePairList> | ||
| <DetailView.DetailListItem item={detail1item1} /> | ||
| <DetailView.DetailListItem item={detail1item2} /> | ||
| </DetailView.DetailList> | ||
| ), | ||
| ( | ||
| <DetailView.DetailList title={detail2title} key="order-info-2" isLabelValuePairList> | ||
| <DetailView.DetailListItem item={detail2item1} /> | ||
| <DetailView.DetailListItem item={detail2item2} /> | ||
| </DetailView.DetailList> | ||
| ), | ||
| ( | ||
| <DetailView.DetailList title={detail3title} key="order-info-3" > | ||
| <DetailView.DetailListItem item={detail3item1} /> | ||
| <DetailView.DetailListItem item={detail3item2} /> | ||
| </DetailView.DetailList> | ||
| ), | ||
| ]} | ||
| /> | ||
| ``` | ||
|
|
||
| </Notice> | ||
|
|
||
| ## Support Compliance | ||
|
|
||
| Terra is committed to ensuring its components provide maximum possible accessibility. However, simply using Terra components will not automatically make a product accessible. | ||
|
|
||
| Final responsibility lies with the consumers of Terra components — ensuring proper usage, engineers following correct implementation patterns, and authors crafting content that follows best practice guidance — to make a product fully accessible. | ||
|
|
||
| ### WCAG Resources | ||
|
|
||
| - [**1.1.1 Non-text Content**](https://www.w3.org/WAI/WCAG21/Understanding/non-text-content) - All non-text content that is presented to the user has a text alternative that serves the equivalent purpose. | ||
| - [**1.3.1 Info and Relationships**](https://www.w3.org/WAI/WCAG21/Understanding/info-and-relationships) - Information, structure, and relationships conveyed through presentation can be programmatically determined or are available in text. (Level A) | ||
| - [**3.2.4 Consistent Identification**](https://www.w3.org/WAI/WCAG21/Understanding/consistent-identification) - Components that have the same functionality within a set of Web pages are identified consistently. | ||
| - [**4.1.2 Name, Role, Value**](https://www.w3.org/WAI/WCAG21/Understanding/name-role-value) - For all user interface components (including but not limited to: form elements, links and components generated by scripts), the name and role can be programmatically determined; states, properties, and values that can be set by the user can be programmatically set; and notification of changes to these items is available to user agents, including assistive technologies. | ||
|
|
||
| ### Partial Support & Requiring Further Enhancement | ||
|
|
||
| - None identified | ||
| - Report a problem with this component on [**GitHub**](https://github.com/cerner/terra-clinical/issues/new/choose) | ||
|
|
||
| _For more information about Accessibility Support with Terra — go to [Component Standards: Accessibility (A11y)](https://engineering.cerner.com/terra-ui/about/terra-ui/component-standards#accessibility-a11y)._ | ||
|
|
||
| ## Linked References: | ||
|
|
||
| 1. [W3C Page Structure](https://www.w3.org/WAI/tutorials/page-structure/) |
File renamed without changes.
File renamed without changes.