Skip to content

chore: a11y docs structure update #24871

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
smhigley merged 2 commits into from
Sep 21, 2022
Merged

chore: a11y docs structure update #24871

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9eb09ea
chore: move spinbutton a11y spec to Concepts/Developer/Accessibility
smhigley Sep 20, 2022
3215b65
change files
smhigley Sep 20, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions change/@fluentui-react-components-2746a815-4cae-4351-a6fe-ad932145c33b.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
{
"type": "none",
"comment": "chore: move spinbutton a11y spec to Concepts/Developer/Accessibility",
"packageName": "@fluentui/react-components",
"email": "[email protected]",
"dependentChangeType": "none"
}
7 changes: 7 additions & 0 deletions change/@fluentui-react-spinbutton-49e629e4-b86e-4b48-8b72-25cd7f0b719a.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
{
"type": "none",
"comment": "chore: move spinbutton a11y spec to Concepts/Developer/Accessibility",
"packageName": "@fluentui/react-spinbutton",
"email": "[email protected]",
"dependentChangeType": "none"
}
2 changes: 1 addition & 1 deletion packages/react-components/react-components/.storybook/preview.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ export const parameters = {
[
'Introduction',
'Developer',
['Quick Start', 'Styling Components', 'Positioning Components'],
['Quick Start', 'Styling Components', 'Positioning Components', 'Accessibility', ['*', 'Components']],
'Upgrading',
[
'from v8',
Expand Down
2 changes: 1 addition & 1 deletion ...ts/react-components/src/Concepts/Accessibility/AccessibleComponents.stories.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
import { Meta } from '@storybook/addon-docs';
import { ScenariosListLink } from '../../AccessibilityScenarios/utils';

<Meta title="Concepts/Developer/Accessibility/Components" />
<Meta title="Concepts/Developer/Accessibility/Components Overview" />

## Components accessibility

Expand Down
68 changes: 36 additions & 32 deletions ...ies/SpinButton/SpinButtonAccessibility.md → ...utton/SpinButtonAccessibility.stories.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,38 +1,47 @@
import { Meta } from '@storybook/addon-docs';

<Meta title="Concepts/Developer/Accessibility/Components/SpinButton" />

# SpinButton Accessibility Spec

## Component features and behavior

This section documents accessibility-related behavoirs of spin buttons.
This section documents accessibility-related behaviors 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 |
| 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 |

| 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

Expand All @@ -56,15 +65,15 @@ Mouse press quick changes to value are not announced to screen readers.
[Narrator defaults to reading min/max as 0 when they're (intentionally) undefined](https://microsoft.visualstudio.com/Edge/_workitems/edit/39070743)

### Narrator + Edge

When no min or max values are set Narrator announces "minimum 0" and "maximum 0". This is misleading because when these values are not set SpinButton does not enforce a min or max value.

### NVDA + Edge/Chrome

When focused on the SpinButton input field pressing up/down arrows announces "blank". NVDA + Firefox announces the correct value.

## Usage



### When to choose Spin button

SpinButtons allow someone to incrementally adjust a value in small steps.
Expand All @@ -76,6 +85,7 @@ SpinButtons are a better choice than Slider when there are many valid values and
### Required props

Authors must provide a label for SpinButton. The recommended pattern for Fluent inputs is to use the Label component like this:

```
<Label htmlFor="example-spinbutton">A SpinButton</Label>
<SpinButton id="example-spinbutton" defaultValue={10} />
Expand All @@ -93,26 +103,20 @@ How this is read also depends on the screen reader used but a screen reader shou

### Styling
Copy link
Member

@micahgodbolt micahgodbolt Sep 20, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

is this just a stub for later? should we ommit empty areas for now.

Copy link
Contributor Author

@smhigley smhigley Sep 20, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yup, though that wasn’t added in this PR. For now I’m just moving the files and updating the docs nav structure, and sometime this week I plan to fill in these sections 😄




### 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
* Increment icon
* Down button
* Decrement icon

- Input field
- Up button
- Increment icon
- Down button
- Decrement icon

#### Component-specific usage warnings



## Extending [component name]


3 changes: 1 addition & 2 deletions packages/react-components/react-spinbutton/src/stories/SpinButton/index.stories.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,6 @@
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';

Expand All @@ -21,7 +20,7 @@ const meta: Meta = {
parameters: {
docs: {
description: {
component: [descriptionMd, bestPracticesMd, accessibilityMd].join('\n'),
Copy link
Member

@micahgodbolt micahgodbolt Sep 20, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How about linking from the SpinButton to the a11y docs

Copy link
Contributor Author

@smhigley smhigley Sep 20, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yup, it’s in the plan! I’m going to be adding an a11y authoring section next to best practices that will link to the full descriptive spec

component: [descriptionMd, bestPracticesMd].join('\n'),
},
},
},
Expand Down