diff --git a/aio/content/guide/accessibility.md b/aio/content/guide/accessibility.md new file mode 100644 index 0000000000..7146644151 --- /dev/null +++ b/aio/content/guide/accessibility.md @@ -0,0 +1,181 @@ +# Accessibility in Angular + +The web is used by a wide variety of people, including those who have visual or motor impairments. +A variety of assistive technologies are available that make it much easier for these groups to +interact with web-based software applications. +In addition, designing an application to be more accessible generally improves the user experience for all users. + +For an in-depth introduction to issues and techniques for designing accessible applications, see the [Accessibility](https://developers.google.com/web/fundamentals/accessibility/#what_is_accessibility) section of the Google's [Web Fundamentals](https://developers.google.com/web/fundamentals/). + +This page discusses best practices for designing Angular applications that +work well for all users, including those who rely on assistive technologies. + +## Accessibility attributes + +Building accessible web experience often involves setting [ARIA attributes](https://developers.google.com/web/fundamentals/accessibility/semantics-aria) +to provide semantic meaning where it might otherwise be missing. +Use [attribute binding](guide/template-syntax#attribute-binding) template syntax to control the values of accessibility-related attributes. + +When binding to ARIA attributes in Angular, you must use the `attr.` prefix, as the ARIA +specification depends specifically on HTML attributes rather than properties on DOM elements. + +```html + + +``` + +Note that this syntax is only necessary for attribute _bindings_. +Static ARIA attributes require no extra syntax. + +```html + + +``` + +NOTE: + +
+ + By convention, HTML attributes use lowercase names (`tabindex`), while properties use camelCase names (`tabIndex`). + + See the [Template Syntax](https://angular.io/guide/template-syntax#html-attribute-vs-dom-property) guide for more background on the difference between attributes and properties. + +
+ + +## Angular UI components + +The [Angular Material](https://material.angular.io/) library, which is maintained by the Angular team, is a suite of reusable UI components that aims to be fully accessible. +The [Component Development Kit (CDK)](https://material.angular.io/cdk/categories) includes the `a11y` package that provides tools to support various areas of accessibility. +For example: + +* `LiveAnnouncer` is used to announce messages for screen-reader users using an `aria-live` region. See the W3C documentation for more information on [aria-live regions](https://www.w3.org/WAI/PF/aria-1.1/states_and_properties#aria-live). + +* The `cdkTrapFocus` directive traps Tab-key focus within an element. Use it to create accessible experience for components like modal dialogs, where focus must be constrained. + +For full details of these and other tools, see the [Angular CDK accessibility overview](https://material.angular.io/cdk/a11y/overview). + + +### Augmenting native elements + +Native HTML elements capture a number of standard interaction patterns that are important to accessibility. +When authoring Angular components, you should re-use these native elements directly when possible, rather than re-implementing well-supported behaviors. + +For example, instead of creating a custom element for a new variety of button, you can create a component that uses an attribute selector with a native `