[a11y] Autocomplete and text field a11y docs #968

dpersing · 2019-02-04T21:35:14Z

Adds accessibility documentation for the (related) text field and autocomplete components.

WHY are these changes introduced?

Provides guidance on using the text field and autocomplete components as part of accessibility documentation updates. These update are available in component docs on polaris-react and the style guide site.

See the draft Google doc for editing history for these changes and updates for other components and pages.

WHAT is this pull request doing?

Adds guidance on using the text field for web, iOS, and Android
Adds guidance on using the autocomplete for web (not available on other platforms)
Adds an entry to UNRELEASED.md

How to 🎩

Check out master from polaris-styleguide to get the changes that support the accessibility section.
In another Terminal tab or window, check out this branch from polaris-react and run the instructions for testing in a consuming project.
In the polaris-styleguide tab, run dev up && dev start.
View changes after examples and props:

https://polaris.myshopify.io/components/forms/text-field (web, iOS, and Android)
https://polaris.myshopify.io/components/forms/autocomplete (web only)

Screenshots

Autocomplete

Text field (web)

sadiesaurus

Yes! Content is looking good. Made some comments, asked some questions 🙂

sadiesaurus · 2019-02-05T22:16:13Z

src/components/Autocomplete/README.md

+
+The autocomplete component is based on the [ARIA 1.1 combobox pattern](https://www.w3.org/TR/wai-aria-practices-1.1/#combobox). See the [text field component](https://polaris.shopify.com/components/forms/text-field) for information on implementing the autocomplete component with a text field.
+
+We recommend implementing the autocomplete list below the text input so that it’s easy to discover and use. However, you can change the position with the `preferredPosition` prop.


A couple of questions:

Does line 435 refer to implementing autocomplete with a text field? Or is it relevant to autocomplete on the whole?

If you don't change the position with the preferredPosition prop, then does the autocomplete list show below the text input by default?

I believe we only support using the autocomplete with a text field but there are similar features in admin that are used with buttons. I'll clarify that it's below the control by default.

src/components/Autocomplete/README.md

sadiesaurus · 2019-02-05T22:47:05Z

src/components/TextField/README.md

+
+- Use the `disabled` prop to add the HTML `disabled` attribute to the text field
+- Use the `readOnly` prop to add the HTML `readonly` attribute to the text field
+- If you use the `type` prop, then some technologies update the software keyboard provided to the user to be more specific to the task at hand. This helps merchants with mobility, vision, and cognitive issues to enter information more easily


Because '"provided to the user" might be implied, and "task at hand" is idiomatic and might be difficult for ESL readers or translations, maybe we can rephrase to something like:

If you use the `type` prop, then some technologies update the software keyboard to be more specific to the current task.

or even

If you use the `type` prop, then some assistive technologies adapt the software keyboard to the current task.

Since one of the bullets here has two sentences, we can add periods to all of the bullets in the list

src/components/Autocomplete/README.md

src/components/TextField/README.md

sadiesaurus · 2019-02-06T01:41:14Z

src/components/TextField/README.md

+
+#### Automatically focusing
+
+In general, avoid focusing on fields automatically. However, you can use the `autoFocus` prop to automatically move focus to the text field. This prop is set to `false` by default and should only be used in cases where it won’t force focus to skip other controls or content of equal or great importance importance.


I think the paragraph flows a little better if we rephrase so that the first sentence is at the end:

Use the `autoFocus` prop to automatically move focus to the text field. This prop is set to `false` by default and should only be used in cases where it won’t force focus to skip other controls or content of equal or greater importance. In general, avoid focusing on fields automatically.

That said, if it's important to make sure that folks don't miss the message about it being best to not automatically focus, then maybe we can say something like:

Although you can use the `autoFocus` prop to automatically move focus to the text field, it’s generally best to avoid focusing on fields automatically. The `autoFocus` prop is set to `false` by default and should only be used in cases where it won’t force focus to skip other controls or content of equal or greater importance.

src/components/TextField/README.md

Co-Authored-By: dpersing <devon.persing@shopify.com>

dpersing · 2019-02-06T17:49:43Z

@sadiesaurus Updated/added all your recs!

kaelig

Looks great, aside from the UNRELEASED.md that contains unrelated entries.

* Add a11y content to text field component * Add a11y content for the autocomplete page * Added entry to UNRELEASED.md

Devon Persing added 7 commits January 30, 2019 13:58

Add a11y content to text field component

39a88c8

Add a11y content for the autocomplete page

b2a47a5

Fixing typos

6e7efaa

Rewrote auto-focusing section

c8afbe5

Cleaning up lists

c243dff

Troubleshooting content display

79df589

Tidied lists

63fbb52

BPScott temporarily deployed to polaris-react-pr-968 February 4, 2019 21:35 Inactive

Added entry to UNRELEASED.md

8072a29

BPScott temporarily deployed to polaris-react-pr-968 February 4, 2019 21:36 Inactive

dpersing requested review from danrosenthal and sadiesaurus February 4, 2019 21:38

dpersing changed the title ~~[a11y] Autocomplete text field a11y docs~~ [a11y] Autocomplete and text field a11y docs Feb 4, 2019

sadiesaurus reviewed Feb 6, 2019

View reviewed changes

src/components/TextField/README.md Outdated Show resolved Hide resolved

Update src/components/Autocomplete/README.md

7a89bd1

Co-Authored-By: dpersing <devon.persing@shopify.com>

BPScott temporarily deployed to polaris-react-pr-968 February 6, 2019 17:22 Inactive

sadieredden and others added 2 commits February 6, 2019 09:22

Update src/components/Autocomplete/README.md

9295ff6

Co-Authored-By: dpersing <devon.persing@shopify.com>

Update src/components/TextField/README.md

866bc47

Co-Authored-By: dpersing <devon.persing@shopify.com>

BPScott temporarily deployed to polaris-react-pr-968 February 6, 2019 17:23 Inactive

Update src/components/TextField/README.md

c85b6f4

Co-Authored-By: dpersing <devon.persing@shopify.com>

BPScott temporarily deployed to polaris-react-pr-968 February 6, 2019 17:23 Inactive

Update src/components/TextField/README.md

72bd889

Co-Authored-By: dpersing <devon.persing@shopify.com>

BPScott temporarily deployed to polaris-react-pr-968 February 6, 2019 17:23 Inactive

Update src/components/TextField/README.md

965a7f6

Co-Authored-By: dpersing <devon.persing@shopify.com>

BPScott temporarily deployed to polaris-react-pr-968 February 6, 2019 17:24 Inactive

sadieredden and others added 2 commits February 6, 2019 09:24

Update src/components/TextField/README.md

480c27c

Co-Authored-By: dpersing <devon.persing@shopify.com>

Update src/components/TextField/README.md

34e7ad5

Co-Authored-By: dpersing <devon.persing@shopify.com>

BPScott temporarily deployed to polaris-react-pr-968 February 6, 2019 17:24 Inactive

Tweaked positioning language

f3b4a94

Language tweaks

d9762ba

BPScott temporarily deployed to polaris-react-pr-968 February 6, 2019 17:32 Inactive

Merge branch 'master' into autocomplete-text-field-a11y-docs

9136499

BPScott temporarily deployed to polaris-react-pr-968 February 6, 2019 17:50 Inactive

dpersing requested a review from kaelig February 15, 2019 17:10

dpersing mentioned this pull request Feb 15, 2019

[a11y] Component accessibility documentation #1050

Closed

kaelig approved these changes Feb 16, 2019

View reviewed changes

Merge branch 'master' into autocomplete-text-field-a11y-docs

54421d3

BPScott deployed to polaris-react-pr-968 February 19, 2019 17:16 View deployment

dpersing merged commit 8b73409 into master Feb 19, 2019

solonaarmstrong-zz pushed a commit that referenced this pull request Feb 20, 2019

[a11y] Autocomplete and text field a11y docs (#968)

7559e4c

* Add a11y content to text field component * Add a11y content for the autocomplete page * Added entry to UNRELEASED.md

kaelig deleted the autocomplete-text-field-a11y-docs branch February 21, 2019 00:49

dpersing added 📓 Documentation and removed 📓 Documentation labels Apr 25, 2019

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

[a11y] Autocomplete and text field a11y docs #968

[a11y] Autocomplete and text field a11y docs #968

Uh oh!

dpersing commented Feb 4, 2019 •

edited

Loading

Uh oh!

sadiesaurus left a comment

Uh oh!

sadiesaurus Feb 5, 2019

Uh oh!

dpersing Feb 6, 2019 •

edited

Loading

Uh oh!

Uh oh!

sadiesaurus Feb 5, 2019

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sadiesaurus Feb 6, 2019

Uh oh!

Uh oh!

Uh oh!

Uh oh!

dpersing commented Feb 6, 2019

Uh oh!

kaelig left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants


		The autocomplete component is based on the [ARIA 1.1 combobox pattern](https://www.w3.org/TR/wai-aria-practices-1.1/#combobox). See the [text field component](https://polaris.shopify.com/components/forms/text-field) for information on implementing the autocomplete component with a text field.

		We recommend implementing the autocomplete list below the text input so that it’s easy to discover and use. However, you can change the position with the `preferredPosition` prop.


		#### Automatically focusing

		In general, avoid focusing on fields automatically. However, you can use the `autoFocus` prop to automatically move focus to the text field. This prop is set to `false` by default and should only be used in cases where it won’t force focus to skip other controls or content of equal or great importance importance.

[a11y] Autocomplete and text field a11y docs #968

[a11y] Autocomplete and text field a11y docs #968

Uh oh!

Conversation

dpersing commented Feb 4, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

WHY are these changes introduced?

WHAT is this pull request doing?

How to 🎩

Screenshots

Autocomplete

Text field (web)

Uh oh!

sadiesaurus left a comment

Choose a reason for hiding this comment

Uh oh!

sadiesaurus Feb 5, 2019

Choose a reason for hiding this comment

Uh oh!

dpersing Feb 6, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

sadiesaurus Feb 5, 2019

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sadiesaurus Feb 6, 2019

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

dpersing commented Feb 6, 2019

Uh oh!

kaelig left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

dpersing commented Feb 4, 2019 •

edited

Loading

dpersing Feb 6, 2019 •

edited

Loading