import { Badge } from 'terra-arrange/package.json?dev-site-package';

<Badge />

# Accessibility Guide for Terra Arrange

## Why is it important for Terra Arrange to meet accessibility guidelines ?

> Terra Arrange is a component used for setting the content layout alignment to be top/bottom/right/left. CSS alignment does not affect the accessibility, however it is crucial to ensure that the screen reader reads the content in the same manner as to how the content is visually present. If the content is aligned with any position property to make it look in different place which will create a complexity for the screen reader user to get the correct reading order.   
>
> Making the DOM order same as visual order will help the assistive technology users to get the correct reading order. 
>
> Arrange may also have interactive elements which need to be keyboard focusable and acted upon using the standard expected keyboard behaviors. 
>
>&nbsp;&nbsp;
- **Screen reader users** do not necessarily interact with the page in a linear fashion and can use Arrange out of context. Hence, a descriptive label is necessary for each interactive element.
- **People using speech input software** require unique labels for the interactive elements to effectively understand them.  
- **Keyboard only users** navigate the page using only a keyboard. Actionable elements must be keyboard accessible for keyboard only users to interact with it. Additionally, a visible keyboard focus indicator is needed to see where they are currently on the page.  


## Accessibility Considerations:

### Code Considerations: What do engineers need to do?
- Ensure the content in the arrange component is reading in logical manner in assistive technology. The DOM structure needs to be in the form the UI order. 
- Ensure the interactive elements are receiving TAB focus and user able to interact with it. 
- Ensure the content is available in 200% text only zoom. Except for captions and images of text, text can be resized without assistive technology up to 200 percent without loss of content or functionality. 
- Ensure the content can be presented without loss of information or functionality, and without requiring scrolling in two dimensions for: Vertical scrolling content at a width equivalent to 320 CSS pixels; Horizontal scrolling content at a height when window is resized to 400%.
- Ensure Terra Arrange is not used to create and arrange tabular data that has relationships to columns and rows. Instead, use Terra Table or Terra HTML Table.

### Content Considerations: What do content creators need to do? 
- Terra Arrange must not be used to create and arrange tabular data that has relationships to columns and rows. That is to say do not use 
   Terra arrange to create visible tables. Instead, use Terra Table or Terra HTML Table. 
- Ensure all interactive elements have descriptive labels that describe their purpose. 
  - For each interactive element within Arrange, provide the engineers with a meaningful label. 
  - Ensure each interactive element label is unique to the page. 
    - If multiple elements with the same name are used, they must perform the same exact function (e.g., download the same file). 
    - Or it must be programmatically associated with other visible and related content on the page that can help users understand the purpose of elements. 
  - If the label is text, the visible text must match the programmatic label. 
  - All icons used within interactive elements that convey meaning must have an accessible name (alternate content). 
    - The icon must be intuitive for the functionality it represents. 
    - The icon must be named consistently across the product. 
    - Icons must be used to represent the same function consistently (don’t use multiple icons for the same functionality) 
  - Any purely decorative icon (does NOT convey any meaning) within a button must be marked as decorative. 
- Consider how content will adjust to resizing text or reflowing content at different viewpoints. Users may have settings that change the font size, style, or other text attributes. They may also resize a window or zoom into the content. All these things can cause content to resize or reflow, and when it does, content must not overlap, be cut off, or become unusable. 
- Ensure all content is perceivable by meeting all the color contrast requirements. 
- After development, ensure all actionable elements inside of Arrange is keyboard accessible and work as expected. 
  - Ensure actionable elements inside Arrange has a visible keyboard focus when accessed using the keyboard. 
  - Ensure the Arrange does not cause a keyboard trap. 

## Usability Expectations:

### Interaction Details
- Terra Arrange has no interactions in and of itself. However, it may contain actionable elements. All actionable elements within Terra Arrange must be able to be focused via keyboard and follow the expected keyboard behavior per actionable element, and proper labeling should be announced in the screen reader.  

### Usability Expectations:
- The user expects the button would be performing an action indicated in the button label. 


### Keyboard Expectations
- Terra Arrange has no expected keyboard behaviors itself. However, the content within it will follow the basic keyboard behaviors. 

| Key Sequence | Expectation |
|---|---|
|*Tab*| Moves focus to the interactive element  |
|*Arrow keys*| Read the content in logical manner   |
|*Enter/Return/Spacebar*| Executes the button and moves focus to the target place.   |


## Support Compliance:

### How does Arrange support compliance? 
> Terra is committed to ensuring its components provide maximum possible accessibility. Terra provides the ability to make accessibility products. However, using Terra components will not automatically make a product accessible. 
>
> Final responsibility lies with the consumers of Terra components — ensuring proper usage, programmatic context where needed, the words used to label elements, engineers following correct implementation patterns, and authors crafting content that follows best practice guidance — to make a product fully accessible. 

### Primary accessibility criteria for Arrange  
- [1.1.1 Non-text Content](https://wiki.cerner.com/display/UserExperience/1.1.1+Non-text+Content) — Supports
  - Terra provides the ability to use icons inside a button. 
  - Engineers must ensure when an icon conveys meaning, to add appropriate ALT text to create a meaningful button label. 
  - Content creators must provide engineers with meaningful text when using icons that convey meaning. 

- [1.3.1 Info and Relationships](https://wiki.cerner.com/display/UserExperience/1.3.1+Info+and+Relationships) — Supports 
  - Terra provides the ability for information, structure, and relationships to be programmatically determined. 
  - Engineers must ensure the heading hierarchy is followed from h1 to h6 order to give the meaningful order to assistive technology users. 

- [1.4.3 Contrast (Minimum)](https://wiki.cerner.com/display/UserExperience/1.4.3+Contrast) — Supports
  - Terra Arrange provides icons/buttons by default, meet color contrast requirements.  
  - Engineers must work with content creators to implement icons so that the foreground and the background color meet appropriate color contrast ratios.   
  - Content creators must ensure that the button label color meets the appropriate contrast ratio against background color(s) based on text size of the visual label text. Contrast ratios should be above 4.5:1 for normal text and 3:1 for bold and large text.  

- [1.4.4 Resize text](https://wiki.cerner.com/display/UserExperience/1.4.4+Resize+Text) — Supports
  - Terra provides the ability for text to be resized and zoomed without loss of information or function.  
  - Engineers must ensure content other than captions and images of text can be up to 200 percent without loss of content or functionality.  

- [1.4.10 Reflow](https://wiki.cerner.com/display/UserExperience/1.4.10+Reflow) — Supports
  - Terra provides the ability for components to reflow when the viewport is resized to 320x256 px without loss of information or function. 
  - Engineers must ensure content within the Terra component can reflow when the viewport is resized to 320 x 256 px without scrolling in two directions or loss of information or functionality. 
  - Content creators must consider the responsive nature of Terra component and provide engineers guidance on how content should reflow when the viewport is resized to 320 x 256 px 

- [2.1.1 Keyboard](https://wiki.cerner.com/display/UserExperience/2.1.1+Keyboard) — Supports
  - Terra ensures Terra Arrange supports basic keyboard functionality.  
  - Engineers must ensure Arrange is keyboard accessible and not override any basic keyboard functionality and follow the tab index values such as tabindex=0  
  - Ensure all contents can be accessed, interacted with and acted upon using only the keyboard.   

- [2.1.2 No Keyboard Trap](https://wiki.cerner.com/display/UserExperience/2.1.2+No+Keyboard+Trap) — Supports
  - Terra Arrange will not cause a keyboard trap on its own.  
  - Engineer and Content Creators must ensure Arrange does not cause a keyboard trap when implemented within code.  

- [2.4.3 Focus Order](https://wiki.cerner.com/display/UserExperience/2.4.3+Focus+Order) — Supports
  - Terra provides consuming teams the ability to create a logical focus for the user.  
  - Engineers must never set a TABINDEX of greater than zero. Code should be written to match the users logical reading order.  
  - Content creators ensure that engineers understand the users logical reading order.  

- [2.4.7 Focus Visible](https://wiki.cerner.com/display/UserExperience/2.4.7+Focus+Visible) — Supports
  - Terra ensures a visible keyboard focus is built into the component.  
  - Engineers and Content Creators must ensure the visible indication must be maintained for buttons/icons and must meet the sufficient color contrast ratio.  
  - Content creators must inform engineers that whenever buttons/icons receive focus, the focus must be visible and maintain existing Terra Keyboard Focus styles.   

- [4.1.1 Parsing](https://wiki.cerner.com/display/UserExperience/4.1.1+Parsing) — Supports 
  - Terra components are tested and validated before release to ensure proper parsing of code.  
  - Engineers must ensure this criterion is met.  
  - Content creators must inform engineers about the proper parsing of code.  

- [4.1.2 Name, Role, Value](https://wiki.cerner.com/display/UserExperience/4.1.2+Name%2C+Role%2C+Value) — Supports 
  - Terra provides the ability for Name, Role, and Value attributes to be programmatically determined for screen readers to effectively communicate to the user.   
  - Engineers must ensure the programmatic label matches the visible label.   
  
### Related accessibility criteria that apply when adding content to Arrange 
- [3.2.1 On Focus](https://wiki.cerner.com/display/UserExperience/3.2.1+On+Focus) — Supports 
  - Terra components do not cause a change of context on focus by default.  
  - Engineers must ensure that no unexpected change of context happens when interactive elements receive focus or when focus is removed (on blur).  
  - Content creators must inform engineers that it should not cause any change while on focus.   

- [3.2.2 On Input](https://wiki.cerner.com/display/UserExperience/3.2.2+On+Input) — Supports 
  - Terra Arrange does not cause an unexpected change of context on input. 
  - Engineers must ensure nothing unexpected happens on input.  
  - Content creators must also ensure buttons/icons do not create a change of context for the user. If there is a change of context on input, the user must be warned (with text) before the user activates the button.   

### Supported Features and Technology  
- Keyboard Interactions 
- JAWS Support with Chrome (PC) 
- VoiceOver Support with Chrome, Safari (MAC) 

### Partial Support & Requiring Further Enhancement  
- NVDA not tested (PC) 
- Mobile Touch Interactions with Screen Reader assistive technology 
- Speech Input Interactions with assistive technology 
- [Report a problem with this component on GitHub](https://github.com/cerner/terra-core/issues/new/choose) 

## Linked References:

1. [W3C WAI Aria: Use heading to convey meaning and structure  ](https://www.w3.org/WAI/tips/writing/#use-headings-to-convey-meaning-and-structure)
2. [Web Content Accessibility Guidelines](https://www.w3.org/TR/WCAG21/#:~:text=%20Web%20Content%20Accessibility%20Guidelines%20%28WCAG%29%202.1%20defines,physical%2C%20speech%2C%20cognitive%2C%20language%2C%20learning%2C%20and%20neurological%20disabilities)