Initial spin-button a11y commit

change/@fluentui-react-spinbutton-803b9a0b-82dd-471f-b57d-7717eb0d925d.json

@@ -0,0 +1,7 @@
+{
+  "type": "none",
+  "comment": "Merge branch 'master' of https://github.com/microsoft/fluentui into spin-button",
+  "packageName": "@fluentui/react-spinbutton",
+  "email": "jennz@microsoft.com",
+  "dependentChangeType": "none"
+}

packages/react-components/react-spinbutton/src/stories/SpinButton/SpinButtonAccessibility.md

@@ -0,0 +1,100 @@
+## Component features and behavior
+
+This section documents accessibility-related behavoirs of spin buttons.
+
+### Keyboarding
+
+#### Tab Order
+1. Value field
+
+#### States
+1. Rest (Focused)
+2. Editing (Focused and editing)
+
+#### Keyboard State Diagram
+
+| Starting state | Transition | Resulting state |
+| ---------- | ------------ | ------- |
+| Content before spin button | Tab | Rest |
+| Rest  | Tab | Content after spin button |
+| Editing  | Tab | Content after spin button (Value committed) |
+| Editing  | Enter | Rest (Value committed)|
+| Rest  | Any Edit Key (that results in a change) | Editing |
+| Editing  | Any Edit Key | Editing |
+| Content after spin button (Value committed) | Shift + Tab | Rest |
+
+##### Edit keys
+| Edit Key | Result |
+| ---------- | ------------ |
+| Home | First item in defined range |
+| End | Last item in defined range |
+| Up arrow | Increments value higher, based on the step prop (defaulting to 1) |
+| Down arrow | Increments value lower, based on the step prop (defaulting to 1) |
+| Page up | Increments value higher, based on the stepPage prop (defaulting to 1) |
+| Page down | Increments value lower, based on the stepPage prop (defaulting to 1) |
+| Typing valid value | Valid value |
+
+### High contrast mode
+
+Be careful about visibility of the spin button arrows in high contrast mode.
+TODO: Either add specifics about SVGs in high contrast and how to customize the icon color without messing up HCM or (ideally) link to the Icon section on high contrast, when it exists.
+
+### Motion and animation
+
+There is an animation when this element receives focus. This respects reduced-motion media queries.
+
+When a user holds down an edit key or mouse click, there is an animation of spinning numbers to provide a sense of how fast the value is changing. This animation is an interaction cue and therefore is acceptable even when a user has set a preference for reduced motion.
+
+### Semantics
+
+## Known issues
+
+Placeholder: If there are any current known bugs with browsers or AT that impact this component, list them here.
+
+Mouse press quick changes to value are not announced to screen readers.
+
+## Usage
+
+
+
+### When to choose Spin button
+
+SpinButtons allow someone to incrementally adjust a value in small steps.
+
+SpinButtons are a better choice than Input and Input with type: number when clear indication is needed that there are maximum and minimum allowed values.
+
+SpinButtons are a better choice than Slider when there are many valid values and Slider would not provide enough granularity to choose a precise value.
+
+### Required props
+
+Placeholder: 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.
+
+Open question: How does everything read? Name, role, value? What about when there are prefixes or postfixes?
+
+### Styling
+
+
+
+### Advanced usage
+
+Placeholder: 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)
+
+#### Child content restrictions
+
+The component has the following structure:
+* Input field
+* Up button
+  * Up carat symbol
+* Down button
+  * Down carat symbol
+
+
+#### Component-specific usage warnings
+
+[NVDA does not read the value of spinbuttons in Chromium](https://github.com/nvaccess/nvda/issues/13195)
+
+[Narrator defaults to reading min/max as 0 when they're (intentionally) undefined](https://microsoft.visualstudio.com/Edge/_workitems/edit/39070743)
+
+## Extending [component name]
+
+

packages/react-components/react-spinbutton/src/stories/SpinButton/index.stories.tsx

@@ -1,6 +1,7 @@
 import { Meta } from '@storybook/react';
 import { SpinButton } from '@fluentui/react-components';
 
+import accessibilityMd from './SpinButtonAccessibility.md';
 import descriptionMd from './SpinButtonDescription.md';
 import bestPracticesMd from './SpinButtonBestPractices.md';
 
@@ -20,7 +21,7 @@ const meta: Meta = {
   parameters: {
     docs: {
       description: {
-        component: [descriptionMd, bestPracticesMd].join('\n'),
+        component: [descriptionMd, bestPracticesMd, accessibilityMd].join('\n'),
       },
     },
   },