import { Badge } from 'terra-heading/package.json?dev-site-package';
import { Notice } from '@cerner/terra-docs';
import HeadingLevels from './example/HeadingLevels';
import HeadingExamples from './example/HeadingExamples';

<Badge />

# Accessibility Guide for Terra  Heading
> Accessibility of Headings is important because headers are used on virtually every page and in every product. Headings convey the page's visual structure and informational hierarchy and can also provide cues such as urgency, importance, or activity. However, headings must be coded correctly, for example, with proper heading levels, so that screen readers can convey the same structure of the page to people with limited or no vision.  

> Headings should accurately describe the content that follows them to ensure all users understand the proper context. It can be confusing if headings don't represent associated content or if heading levels do not match the appropriate level or are skipped or out of order. Any text that is visually styled to look like a heading must be understood programmatically, as a heading. 

## Accessibility Considerations 

### Code Considerations: What do engineers need to do?
- Headings must accurately describe the content they represent (content creators must provide the words used for the heading that describe its content and engineers must implement that within the code).

- Side note that Toggle Section Header provides teams with spaces to drop in other components or content. When consuming teams are adding interactive controls inside of Toggle Section Headers, Content creators must: 
    - Ensure the controls have labels that accurately describe the action they perform 
    - Ensure the objects have unique accessible names or add programmatic association to the Toggle Section Header heading.
    - If icons that convey information (meaningful icons) are used, ensure they have alternate content that reflect their purpose. And ensure the icon and alternate content used to describe it are consistent for other instances of the same icon when used for the same functionality.
    - If default theme colors are overridden, the consuming team must make sure colors meet proper contrast ratios for any meaningful text and non-text content.

### Code Considerations: What do engineers need to do?

- Headings must programmatically have a heading level that is set to match the structure of its placement on the page. Content creators should work with engineers to determine what heading level to use, and engineers must assign the proper heading level.

<div aria-label="Heading Demo">
  <HeadingExamples />
</div>

```jsx
<div>
    <Notice variant="important" ariaLevel="5">

      <Arrange
      align="center"
      fill={(
        <div className={cx('heading-wrapper')}>
          <Heading level={1}>
          Allergies Hospitals Locations
          </Heading>
        </div>
)}
    />
    <Arrange
      align="center"
      fill={(
        <div className={cx('heading-wrapper')}>
          <Heading level={2}>
            Kansas,MO
          </Heading>
        </div>
)}
    />
    <Arrange
      align="center"
      fill={(
        <div className={cx('heading-wrapper')}>
          <Heading level={3}>
            Riverport Campus, MO
          </Heading>
        </div>
)}
    />
    <Arrange
      align="center"
      fill={(
        <div className={cx('heading-wrapper')}>
          <Heading level={4}>
            Innovations Campus, MO
          </Heading>
        </div>
)}
    />
    <Arrange
      align="center"
      fill={(
        <div className={cx('heading-wrapper')}>
          <Heading level={5}>
            Realization Campus, MO
          </Heading>
        </div>
)}
    />
    <Arrange
      align="center"
      fill={(
        <div className={cx('heading-wrapper')}>
          <Heading level={6}>
            Kansas,MO
          </Heading>
        </div>
)}
    />
    </Notice>
  </div>
```

## Usability Expectations

### Interaction Detail
Terra Heading is not interactable.

### Keyboard Interactions
Terra Heading is not interactable.

## Concerns and Hazards

### Support Compliance

Terra is committed to ensuring its components provide maximum possible accessibility. Terra provides the ability to make accessible 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 Toggle Section Header

- [**1.3.1 Info and Relationships**](https://wiki.cerner.com/pages/viewpage.action?pageId=2016418858) - Supports
    - Engineers must ensure that appropriate heading level is applied to convey proper content structure of the Heading on the page. 
    - Content creators should provide engineering with heading level to match structure within the page.  


- [**2.4.6 Headings and Labels**](https://wiki.cerner.com/display/UserExperience/2.4.6+Headings+and+Labels) - Supports
    - Content creators must ensure headings and labels accurately describe the purpose of the content it represents.

### Related accessibility criteria that apply when adding content to Heading

- [**1.1.1 Non-text Content**](https://wiki.cerner.com/display/UserExperience/1.1.1+Non-text+Content) - Supports
    - Engineers must ensure appropriate alternate content is added graphics, icons, or images that convey meaning.  
    - Content creators must provide Engineers with alternate content that conveys meaning to the user. See also 3.2.4 Consistent Identification.

- [**1.4.1 Use of Color**](https://wiki.cerner.com/display/UserExperience/1.4.1+Use+of+Color) - Supports
    - Content creators must ensure that color, alone, is not used to convey information or meaning.

- [**1.4.3 Contrast (Minimum)**](https://wiki.cerner.com/display/UserExperience/1.4.3+Contrast) - Supports
    - Engineers must ensure any content used within Terra Heading meets the proper color contrast ratios for text.
    - Content creators must ensure any content used within Terra Heading meets the proper color contrast ratios for text.

- [**2.1.1 Keyboard**](https://wiki.cerner.com/display/UserExperience/2.1.1+Keyboard) - Supports
    - Engineers must ensure that all interactable elements can receive focus, be interacted with, and are able to be acted upon via keyboard only.

- [**2.1.2 Keyboard Trap**](https://wiki.cerner.com/display/UserExperience/2.1.1+Keyboard) - Supports
    - Engineers must ensure no keyboard traps are introduced into code.

- [**2.4.3 Focus Order**](https://wiki.cerner.com/display/UserExperience/2.4.3+Focus+Order) - Supports
    - Engineers must ensure the focus order is expected and preserves page meaning. Must also ensure not to implement a tab index value greater than zero.

- [**2.4.7 Focus Visible**](https://wiki.cerner.com/display/UserExperience/2.4.7+Focus+Visible) - Supports
    - Consuming teams must ensure visible focus is maintained on interactive elements used within the Terra Heading. 

- [**2.5.2 Pointer Cancellation**](https://wiki.cerner.com/display/UserExperience/2.5.2+Pointer+Cancellation) - Supports
    - Engineers must ensure that actions are activated by the mouse up event (not the down action), allowing the users to cancel interactions.

- [**2.5.3 Label in Name**](https://wiki.cerner.com/display/UserExperience/2.5.3+Label+in+Name) - Supports
    - Engineers must ensure the programmatic label matches the visual label when interactable elements are included with Heading. The visual label of an interactive object (e.g., button) must be the first word(s) of the accessible name of the object. Other programmatic association may be made by using an aria-describedby attribute.
    - Content creators should tell engineers what content should be used to create programmatic association for unique and descriptive accessible names of interactive objects.

- [**3.2.1 On Focus**](https://wiki.cerner.com/display/UserExperience/3.2.1+On+Focus) - Supports
    - Engineers must ensure no unexpected change of context happens when interactive elements receive focus.
    - Content creators must use standard and predictable design patterns.

- [**3.2.2 On Input**](https://wiki.cerner.com/display/UserExperience/3.2.2+On+Input)
    - Engineers must ensure that nothing unexpected happens when interactive elements receive input.

- [**3.2.4 Consistent Identification**](https://wiki.cerner.com/display/UserExperience/3.2.4+Consistent+Identification)
    - Content creators must ensure any icons used are used to consistently represent the same function. Additionally, the alternate content used to represent icons must be consistent for users to predictably understand it’s function.

- [**4.1.1 Parsing**](https://wiki.cerner.com/display/UserExperience/4.1.1+Parsing) - Does Not Supports
    - Engineers must ensure that clean, fundamentally sound code is implemented, including elements with complete start and end tags, elements nested according to specifications, elements that do not contain duplicate attributes, and so on.

- [**4.1.2 Name, Role, Value**](https://wiki.cerner.com/display/UserExperience/4.1.2+Name%2C+Role%2C+Value) - Supports
    - Content creators and engineers must ensure that any content inside Heading meets this criterion.

### 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:
- [W3C WAI Aria: Use heading to convey meaning and structure](https://www.w3.org/WAI/tips/writing/#use-headings-to-convey-meaning-and-structure)