This section documents out-of-the box accessibility-related behavoirs of the component.
Link to the APG for standard keyboard patterns for this component pattern. Document any additions or non-standard interactions.
| Key | State | Behavior |
|---|---|---|
| Alt + Down | Collapsed | Opens dropdown |
| ...etc. |
Add screenshots and notes about specific system color keywords when they are specifically defined (i.e. not just default browser styles).
Include this section for components that have animations or transitions that involve motion (e.g. in-place color fades don't count, but the spinner would, as would the tab indicator transition). Mention what the animated motion is, and that it is turned off by the reduced-motion media query.
If the component has no motion-based animation, remove this section.
Link to the ARIA spec and APG for any component that matches a specific existing pattern.
Note down any Fluent-specific semantic choices, or for parts of the control that are not covered in the basic ARIA pattern. An example of this would be the overflow button for Tabs, or the selected option tags for Combobox.
If there are any current known bugs with browsers or AT that impact this component, list them here.
This section contains guidance for authors to use the component in accessible manner.
A brief description of the use cases when this particular component would be appropriate, and when it wouldn't. Reference other component patterns (whether or not they are provided by Fluent) that are similar, but have slightly different use cases.
If there are any props or other specific work that the author must do to make the default usage of the component accessible, list those here. One example is that all form components must have a label provided by the author. If the component has any internally defined strings that should be localized, list those here.
Any notes about styling or color usage here. E.g. filled-darker and filled-lighter variants of inputs must be used on a background with adequate contrast. Also note which parts of the control must meet contrast against which other parts.
Cover potential use cases not included in our storybook examples here (or even included storybook examples, if they're complex require a notable amout of work or nuanced understanding from authors)
If the component accepts child content or slot content with any sort of restrictions, list those here. E.g.: Button and Link only accept non-interactive and unstructured content. Similarly with Tooltip, MenuItem, etc.
If there are any other accessibility pitfalls specific to this component, add more sections under "Advanced Usage" for those.
Go over accessibility considerations with recomposing or extending the component.
This section is a stretch goal, and should probably come after we have better docs on recomposing in general, and after the rest of the a11y documentation is complete for all components.
This hits on the main points in Accessibility Control Specifications so I'm board with this overall, looks really good!
Consider component hierarchy trees, and keyboard state tables with transitions. One piece of feedback that has come up about APG is that the text-based list isn't very clear about when certain keys are valid. For combobox, for example, does type ahead work when it's collapsed? It is included, though the format is difficult to decipher. We could speak to APG about that to see if we can influence them to do this.
State, transition, end state? For your example, this would be Collapsed, Alt + Down, Expanded