diff --git a/packages/terra-clinical-detail-view/CHANGELOG.md b/packages/terra-clinical-detail-view/CHANGELOG.md index 7909f3e46..06e9a270b 100644 --- a/packages/terra-clinical-detail-view/CHANGELOG.md +++ b/packages/terra-clinical-detail-view/CHANGELOG.md @@ -2,6 +2,9 @@ ## Unreleased +* Added + * Added accessibility guide + ## 3.31.0 - (June 22, 2023) * Added diff --git a/packages/terra-clinical-detail-view/src/terra-dev-site/doc/clinical-detail-view/AccessibilityGuide.4.doc.mdx b/packages/terra-clinical-detail-view/src/terra-dev-site/doc/clinical-detail-view/AccessibilityGuide.4.doc.mdx new file mode 100644 index 000000000..2754b9d6e --- /dev/null +++ b/packages/terra-clinical-detail-view/src/terra-dev-site/doc/clinical-detail-view/AccessibilityGuide.4.doc.mdx @@ -0,0 +1,161 @@ +import { Notice } from "@cerner/terra-docs"; +import { Badge } from 'terra-image/package.json?dev-site-package'; +import DetailViewDivided from '../example/DetailViewDivided?dev-site-example'; + + + +# Accessibility Guide for Terra Clinical Detail View + +## Why is this important? + +> The Terra Clinical Detail Views allows you to create a view with text at different levels of importance. Using the terra-clinical-detail-view improperly may prevent some of your 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/)_[[1]](/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 DetailView 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 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. + +It is highly recommended to utilize the `level` prop to set the appropriate heading level of the Title to match the hierarchical structure of the page. The level prop 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 = (); + + + + + ), + ]} +/> +``` + +#### Named Section Behavior: + +All of the content related to the 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 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. + +#### Accessibility Considerations: Caption for graphs: + +The graph prop is used to set visualization content such as graphs, or images based on the data. This graph prop is wrapped in an [`
`](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 [`
`](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. + +**Example:** + + + +#### Accessibility Considerations: 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 `
` list item content and `
` list item content. `
` and `
` content must be logically connected. With label-value pairs in description lists, the `
` holds the “label” and the `
` holds the “value” associated with the label. The two are always together. + +It is highly recommended that the `isLabelValuePairList` prop 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. The terra-clinical-label-value-view component with isChildOfDescriptionList=true can also be used as it will return the label and value using the appropriate `
` and `
` elements. + +Code Example: +```jsx +const detail1item1 = (); +const detail1item2 = (); + +const detail2item1 = (); +const detail2item2 = (); + +const detail3item1 = ( +
+
+ +
+
+ Immediate Priority +
+
+); +const detail3item2 = ( +
+
+ +
+
+ Pharmacy Review +
+
+); + + + + + + ), + ( + + + + + ), + ( + + + + + ), + ]} + /> +``` + +## Support Compliance + +Terra is committed to ensuring its components provide maximum possible accessibility. However, 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/TR/WCAG21/#consistent-identification) - Components that have the same functionality within a set of Web pages are identified consistently. +- [**4.2.1 Name, Role, Value**](https://www.w3.org/TR/WCAG21/#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 + +- Report a problem with this component on [**GitHub**](https://github.com/cerner/terra-core/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/) \ No newline at end of file