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-item-view] Accessibility guide
- Loading branch information
ry061521
committed
Sep 14, 2023
1 parent
fe3740c
commit 40e3758
Showing
2 changed files
with
199 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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -2,6 +2,9 @@ | |
|
|
||
| ## Unreleased | ||
|
|
||
| * Added | ||
| * Added accessibility guide. | ||
|
|
||
| ## 4.10.0 - (August 16, 2023) | ||
|
|
||
| * Changed | ||
|
|
||
196 changes: 196 additions & 0 deletions
196
...tem-view/src/terra-dev-site/doc/clinical-item-view/AccessibilityGuide.4.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,196 @@ | ||
| import { Badge } from 'terra-clinical-item-view/package.json?dev-site-package'; | ||
| import { Notice } from "@cerner/terra-docs"; | ||
|
|
||
| <Badge /> | ||
|
|
||
| # Accessibility Guide for Terra Clinical Item View | ||
|
|
||
| ## Why is this important? | ||
|
|
||
| Terra Clinical Item View allows you to create a view filled with information in the form of Clinical Item Displays. Improper usage of this component may prevent end users from understanding content and necessary context to interact with the page. | ||
|
|
||
| ## Accessibility Considerations | ||
|
|
||
| #### General notes | ||
| - **Related information should be presented as close to each other as possible.** It is best practice to keep related information above or below its related counterparts. | ||
| - For example: presenting related information across from each other in the two column view can make it more difficult for users to understand that the information is related. | ||
| Reading by column from top to bottom is the more common way information is consumed visually, so when presenting this information by row between the two columns it might be confusing for both sighted and non-sighted users. | ||
| - When passing in displays keep in mind that only 8 can be used within a view at a time. Any additional displays passed in will be ignored. | ||
| - Displays are also split between two columns with every other display being moved to the right hand column. | ||
|
|
||
| ---- | ||
|
|
||
| ### Code Considerations | ||
|
|
||
| #### Clinical Item View Two Column Layout | ||
|
|
||
| Two column layout for the Clinical Item View has been updated to use true columns instead of rows formatted to look like columns. This affects not only the programmatic layout but also the screenreader's behavior in how these displays are read. | ||
| The implementation of this is accomplished behind the `trueColumn` prop which defaults to true. | ||
|
|
||
| The screenreader now reads through the first column, top to bottom, before moving on to the second column and reading its displays from top to bottom. | ||
| This way of handling readout is better, as it is more natural for us to organize and read information in columns by reading them one at a time, top to bottom before reading through the next column. | ||
|
|
||
| #### Clinical Item View Two Column Layout By Row | ||
|
|
||
| It is strongly recommended to utilize the true two column layout mentioned above, but if needed you can set the `trueColumn` prop to false which will revert to using the previous 'by row' logic. | ||
|
|
||
| Some potential reasons you might do this: | ||
| - When trueColumn is true, the spacing and truncation of elements are slightly different due to the fact that we are now splitting the displays into actual programmatic columns. | ||
| We can't resize on a row by row basis between the two columns since they are separate, so truncation may start a little earlier than it did before. | ||
| - When there is text wrapping/overflow for a display on one side - the 'by row' behavior adds blank newlines to the corresponding display in the opposite column. | ||
| Alternatively, when we use the trueColumn layout and there is a display on one side with overflow, no blank lines are added below the display in the opposite column. The next display is rendered directly under the previous one with no blank lines. | ||
|
|
||
| All of that being said, the screenreader readout for the 'by row' formatting announces the first display from the first column and then jumps over to the first display in the second column. | ||
| It then jumps back to the first column and reads out the next display before moving back over to the second column and reading the next display. This pattern of reading displays by row continues until the last display is read. | ||
|
|
||
| <Notice variant="important" ariaLevel="3"> | ||
|
|
||
| The primary reason this 'by row' formatting is not recommended is because visually when information is shown in a column it is natural to read all of the information in the first column and then the second. | ||
| Non-sighted users should also have the opportunity to take in information this way. | ||
|
|
||
| </Notice> | ||
|
|
||
| How these views are used, what kind of information is being communicated, and how far apart the columns are - all of these contribute to how understandable the information is to both non-sighted and sighted users. | ||
| **It is always best practice in general to keep closely related information in the same column.** | ||
|
|
||
| #### Clinical Item View Styling Override | ||
|
|
||
| Clincial Item View takes in Clinical Item Displays and by default the Item View has its own styling for these display elements. | ||
| However, the Item Displays have several different types of styling that can be applied to each individual display. Sometimes this styling conveys important information, like a display with a strikethrough. | ||
|
|
||
| To allow the usage of custom styling we have the `overrideDefaultStyling` prop. | ||
|
|
||
| This prop allows the user to override the Item View default styling and instead use the styling directly applied to the Item Displays. | ||
| If the override prop is set to true but the displays have no specific styling set, the displays will end up with the default Item Display styling. | ||
| More information on these styling types can be found on the Clincial Item Display [**page**](https://engineering.cerner.com/terra-clinical/components/terra-clinical-item-display/clinical-item-display/clinical-item-display). | ||
|
|
||
| #### Clinical Item View Truncation Handling | ||
|
|
||
| There is an `isTruncated` prop for Clinical Item View, when this is set to true all displays and comments in the Item View can be truncated. Otherwise, the content wraps to a newline when truncation is false. | ||
| The actual Item Displays themselves also have an `isTruncated` prop. If the Item View has truncation set to false but some of the Item Displays have it set to true, only those specific displays will be truncated. The rest will have the word wrap behavior. | ||
|
|
||
| <Notice variant="important" ariaLevel="3"> | ||
|
|
||
| ##### Truncated Text | ||
|
|
||
| Truncation of text can pose an accessibility concern if no method of disclosing the full text is availableto the user. | ||
| When using `isTruncated`, consumers are responsible for providing a progressive disclosure pattern to disclose the full Item Display text in order to ensure that it is accessible for keyboard navigation users. | ||
|
|
||
| **There should always be a method of accessing the truncated information. If there is no way to progressively disclose the full content of the truncated information, then truncation should not be used.** | ||
|
|
||
| Some examples of progressive disclosure patterns that may be used to disclose truncated information include: | ||
| - Accordions | ||
| - Dialogs | ||
| - Popovers | ||
| - Show/Hide | ||
| - Split Views | ||
| - Toasts | ||
|
|
||
| The method of disclosure **must** be accessible via keyboard interactions. | ||
|
|
||
| Truncation should be avoided where it is not necessary. Certain content should **never** be truncated (i.e. medication names and dosages in menus where the user is selecting from a list of choices). | ||
|
|
||
| </Notice> | ||
|
|
||
| ### Other Considerations | ||
|
|
||
| #### Clinical Item View Unordered List Structure | ||
|
|
||
| Displays in the Item View are rendered as list items inside a primary unordered list. | ||
| There is a hidden header tied to the list of displays for the purpose of using aria-labelledby on the unordered list, this header is populated from the first display passed in. | ||
| The structure is different for the different types of layouts - one column, two columns, and two columns by row. Their structure is as follows: | ||
|
|
||
| **For a one column layout with 8 displays** | ||
|
|
||
| Primary Unordered List | ||
| - List Item 1 | ||
| - Display 1 | ||
| - List Item 2 | ||
| - Display 2 | ||
| - List Item 3 | ||
| - Display 3 | ||
| - List Item 4 | ||
| - Display 4 | ||
| - List Item 5 | ||
| - Display 5 | ||
| - List Item 6 | ||
| - Display 6 | ||
| - List Item 7 | ||
| - Display 7 | ||
| - List Item 8 | ||
| - Display 8 | ||
|
|
||
| **For a true two column layout with 8 displays** | ||
|
|
||
| Primary Unordered List | ||
| - List Item 1 | ||
| - Column 1 as an unordered list | ||
| - List Item 1 | ||
| - Display 1 | ||
| - List Item 2 | ||
| - Display 3 | ||
| - List Item 3 | ||
| - Display 5 | ||
| - List Item 4 | ||
| - Display 7 | ||
| - List Item 2 | ||
| - Column 2 as an unordered list | ||
| - List Item 1 | ||
| - Display 2 | ||
| - List Item 2 | ||
| - Display 4 | ||
| - List Item 3 | ||
| - Display 6 | ||
| - List Item 4 | ||
| - Display 8 | ||
|
|
||
| **For a by row, two column layout with 8 displays** | ||
|
|
||
| Primary Unordered List | ||
| - List Item 1 | ||
| - Row 1 as an unordered list | ||
| - List Item 1 | ||
| - Display 1 | ||
| - List Item 2 | ||
| - Display 2 | ||
| - List Item 2 | ||
| - Row 2 as an unordered list | ||
| - List Item 1 | ||
| - Display 3 | ||
| - List Item 2 | ||
| - Display 4 | ||
| - List Item 3 | ||
| - Row 3 as an unordered list | ||
| - List Item 1 | ||
| - Display 5 | ||
| - List Item 2 | ||
| - Display 6 | ||
| - List Item 4 | ||
| - Row 4 as an unordered list | ||
| - List Item 1 | ||
| - Display 7 | ||
| - List Item 2 | ||
| - Display 8 | ||
|
|
||
|
|
||
| ## 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 | ||
|
|
||
| #### Success Criteria | ||
|
|
||
| - [**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)._ |