From 08debdcd4f42477a26fed8738aad34fa72cb69dc Mon Sep 17 00:00:00 2001 From: Vinay Bhargav Arni Ragunathan Date: Tue, 27 Jun 2023 10:10:05 -0400 Subject: [PATCH 01/10] [terra-clinical-detail-view] Add accessibility guide --- .../terra-clinical-detail-view/CHANGELOG.md | 3 + .../AccessibilityGuide.4.doc.mdx | 161 ++++++++++++++++++ 2 files changed, 164 insertions(+) create mode 100644 packages/terra-clinical-detail-view/src/terra-dev-site/doc/clinical-detail-view/AccessibilityGuide.4.doc.mdx diff --git a/packages/terra-clinical-detail-view/CHANGELOG.md b/packages/terra-clinical-detail-view/CHANGELOG.md index 887b19cb9..f4e97da2f 100644 --- a/packages/terra-clinical-detail-view/CHANGELOG.md +++ b/packages/terra-clinical-detail-view/CHANGELOG.md @@ -5,6 +5,9 @@ * Changed * Update Detail List to accept null as children +* 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 From bb30293d159c30e7eac285c225e151f0951f1e8c Mon Sep 17 00:00:00 2001 From: Vinay Bhargav Arni Ragunathan Date: Wed, 28 Jun 2023 17:16:36 -0400 Subject: [PATCH 02/10] Fix typos --- .../AccessibilityGuide.4.doc.mdx | 16 +++++++--------- 1 file changed, 7 insertions(+), 9 deletions(-) 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 index 2754b9d6e..5e3c732ab 100644 --- 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 @@ -8,7 +8,7 @@ import DetailViewDivided from '../example/DetailViewDivided?dev-site-example'; ## 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. +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. @@ -24,8 +24,6 @@ import DetailViewDivided from '../example/DetailViewDivided?dev-site-example'; ## 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. > @@ -35,7 +33,7 @@ import DetailViewDivided from '../example/DetailViewDivided?dev-site-example'; > > _  — 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. +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. @@ -50,7 +48,7 @@ const item1 = ( - + ), ]} @@ -61,7 +59,7 @@ const item1 = (`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/figure) element. Figure captions help the users understand and correctly interpret the visualization. @@ -71,17 +69,17 @@ It is critical to screen reader users that the caption be set with [`
` block. **Example:** -#### Accessibility Considerations: Associate label-value pairs: +#### 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. +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. Code Example: ```jsx From d71eb6f1498225be099e561b12349eb49081d137 Mon Sep 17 00:00:00 2001 From: Vinay Bhargav Arni Ragunathan Date: Thu, 29 Jun 2023 19:22:10 -0400 Subject: [PATCH 03/10] Change look and feel --- ...4.doc.mdx => AccessibilityGuide.2.doc.mdx} | 29 ++++++++++++------- ...hangeLog.3.doc.mdx => ChangeLog.4.doc.mdx} | 0 ...Guide.2.doc.mdx => UpgradeGuide.3.doc.mdx} | 0 3 files changed, 19 insertions(+), 10 deletions(-) rename packages/terra-clinical-detail-view/src/terra-dev-site/doc/clinical-detail-view/{AccessibilityGuide.4.doc.mdx => AccessibilityGuide.2.doc.mdx} (71%) rename packages/terra-clinical-detail-view/src/terra-dev-site/doc/clinical-detail-view/{ChangeLog.3.doc.mdx => ChangeLog.4.doc.mdx} (100%) rename packages/terra-clinical-detail-view/src/terra-dev-site/doc/clinical-detail-view/{UpgradeGuide.2.doc.mdx => UpgradeGuide.3.doc.mdx} (100%) 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.2.doc.mdx similarity index 71% rename from packages/terra-clinical-detail-view/src/terra-dev-site/doc/clinical-detail-view/AccessibilityGuide.4.doc.mdx rename to packages/terra-clinical-detail-view/src/terra-dev-site/doc/clinical-detail-view/AccessibilityGuide.2.doc.mdx index 5e3c732ab..433b02786 100644 --- 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.2.doc.mdx @@ -22,7 +22,9 @@ The Terra Clinical Detail Views allows you to create a view with text at differe > _  — 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: +## 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. @@ -33,9 +35,13 @@ The Terra Clinical Detail Views allows you to create a view with text at differe > > _  — 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. +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](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. + + + +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. -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 @@ -57,11 +63,11 @@ const item1 = (`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/figure) element. +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 [`
`](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. @@ -71,15 +77,15 @@ Note: figcaption content is not a replacement for the alt text that needs to be When using figcaption element, which requires a parent element, it is necessary to wrap the elements within a `` block. -**Example:** - - +
+ +
#### 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. +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 @@ -140,6 +146,7 @@ const detail3item2 = ( ## 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 @@ -151,8 +158,10 @@ Final responsibility lies with the consumers of Terra components — ensurin ### Partial Support & Requiring Further Enhancement +- None identified - 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)._ + +_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: diff --git a/packages/terra-clinical-detail-view/src/terra-dev-site/doc/clinical-detail-view/ChangeLog.3.doc.mdx b/packages/terra-clinical-detail-view/src/terra-dev-site/doc/clinical-detail-view/ChangeLog.4.doc.mdx similarity index 100% rename from packages/terra-clinical-detail-view/src/terra-dev-site/doc/clinical-detail-view/ChangeLog.3.doc.mdx rename to packages/terra-clinical-detail-view/src/terra-dev-site/doc/clinical-detail-view/ChangeLog.4.doc.mdx diff --git a/packages/terra-clinical-detail-view/src/terra-dev-site/doc/clinical-detail-view/UpgradeGuide.2.doc.mdx b/packages/terra-clinical-detail-view/src/terra-dev-site/doc/clinical-detail-view/UpgradeGuide.3.doc.mdx similarity index 100% rename from packages/terra-clinical-detail-view/src/terra-dev-site/doc/clinical-detail-view/UpgradeGuide.2.doc.mdx rename to packages/terra-clinical-detail-view/src/terra-dev-site/doc/clinical-detail-view/UpgradeGuide.3.doc.mdx From 92089c11144bdc7c39fa8a4745e29602e664ee96 Mon Sep 17 00:00:00 2001 From: Vinay Bhargav Arni Ragunathan <55503680+vinaybhargavar@users.noreply.github.com> Date: Thu, 29 Jun 2023 19:22:56 -0400 Subject: [PATCH 04/10] Add full stop Co-authored-by: Saad Adnan <38024451+sdadn@users.noreply.github.com> --- packages/terra-clinical-detail-view/CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/terra-clinical-detail-view/CHANGELOG.md b/packages/terra-clinical-detail-view/CHANGELOG.md index f4e97da2f..76fb96204 100644 --- a/packages/terra-clinical-detail-view/CHANGELOG.md +++ b/packages/terra-clinical-detail-view/CHANGELOG.md @@ -6,7 +6,7 @@ * Update Detail List to accept null as children * Added - * Added accessibility guide + * Added accessibility guide. ## 3.31.0 - (June 22, 2023) From fb27400383d80ff3854e8db46b7ab44e1170ff11 Mon Sep 17 00:00:00 2001 From: Vinay Bhargav Arni Ragunathan Date: Fri, 30 Jun 2023 21:40:15 -0400 Subject: [PATCH 05/10] Address PR comments --- .../doc/clinical-detail-view/AccessibilityGuide.2.doc.mdx | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/packages/terra-clinical-detail-view/src/terra-dev-site/doc/clinical-detail-view/AccessibilityGuide.2.doc.mdx b/packages/terra-clinical-detail-view/src/terra-dev-site/doc/clinical-detail-view/AccessibilityGuide.2.doc.mdx index 433b02786..206cd7498 100644 --- a/packages/terra-clinical-detail-view/src/terra-dev-site/doc/clinical-detail-view/AccessibilityGuide.2.doc.mdx +++ b/packages/terra-clinical-detail-view/src/terra-dev-site/doc/clinical-detail-view/AccessibilityGuide.2.doc.mdx @@ -67,7 +67,7 @@ All of the content related to the Detail View should be understood as a section #### 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 [`
`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/figure) element. +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 [`
`](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. @@ -85,8 +85,12 @@ When using figcaption element, which requires a parent element, it is necessary 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](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 = (); From 857f7216258115fce6634e84dff7e27976163114 Mon Sep 17 00:00:00 2001 From: Vinay Bhargav Arni Ragunathan Date: Wed, 5 Jul 2023 14:38:07 -0400 Subject: [PATCH 06/10] Fix PR comments --- .../doc/clinical-detail-view/AccessibilityGuide.2.doc.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/terra-clinical-detail-view/src/terra-dev-site/doc/clinical-detail-view/AccessibilityGuide.2.doc.mdx b/packages/terra-clinical-detail-view/src/terra-dev-site/doc/clinical-detail-view/AccessibilityGuide.2.doc.mdx index 206cd7498..886420930 100644 --- a/packages/terra-clinical-detail-view/src/terra-dev-site/doc/clinical-detail-view/AccessibilityGuide.2.doc.mdx +++ b/packages/terra-clinical-detail-view/src/terra-dev-site/doc/clinical-detail-view/AccessibilityGuide.2.doc.mdx @@ -53,7 +53,7 @@ const item1 = ( + ), @@ -163,7 +163,7 @@ Final responsibility lies with the consumers of Terra components — ensurin ### Partial Support & Requiring Further Enhancement - None identified -- Report a problem with this component on [**GitHub**](https://github.com/cerner/terra-core/issues/new/choose) +- 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)._ From 730a3b1a89a4eecdfbd9a219dd16e75abb7453e8 Mon Sep 17 00:00:00 2001 From: Vinay Bhargav Arni Ragunathan Date: Wed, 5 Jul 2023 14:45:48 -0400 Subject: [PATCH 07/10] Update WCAG resource links --- .../doc/clinical-detail-view/AccessibilityGuide.2.doc.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/terra-clinical-detail-view/src/terra-dev-site/doc/clinical-detail-view/AccessibilityGuide.2.doc.mdx b/packages/terra-clinical-detail-view/src/terra-dev-site/doc/clinical-detail-view/AccessibilityGuide.2.doc.mdx index 886420930..c65256ed6 100644 --- a/packages/terra-clinical-detail-view/src/terra-dev-site/doc/clinical-detail-view/AccessibilityGuide.2.doc.mdx +++ b/packages/terra-clinical-detail-view/src/terra-dev-site/doc/clinical-detail-view/AccessibilityGuide.2.doc.mdx @@ -157,8 +157,8 @@ Final responsibility lies with the consumers of Terra components — ensurin - [**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. +- [**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 From 86be4da4ca8d997ab7bd3e39963c33f9440b16da Mon Sep 17 00:00:00 2001 From: Vinay Bhargav Arni Ragunathan Date: Wed, 5 Jul 2023 16:17:37 -0400 Subject: [PATCH 08/10] Address PR comments --- .../AccessibilityGuide.2.doc.mdx | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/packages/terra-clinical-detail-view/src/terra-dev-site/doc/clinical-detail-view/AccessibilityGuide.2.doc.mdx b/packages/terra-clinical-detail-view/src/terra-dev-site/doc/clinical-detail-view/AccessibilityGuide.2.doc.mdx index c65256ed6..0e4219780 100644 --- a/packages/terra-clinical-detail-view/src/terra-dev-site/doc/clinical-detail-view/AccessibilityGuide.2.doc.mdx +++ b/packages/terra-clinical-detail-view/src/terra-dev-site/doc/clinical-detail-view/AccessibilityGuide.2.doc.mdx @@ -1,5 +1,5 @@ import { Notice } from "@cerner/terra-docs"; -import { Badge } from 'terra-image/package.json?dev-site-package'; +import { Badge } from 'terra-clinical-detail-view/package.json?dev-site-package'; import DetailViewDivided from '../example/DetailViewDivided?dev-site-example'; @@ -8,7 +8,7 @@ import DetailViewDivided from '../example/DetailViewDivided?dev-site-example'; ## 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. +Terra Clinical Detail View allows you to create a view with text at different levels of importance. Using this component 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. @@ -27,6 +27,7 @@ The Terra Clinical Detail Views allows you to create a view with text at differe ### 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)_ @@ -35,14 +36,12 @@ The Terra Clinical Detail Views allows you to create a view with text at differe > > _  — 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](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. +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. 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 = (); @@ -61,9 +60,11 @@ 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](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. +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: @@ -89,8 +90,6 @@ The DetailList sub-component is often used to create a list of items associated 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 = (); @@ -147,6 +146,8 @@ const detail3item2 = ( /> ``` + + ## Support Compliance Terra is committed to ensuring its components provide maximum possible accessibility. However, using Terra components will not automatically make a product accessible. From 687a94f34683c6250c0ad95d44b6cf8e078beee9 Mon Sep 17 00:00:00 2001 From: Vinay Bhargav Arni Ragunathan <55503680+vinaybhargavar@users.noreply.github.com> Date: Fri, 7 Jul 2023 16:26:47 -0400 Subject: [PATCH 09/10] PR update Co-authored-by: Saad Adnan <38024451+sdadn@users.noreply.github.com> --- .../doc/clinical-detail-view/AccessibilityGuide.2.doc.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/terra-clinical-detail-view/src/terra-dev-site/doc/clinical-detail-view/AccessibilityGuide.2.doc.mdx b/packages/terra-clinical-detail-view/src/terra-dev-site/doc/clinical-detail-view/AccessibilityGuide.2.doc.mdx index 0e4219780..c510bd135 100644 --- a/packages/terra-clinical-detail-view/src/terra-dev-site/doc/clinical-detail-view/AccessibilityGuide.2.doc.mdx +++ b/packages/terra-clinical-detail-view/src/terra-dev-site/doc/clinical-detail-view/AccessibilityGuide.2.doc.mdx @@ -8,7 +8,7 @@ import DetailViewDivided from '../example/DetailViewDivided?dev-site-example'; ## Why is this important? -Terra Clinical Detail View allows you to create a view with text at different levels of importance. Using this component improperly may prevent some of your users from understanding content and necessary context to interact with the page. +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. From dd31f0bb184ab49a962655a2c2b6267429f63fd0 Mon Sep 17 00:00:00 2001 From: Vinay Bhargav Arni Ragunathan <55503680+vinaybhargavar@users.noreply.github.com> Date: Fri, 7 Jul 2023 16:27:09 -0400 Subject: [PATCH 10/10] PR updates Co-authored-by: Saad Adnan <38024451+sdadn@users.noreply.github.com> --- .../doc/clinical-detail-view/AccessibilityGuide.2.doc.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/terra-clinical-detail-view/src/terra-dev-site/doc/clinical-detail-view/AccessibilityGuide.2.doc.mdx b/packages/terra-clinical-detail-view/src/terra-dev-site/doc/clinical-detail-view/AccessibilityGuide.2.doc.mdx index c510bd135..d9b4d0288 100644 --- a/packages/terra-clinical-detail-view/src/terra-dev-site/doc/clinical-detail-view/AccessibilityGuide.2.doc.mdx +++ b/packages/terra-clinical-detail-view/src/terra-dev-site/doc/clinical-detail-view/AccessibilityGuide.2.doc.mdx @@ -150,7 +150,7 @@ const detail3item2 = ( ## Support Compliance -Terra is committed to ensuring its components provide maximum possible accessibility. However, using Terra components will not automatically make a product accessible. +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.