Button and link a11y docs #924

dpersing · 2019-01-22T23:10:00Z

This PR includes component-level accessibility information for the link and button components, to appear in the repo and in the style guide. Both pages are included because the button content refers to the link content.

WHY are these changes introduced?

Adds component-level documentation as part of the style guide accessibility documentation project. This content is added after the examples and props, before best practices.

WHAT is this pull request doing?

Adds new accessibility sections for the button and link components README.md files.
Adds an entry for the UNRELEASED.md file under Documentation.

How to 🎩

Check out https://github.com/Shopify/polaris-styleguide/pull/2493 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:

https://polaris.myshopify.io/components/navigation/link
https://polaris.myshopify.io/components/actions/button (includes changes for web, iOS, and Android)

Screenshots

Do/Don't example

Keyboard content example

Mobile-specific example

- Added "keypress" language to overview - Added accessibility section for current features

src/components/Button/README.md

dpersing · 2019-01-22T23:12:14Z

src/components/Button/README.md

+
+## Accessibility
+
+<!-- content-for: android -->


iOS and Android content for the button page, since there are separate tabs. We don't currently have native-specific guidance so I've linked to the platform best practices.

Although it's a bit awkward from the "Web" perspective to begin the section with external resources that don't apply to web, my understanding is that this will eventually change, when we have native-specific guidance.

To make it more clear what content applies to the reader:

We could add an intro sentence under the Accessibility heading that lets readers know that the accessibility guidelines for the button component differ for Web, Android, and iOS. This sets the reader up to expect to look for the content that applies to them.

Perhaps rearrange the leading sentences to start with "For Android, see Material Design ... " and "For iOS, see Apple's ..."

Perhaps add Android, iOS, and Web headings

@sadiesaurus The sections here display on the web, iOS, and Android tabs in the UI in the style guide, which is what the <! content-for: ...> tags are doing in the file. The Mobile-specific example screenshot is showing what would show up for Android on that tab, while the other specific content shows up for each tab specified. That's what the first item in the 🎩 recommendations is doing, pulling from the PR that @kaelig worked on to do this formatting. Let me know if that's clear!

Ohhhh, yes now I see. I didn't 🎩 it properly last time. This works well!

Please disregard my comment! 😅

I agree that headings would help with the Markdown readability in GitHub itself. I couldn't find a solid and elegant way to make it work :/

@BPScott and I might have cycles to look into it later this year.

src/components/Button/README.md

dpersing · 2019-01-22T23:16:40Z

@kaelig, would particularly love any thoughts in relation to what you're tinkering with for formatting for this content.

dpersing · 2019-01-23T19:34:06Z

Dropped a question about the heading hierarchy in the related style guide PR: https://github.com/Shopify/polaris-styleguide/pull/2493#issuecomment-456935369

~~Currently, the Accessibility heading is getting rendered as an <h3>, which is throwing off the section hierarchy.~~

Fixed!

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

src/components/Button/README.md

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

src/components/Link/README.md

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

dpersing · 2019-02-07T17:24:31Z

@kaelig Can you take another gander?

dpersing · 2019-02-07T21:12:40Z

src/components/Button/README.md

+- Use the `ariaControls` prop to add an `aria-controls` attribute to the button. Use the attribute to point to the unique `id` of the content that the button manages.
+- If a button expands or collapses adjacent content, then use the `ariaExpanded` prop to add the `aria-expanded` attribute to the button. Set the value to convey the current expanded (`true`) or collapsed (`false`) state of the content.
+- Use the `disabled` prop to set the `disabled` state of the button. This prevents merchants from being able to interact with the button, and conveys its inactive state to assistive technologies.
+- Use the `ariaPressed` prop to add an `aria-pressed` attribute to the button. Use the `pressed` prop to add a pressed-style to the button as well.


Added to document use for ariaPressed and pressed: #984

#984 (comment)

kaelig

kaelig · 2019-02-16T00:42:24Z

UNRELEASED.md

+- Added `Stack.Item` properties and description to [style guide](https://polaris.shopify.com)’s ([#772](https://github.com/Shopify/polaris-react/pull/772))
+- Added accessibility documentation for the button and link components ([#924](https://github.com/Shopify/polaris-react/pull/924))
+- Added accessibility documentation to the resource list and data table components ([#927](https://github.com/Shopify/polaris-react/pull/927))
+- Added accessibility recommendations for the caption component ([#928](https://github.com/Shopify/polaris-react/pull/928/))


I'm a bit confused as to why some of these unrelated entries are in this PR?

* Added accessibility section for the button component * Added accessibility section for the link component * Added entry for Unreleased.md

dpersing added 9 commits January 22, 2019 11:57

Button accessibility section

9c9f783

- Added "keypress" language to overview - Added accessibility section for current features

Fixed Android info placement

39d1b54

Custom key events

ecce3ec

Changed key formatting for readability

b9f38f2

Fixed link

1238cfe

Added accessibility section for the link component

ca9e383

Added line Unreleased.md

016c57d

Re-ordered examples for better flow/wrapping

6ccae15

Removed the native content

85d1c9a

BPScott temporarily deployed to polaris-react-pr-924 January 22, 2019 23:10 Inactive

Added PR link

0eb1e78

BPScott temporarily deployed to polaris-react-pr-924 January 22, 2019 23:11 Inactive

dpersing commented Jan 22, 2019

View reviewed changes

src/components/Button/README.md Show resolved Hide resolved

dpersing commented Jan 22, 2019

View reviewed changes

src/components/Button/README.md Show resolved Hide resolved

dpersing commented Jan 22, 2019

View reviewed changes

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

dpersing requested review from ry5n, danrosenthal, kaelig, sadiesaurus and StephPoce January 22, 2019 23:15

dpersing mentioned this pull request Jan 23, 2019

[WIP] Added a11y section to the Button Readme.md #705

Closed

dpersing changed the title ~~Button link a11y docs~~ Button and link a11y docs Jan 23, 2019

dpersing mentioned this pull request Jan 24, 2019

Data table and resource list a11y docs #927

Merged

Update src/components/Button/README.md

5da2eae

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

BPScott temporarily deployed to polaris-react-pr-924 January 24, 2019 23:44 Inactive

dpersing commented Jan 24, 2019

View reviewed changes

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

Update src/components/Button/README.md

48f099f

Update src/components/Link/README.md

f5ff638

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

BPScott temporarily deployed to polaris-react-pr-924 January 30, 2019 18:58 Inactive

kaelig approved these changes Jan 30, 2019

View reviewed changes

kaelig suggested changes Jan 30, 2019

View reviewed changes

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

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

Merge branch 'master' into button-link-a11y-docs

f0c7e43

BPScott temporarily deployed to polaris-react-pr-924 February 7, 2019 17:23 Inactive

Update src/components/Link/README.md

1b536bb

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

BPScott temporarily deployed to polaris-react-pr-924 February 7, 2019 17:24 Inactive

Update src/components/Link/README.md

5a70def

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

BPScott temporarily deployed to polaris-react-pr-924 February 7, 2019 17:24 Inactive

Removed Structure heading and added item about ariaPressed/pressed

6ce31b7

BPScott temporarily deployed to polaris-react-pr-924 February 7, 2019 21:10 Inactive

Restructured headings

b602322

BPScott temporarily deployed to polaris-react-pr-924 February 7, 2019 21:12 Inactive

dpersing commented Feb 7, 2019

View reviewed changes

Tweaked guidance based on decision around the pressed prop

e4f56cd

#984 (comment)

BPScott deployed to polaris-react-pr-924 February 7, 2019 23:38 View deployment

dpersing mentioned this pull request Feb 15, 2019

[a11y] Component accessibility documentation #1050

Closed

kaelig approved these changes Feb 16, 2019

View reviewed changes

kaelig reviewed Feb 16, 2019

View reviewed changes

dpersing added 2 commits February 19, 2019 09:59

Merge branch 'master' into button-link-a11y-docs

b75ec5c

Merge branch 'master' into button-link-a11y-docs

39c31e2

dpersing merged commit f98a742 into master Feb 19, 2019

BPScott requested a deployment to polaris-react-pr-924 February 19, 2019 18:02 Abandoned

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

Button and link a11y docs (#924)

8e93e61

* Added accessibility section for the button component * Added accessibility section for the link component * Added entry for Unreleased.md

kaelig deleted the button-link-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

Button and link a11y docs #924

Button and link a11y docs #924

dpersing commented Jan 22, 2019

dpersing Jan 22, 2019

sadiesaurus Jan 26, 2019

dpersing Jan 28, 2019

sadiesaurus Jan 28, 2019

kaelig Feb 16, 2019

dpersing commented Jan 22, 2019

dpersing commented Jan 23, 2019 •

edited

Loading

dpersing commented Feb 7, 2019

dpersing Feb 7, 2019

kaelig left a comment

kaelig Feb 16, 2019

Button and link a11y docs #924

Button and link a11y docs #924

Conversation

dpersing commented Jan 22, 2019

WHY are these changes introduced?

WHAT is this pull request doing?

How to 🎩

Screenshots

Do/Don't example

Keyboard content example

Mobile-specific example

dpersing Jan 22, 2019

Choose a reason for hiding this comment

sadiesaurus Jan 26, 2019

Choose a reason for hiding this comment

dpersing Jan 28, 2019

Choose a reason for hiding this comment

sadiesaurus Jan 28, 2019

Choose a reason for hiding this comment

kaelig Feb 16, 2019

Choose a reason for hiding this comment

dpersing commented Jan 22, 2019

dpersing commented Jan 23, 2019 • edited Loading

dpersing commented Feb 7, 2019

dpersing Feb 7, 2019

Choose a reason for hiding this comment

kaelig left a comment

Choose a reason for hiding this comment

kaelig Feb 16, 2019

Choose a reason for hiding this comment

dpersing commented Jan 23, 2019 •

edited

Loading