fluentv9-a11y-docs-structure.md

Fluent v9 Component accessibility docs structure

Fluent component a11y information is split across three sections, depending on relevance to the user:

1. Component Best Practices section on overview page
2. Component Accessibility section on overview page
3. Component Accessibility details page

The reason for splitting the information into different areas is to present the most concise and relevant information possible in each area of our docs. The component overview page should contain only information that authors need to know in order to implement an accessible version of our components (e.g. "provide a label), while the full accessibility details page provides a thorough description of all accessibility behaviors and choices made on the component.

Detailed breakdown of information

1. Best Practices

This section doesn't always need a11y-specific info; it should only be added when there is something all authors must do (e.g. provide a label to form components), or a major usage pitfall we want to call out (e.g. "don't use a treegrid for accordions").

Some examples of info that should go here:

• Provide a label for the [Component Name] component
• If there is a high chance of misuse, tell authors to not do that here

2. Accessibility section

The accessibility section on the component overview page should include all information that authors must know to correctly implement a component. This section should skew towards authoring advice, not description of the component. Info in the best practices can also be repeated here. This section should link to the full a11y spec page for more info.

At the end of the section should be a list of known external bugs related to the component.

Some non-comprehensive examples of info that should go here:

• If the control needs an author-provided label
• If the control has any internal screen-reader-only strings, it should be noted here that they need translations
• If the control has background contrast requirements, note them here (including appearance variant contrast reqs)
• Controls that use popover should note the option of rendering the popup inline, and the tradeoffs involved (see v8 combobox for an example)
• Usage guidance
• List of open bugs

3. Accessibility spec page

This page should include a full description of the semantics, keyboard behavior, HCM screenshots, etc. for the component, following the layout of the Spinbutton initial docs PR. It's OK to leave sections empty with a "Coming soon" note for now.