Accessibility article #191

smhigley · 2017-09-22T19:43:26Z

Updated version of the accessibility article, resolves #17.

Refs: #141

edhager · 2017-09-22T19:56:50Z

site/source/tutorials/accessibility.md

@@ -0,0 +1,233 @@
+## Philosophy & Approach
+
+Dojo 2 is grounded in the belief that accessibility is as important online as it is in our built environments, and architects of both share a similar responsibility to provide access to all. Accessibility failures abound in each setting, and they can be very obvious once one starts looking:


Does "built environments" mean the "real world"? When I first read that, I was thinking software development build tools. How about "physical environments"?

edhager · 2017-09-22T19:59:50Z

site/source/tutorials/accessibility.md

+|:---:|:---:|
+| Afterthought Accessibility | Designed Accessibility |
+
+Web developers have an additional hurdle to jump over, since accessibility failures online are often invisible and silent. Without proper testing, it is all too easy to add a `title` attribute to a link or a `<label>` without a `for` and think requirements have been met.


This is awkward:

or a <label> without a for

How about "or a for attribute to a label"?

edhager · 2017-09-22T20:00:41Z

site/source/tutorials/accessibility.md

+
+Web developers have an additional hurdle to jump over, since accessibility failures online are often invisible and silent. Without proper testing, it is all too easy to add a `title` attribute to a link or a `<label>` without a `for` and think requirements have been met.
+
+The advances in spec and support for ARIA attributes are fantastic, but they can feed into the false impression that accessibility is achieved by slapping an `aria-labelledby` or `role` onto a finished widget and calling it a day. The only approach that has the potential to deliver truly equal access is to begin thinking about accessibility in design and continue through to development and testing. For that reason, Dojo 2 has no separate accessibility mixin; all our widgets have been designed to be accessible by default, and any tools needed to meet WCAG standards have been integrated into `widget-core` and `widgets`.


I am not sure what "advances in spec" means.

edhager · 2017-09-22T20:02:35Z

site/source/tutorials/accessibility.md

+
+Web developers have an additional hurdle to jump over, since accessibility failures online are often invisible and silent. Without proper testing, it is all too easy to add a `title` attribute to a link or a `<label>` without a `for` and think requirements have been met.
+
+The advances in spec and support for ARIA attributes are fantastic, but they can feed into the false impression that accessibility is achieved by slapping an `aria-labelledby` or `role` onto a finished widget and calling it a day. The only approach that has the potential to deliver truly equal access is to begin thinking about accessibility in design and continue through to development and testing. For that reason, Dojo 2 has no separate accessibility mixin; all our widgets have been designed to be accessible by default, and any tools needed to meet WCAG standards have been integrated into `widget-core` and `widgets`.


I would remove "our" from "all our widgets have been designed".

edhager · 2017-09-22T20:03:35Z

site/source/tutorials/accessibility.md

+
+Web developers have an additional hurdle to jump over, since accessibility failures online are often invisible and silent. Without proper testing, it is all too easy to add a `title` attribute to a link or a `<label>` without a `for` and think requirements have been met.
+
+The advances in spec and support for ARIA attributes are fantastic, but they can feed into the false impression that accessibility is achieved by slapping an `aria-labelledby` or `role` onto a finished widget and calling it a day. The only approach that has the potential to deliver truly equal access is to begin thinking about accessibility in design and continue through to development and testing. For that reason, Dojo 2 has no separate accessibility mixin; all our widgets have been designed to be accessible by default, and any tools needed to meet WCAG standards have been integrated into `widget-core` and `widgets`.


Can "WCAG" be a link to something that describes it.

edhager · 2017-09-22T22:33:23Z

site/source/tutorials/accessibility.md

+This overview only touched on properties that primarily exist for accessibility-related reasons, but any design decision or property change will end up affecting accessibility in some way. For some of those, such as `invalid`, `disabled`, and `readOnly`, we handle setting ARIA attributes in the background in addition to toggling classes without any extra attention needed from the user. In other cases, such as `getResultLabel` in ComboBox or `renderMonthLabel` in Calendar, it is entirely up to the widget user to ensure the returned result includes clear, screen-reader-accessible text content.
+
+## Styling
+The base Dojo 2 theme meets WCAG AA color contrast guidelines, but it is up to the user to double check the final styles as changes to font size or background could affect readability. Widget css packaged with Dojo2 also includes `:focus` styles for all focusable nodes.


Widget css packaged

There are a couple places where CSS is not capitalized and one that is. I think they should all be all-caps.

edhager · 2017-09-22T22:35:09Z

site/source/tutorials/accessibility.md

+## Styling
+The base Dojo 2 theme meets WCAG AA color contrast guidelines, but it is up to the user to double check the final styles as changes to font size or background could affect readability. Widget css packaged with Dojo2 also includes `:focus` styles for all focusable nodes.
+
+There is a set of base styles provided by `@dojo/widgets` separate from themes, containing basic utility classes like the screen reader-accessible visually hidden style. To use it, import `baseCss` separately like so:


Can we have a sentence that quickly describes what "visually hidden" means so people realize that the difference between that and "display: none;"?

edhager · 2017-09-22T22:36:56Z

site/source/tutorials/accessibility.md

+```
+
+## Focus Management
+Dojo 2 will provide a focus manager for situations where focus needs to be directly managed, since directly touching the DOM within widgets is discouraged. This feature is currently in development.


Do we have any articles that could be linked here that talk about the reasons why manipulating the DOM is discouraged?

edhager · 2017-09-22T22:38:51Z

site/source/tutorials/accessibility.md

+
+### Button
+
+This widget returns a simple `<button>` element.


Should have a comment about native keyboard interaction.

edhager · 2017-09-22T22:42:55Z

site/source/tutorials/accessibility.md

+	onclick: this._togglePopup
+}, [ 'Click to open popup' ])
+```
+Since this example uses a `<button>` element, it requires neither an explicit `tabindex` nor an `onkeydown` event to work properly with a keyboard. Wherever possible, Dojo 2 takes advantage of built-in accessibility by using native elements; if it looks like a button and acts like a button, it should be a `<button>`. However, while native functionality is the easiest and most straightforward path to good accessibility, there are times when it’s just not possible or no such element exists.


I wonder if the text starting from " Wherever possible, Dojo 2 takes advantage of built-in accessibility by using native elements;" to the end of the paragraph should be moved closer to the top of the article before "Using Dojo 2 Widgets". It might be good if the reader knew some of these things before reading about each type of widget.

dylans

Very informative, lots of small nits for consistency, a few typos, and a couple of suggestions.

dylans · 2017-09-26T15:10:29Z

site/source/tutorials/accessibility.md

@@ -0,0 +1,250 @@
+## Philosophy & Approach


Philosophy and approach (we're lowercasing non-proper nouns in titles)

dylans · 2017-09-26T15:11:17Z

site/source/tutorials/accessibility.md

+
+Web developers have an additional hurdle to jump over, since accessibility failures online are often invisible and silent. Without proper testing, it is all too easy to add a redundant `title` attribute to a link or create a `<label>` while forgetting the `for` attribute.
+
+The increasingly fleshed-out spec and support for ARIA attributes is fantastic, but can feed into the false impression that accessibility is achieved by slapping an `aria-labelledby` or `role` onto a finished widget and calling it a day. The only approach that has the potential to deliver truly equal access is to begin thinking about accessibility in design and continue through to development and testing. For that reason, Dojo 2 has no separate accessibility mixin; all Dojo 2 widgets have been designed to be accessible by default, and any tools needed to meet [WCAG](https://www.w3.org/TR/WCAG20/) standards have been integrated into `@dojo/widget-core` and `@dojo/widgets`.


spec -> specification

a day -> done

dylans · 2017-09-26T15:12:14Z

site/source/tutorials/accessibility.md

+
+The increasingly fleshed-out spec and support for ARIA attributes is fantastic, but can feed into the false impression that accessibility is achieved by slapping an `aria-labelledby` or `role` onto a finished widget and calling it a day. The only approach that has the potential to deliver truly equal access is to begin thinking about accessibility in design and continue through to development and testing. For that reason, Dojo 2 has no separate accessibility mixin; all Dojo 2 widgets have been designed to be accessible by default, and any tools needed to meet [WCAG](https://www.w3.org/TR/WCAG20/) standards have been integrated into `@dojo/widget-core` and `@dojo/widgets`.
+
+## Using Dojo 2 Widgets


Using Dojo 2 widgets

dylans · 2017-09-26T15:12:28Z

site/source/tutorials/accessibility.md

+The increasingly fleshed-out spec and support for ARIA attributes is fantastic, but can feed into the false impression that accessibility is achieved by slapping an `aria-labelledby` or `role` onto a finished widget and calling it a day. The only approach that has the potential to deliver truly equal access is to begin thinking about accessibility in design and continue through to development and testing. For that reason, Dojo 2 has no separate accessibility mixin; all Dojo 2 widgets have been designed to be accessible by default, and any tools needed to meet [WCAG](https://www.w3.org/TR/WCAG20/) standards have been integrated into `@dojo/widget-core` and `@dojo/widgets`.
+
+## Using Dojo 2 Widgets
+All widgets provided through `@dojo/widgets` have been created with a range of assistive tech and perceptual differences in mind. Wherever possible, Dojo 2 takes advantage of built-in accessibility by using native elements; if it looks like a button and acts like a button, it should be a `<button>`. Widgets than go beyond the functionality provided by native elements use internal logic to provide proper semantics and non-mouse interaction.


tech -> technologies

Widgets than go -> Widgets that go

dylans · 2017-09-26T15:13:59Z

site/source/tutorials/accessibility.md

+Below is a list of widgets in `@dojo/widgets`, along with a description of the keyboard interaction (if applicable) and any properties included primarily for accessibility (shortened to a11y):
+
+### Label
+All form widgets apart from the Button contain a `label` property that allows widget authors to easily associate a text label with the control. Label is also available as a separate widget for use with custom form controls. The Label widget included with Dojo form widgets is associated with the form input by wrapping it as a child element. When used separately, it is also possible to explicitly set the `forId` property to the id of an input.


Button -> Button

Label -> Label

wrapping it as -> wrapping the label as

to the id of -> to the id of

dylans · 2017-09-26T15:55:29Z

site/source/tutorials/accessibility.md

+	}
+}
+```
+


Maybe worth adding a sentence referring to the full theming tutorial that is being worked on with a coming soon link for now?

dylans · 2017-09-26T15:55:35Z

site/source/tutorials/accessibility.md

+}
+```
+
+## Focus Management


Focus management

dylans · 2017-09-26T15:55:52Z

site/source/tutorials/accessibility.md

+## Focus Management
+Dojo 2 will provide a focus manager for situations where focus needs to be directly managed, since the [virtual DOM approach](./working_with_virtual_dom) means directly touching the DOM within widgets is discouraged. This feature is currently in development.
+
+## Writing Custom Widgets


Writing custom widgets

dylans · 2017-09-26T15:56:31Z

site/source/tutorials/accessibility.md

+Dojo 2 will provide a focus manager for situations where focus needs to be directly managed, since the [virtual DOM approach](./working_with_virtual_dom) means directly touching the DOM within widgets is discouraged. This feature is currently in development.
+
+## Writing Custom Widgets
+All DOM attributes can be set with `VirtualDomProperties` so, apart from managing focus, no extra tools should be required to create strongly accessible widgets. For example, the following code would create an accessible popup button:


Should probably also link to the tutorial on writing custom widgets in general, and how this is specific to a11y for custom widgets, and probably also look at the custom widgets tutorial and add an aside linking to this article

dylans · 2017-09-26T15:59:40Z

site/source/tutorials/accessibility.md

+- Ensure nodes that support any sort of user interaction are both focusable and have accessible descriptive text.
+- Leave native focus styles intact, or provide a sufficiently visible alternative.
+- Check the [WAI-ARIA Authoring Practices 1.1](https://www.w3.org/TR/wai-aria-practices-1.1) for information on node attributes and keyboard interaction for many common widget patterns. Even for more complex widgets, these serve as good building blocks.
+- Make a quick POC and try [inspecting its accessibility attributes](http://khan.github.io/tota11y/) in the browser and running through one of the [many](https://medium.com/@addyosmani/accessible-ui-components-for-the-web-39e727101a67) [excellent](http://www-03.ibm.com/able/guidelines/ci162/accessibility_checklist.html) [a11y](https://www.wuhcag.com/wcag-checklist/) [checklists](https://ebay.gitbooks.io/oatmeal/content/).


POC -> proof of concept

dylans

Looks great, thanks! One suggestion for updating relevant tickets to remind us to update this later when things change, but that's not a blocker.

dylans · 2017-09-27T19:05:43Z

site/source/tutorials/accessibility.md

@@ -159,7 +159,7 @@ ___

 ### Dialog

-The Dialog widget creates a controlled dialog element. Controlled focus is not yet implemented, but will be added along with the focus manager.
+The `Dialog` widget creates a controlled dialog element. Controlled focus is not yet implemented, but will be added along with the focus manager in a future Dojo release.


Maybe add a note in the ticket about this to update the tutorial when this change occurs?

As well as any other mentions in this tutorial of future changes?

updated a11y article

d3e4bea

smhigley mentioned this pull request Sep 22, 2017

Ref #17 - initial Accessibility article #141

Closed

edhager self-requested a review September 22, 2017 19:44

edhager requested changes Sep 22, 2017

View reviewed changes

dylans added this to the 2017.09 milestone Sep 23, 2017

edits to a11y article

aebf4b0

dylans requested changes Sep 26, 2017

View reviewed changes

feedback round 2

6a592c7

dylans approved these changes Sep 27, 2017

View reviewed changes

smhigley mentioned this pull request Sep 29, 2017

Focus Management dojo/widget-core#107

Closed

edhager approved these changes Oct 2, 2017

View reviewed changes

smhigley merged commit 5f8f485 into dojo:master Oct 2, 2017

kitsonk mentioned this pull request Oct 10, 2017

Focus Management dojo/widgets#309

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Accessibility article #191

Accessibility article #191

smhigley commented Sep 22, 2017

edhager Sep 22, 2017

edhager Sep 22, 2017

edhager Sep 22, 2017

edhager Sep 22, 2017

edhager Sep 22, 2017

edhager Sep 22, 2017

edhager Sep 22, 2017

edhager Sep 22, 2017

edhager Sep 22, 2017

edhager Sep 22, 2017

dylans left a comment

dylans Sep 26, 2017

dylans Sep 26, 2017

dylans Sep 26, 2017

dylans Sep 26, 2017

dylans Sep 26, 2017

dylans Sep 26, 2017

dylans Sep 26, 2017

dylans Sep 26, 2017

dylans Sep 26, 2017

dylans Sep 26, 2017

dylans Sep 26, 2017

dylans Sep 26, 2017

dylans Sep 26, 2017

dylans Sep 26, 2017

dylans Sep 26, 2017

dylans left a comment

dylans Sep 27, 2017

dylans Sep 27, 2017

smhigley Sep 29, 2017

		@@ -0,0 +1,233 @@
		## Philosophy & Approach

		Dojo 2 is grounded in the belief that accessibility is as important online as it is in our built environments, and architects of both share a similar responsibility to provide access to all. Accessibility failures abound in each setting, and they can be very obvious once one starts looking:


		Web developers have an additional hurdle to jump over, since accessibility failures online are often invisible and silent. Without proper testing, it is all too easy to add a `title` attribute to a link or a `<label>` without a `for` and think requirements have been met.

		The advances in spec and support for ARIA attributes are fantastic, but they can feed into the false impression that accessibility is achieved by slapping an `aria-labelledby` or `role` onto a finished widget and calling it a day. The only approach that has the potential to deliver truly equal access is to begin thinking about accessibility in design and continue through to development and testing. For that reason, Dojo 2 has no separate accessibility mixin; all our widgets have been designed to be accessible by default, and any tools needed to meet WCAG standards have been integrated into `widget-core` and `widgets`.


		Web developers have an additional hurdle to jump over, since accessibility failures online are often invisible and silent. Without proper testing, it is all too easy to add a redundant `title` attribute to a link or create a `<label>` while forgetting the `for` attribute.

		The increasingly fleshed-out spec and support for ARIA attributes is fantastic, but can feed into the false impression that accessibility is achieved by slapping an `aria-labelledby` or `role` onto a finished widget and calling it a day. The only approach that has the potential to deliver truly equal access is to begin thinking about accessibility in design and continue through to development and testing. For that reason, Dojo 2 has no separate accessibility mixin; all Dojo 2 widgets have been designed to be accessible by default, and any tools needed to meet [WCAG](https://www.w3.org/TR/WCAG20/) standards have been integrated into `@dojo/widget-core` and `@dojo/widgets`.


		The increasingly fleshed-out spec and support for ARIA attributes is fantastic, but can feed into the false impression that accessibility is achieved by slapping an `aria-labelledby` or `role` onto a finished widget and calling it a day. The only approach that has the potential to deliver truly equal access is to begin thinking about accessibility in design and continue through to development and testing. For that reason, Dojo 2 has no separate accessibility mixin; all Dojo 2 widgets have been designed to be accessible by default, and any tools needed to meet [WCAG](https://www.w3.org/TR/WCAG20/) standards have been integrated into `@dojo/widget-core` and `@dojo/widgets`.

		## Using Dojo 2 Widgets

Accessibility article #191

Accessibility article #191

Conversation

smhigley commented Sep 22, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dylans left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dylans left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment