# Accessibility convergence

## Comparison v0/v7
### Current react-northstar (v0) process
0) Follow ARIA as much as possible, always preserve DOM order, file bugs to other parties early
2) Identify [ARIA](https://www.w3.org/TR/wai-aria-practices-1.2/) pattern or other best practices to follow
3) Create prototype and test internally with all supported screen reader/browser combinations + forms and virtual cursor mode
4) Test prototype (HCL)
5) Implement component including behaviors, add behavior description and unit tests
6) Validate component (internal testing + HCL)
7) Document best practices
8) Create [validation rules](https://github.com/microsoft/ability-attributes) for component

[Accessibility guide](https://fluentsite.z22.web.core.windows.net/accessibility)
[Accessibility behaviors](https://fluentsite.z22.web.core.windows.net/accessibility-behaviors)
[Accessibility spec in fluent-ui-react](https://github.com/microsoft/fluent-ui-react/pull/2237/files)

### Current react (v7) process
1. dev primarily follows ARIA spec
2. while dev'ing, testing is done manually with supported browser+screenreader combination and Accessibility Insights for Web
3. dev will work with designer when it's not straightforward to say what the expected user experience should be.

### Converged process proposal
1) Include accessibility in Fluent UI **component spec**
2) Create **prototype or base functionality** of the component
3) **Internal test** when component functionality is available (all supported screen reader/browser combinations)
4) **Incorporate test results** in the component implementation
5) Document **best practices**
6) Document **known issues**, including links if they are tracked by browsers or screen readers
7) Create **[validation rules](https://github.com/microsoft/ability-attributes)** for component - help to identify accessibility issues early in the development phase (or even design with UI Builder)
8) Schedule an **HCL test**
9) **Resolve issues** found in the trusted user test

## Component Specification

When writting a component specification follow these steps to achieve an accessible user experience:
* Decide whether to use **native element** or folow **ARIA** and provide reasons
* Identify the **[ARIA](https://www.w3.org/TR/wai-aria-practices-1.2/) pattern** and, if the component is listed there, follow its specification as possible.
* Identify accessibility **variants**, the `role` of the component, its `slots` and `aria-*` props.
* Describe the **keyboard navigation**: Tab Oder and Arrow Key Navigation. Describe any other keyboard **shortcuts** used
* Specify texts for **state change announcements** - [ARIA live regions
](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions) (number of available items in dropdown, error messages, confirmations, ...)
* Identify UI parts that appear on **hover or focus** and specify keyboard and screen reader interaction with them
* List cases when **focus** needs to be **trapped** in sections of the UI (for dialogs and popups or for hierarchical navigation)
* List cases when **focus** needs to be **moved programatically** (if parts of the UI are appearing/disappearing or other cases)

[Components specs](https://github.com/microsoft/fluentui/tree/master/specs)

## Focusing
Focus management is a complex topic involving tabbing, arrow key (and other keys) navigation, focus trap for popups and dialogs, focus restoration, focus indicator and others.
Proposal: use [Ability helpers](https://github.com/microsoft/ability-helpers) for focus management

## External and internal documentation
1) [Docs] Best practices - should include all information that the consumer needs to properly use the component in an accessible way. Good examples are prop restrictions or suggestions.
2) [Docs] Track accessibility issues in the component documentation page
* [Currently reported screen readers bugs](https://teams.microsoft.com/l/entity/com.microsoft.teamspace.tab.wiki/tab::9804ef92-c0fd-4dd9-b2ce-81e7e0671be5?context=%7B%22subEntityId%22%3A%22%7B%5C%22pageId%5C%22%3A43%2C%5C%22origin%5C%22%3A2%7D%22%2C%22channelId%22%3A%2219%3Askypespaces_376bcd04502141c483d3be51a3a5aad2%40thread.skype%22%7D&tenantId=72f988bf-86f1-41af-91ab-2d7cd011db47)
* [Where to log external accessibility bugs](https://teams.microsoft.com/l/entity/com.microsoft.teamspace.tab.wiki/tab::9804ef92-c0fd-4dd9-b2ce-81e7e0671be5?context=%7B%22subEntityId%22%3A%22%7B%5C%22pageId%5C%22%3A22%2C%5C%22sectionId%5C%22%3A31%2C%5C%22origin%5C%22%3A2%7D%22%2C%22channelId%22%3A%2219%3Askypespaces_376bcd04502141c483d3be51a3a5aad2%40thread.skype%22%7D&tenantId=72f988bf-86f1-41af-91ab-2d7cd011db47)
3) [Internal - component spec?] Document accessibility decisions, especially cases when we diverged from ARIA

## Tools and testing

1) **[axe-core](https://www.deque.com/axe/)** needs to be part of unit tests for each component. Consider using it in e2e test to check contrast of themes as well.

2) **Schema validation** helps to enforce common accessibility [Schema](https://github.com/microsoft/fluent-ui-react/blob/master/packages/ability-attributes/schema.json) - rules that can be valid globally or specifically for a product. It validates DOM in runtime (dev and test builds, UI Builder) and provides immediate feedback to the developer for most common accessibility problems:
- focusable elements without label
- violations in parent/child widget/role restrictions
- missing or invalid ARIA attributes
- violations of atomicity
- others

For example, the following `Button Schema` it would throw an error if you try to render a button without content or title:

    <Button />


Or if missing the role attribute:


Schema validation is part of [Ability attributes](https://github.com/microsoft/ability-attributes)

3) **[Accessibility Insights](https://accessibilityinsights.io/)** for fast general accesibility check.

4) Consider using [Accessibility object model (AOM)](https://wicg.github.io/aom/) in e2e tests

## Behaviors
React-northstar has externalized accessibility logic in behaviors. Each component has a default behavior, which can be overriden (or extended)

**Pros**:
- compact code describing keyboard navigation, ARIA attributes and keyboard handlers in a consistent way, similar to ARIA patterns
- tests and documentation are enforced
- consumers have flexibility in providing their own behaviors

**Cons**:
- without type safety (and enforcement of slot existence) behaviors are interchangable, which might lead to confusing experience
- tests and documentation is cumbersome
- unit-ests only - are not used to validate rendered DOM

**Proposal**:
- continue using behaviors but do not expose them through a generic props API
- instead, use specific props (requires an analysis of when the behaviors needed to be overriden in Teams)
- use standardized way of testing and documenting accessibility: https://github.com/microsoft/fluentui/pull/16711
- consider generating behaviors from schema

## Component labeling

**Usage of aria-label, aria-labelledby or aria-describedby**
User needs to label the component in order to provides context for screen reader users.
The label can be set with `aria-label` or `aria-labeledby`.
A visible label should be referenced by the value of `aria-labelledby` (id of element containing the label).
Otherwise user uses the `aria-label`.

If there's additional static text representing that is descriptive, `aria-describedby` should be set to id of element containing the description.

## Open questions
`aria-label` vs `ariaLabel` in props - React says `aria-`: https://reactjs.org/docs/dom-elements.html - **agreed to use dashed properties**