diff --git a/src/cdk/a11y/a11y.md b/src/cdk/a11y/a11y.md index 7b08ce5d992..51ba0eb0003 100644 --- a/src/cdk/a11y/a11y.md +++ b/src/cdk/a11y/a11y.md @@ -22,7 +22,7 @@ interface ListKeyManagerOption { Navigation through options can be made to wrap via the `withWrap` method ```ts this.keyManager = new FocusKeyManager(...).withWrap(); -``` +``` ### Types of key managers There are two varieties of `ListKeyManager`, `FocusKeyManager` and `ActiveDescendantKeyManager`. @@ -37,7 +37,7 @@ interface FocusableOption extends ListKeyManagerOption { ``` #### ActiveDescendantKeyManager -Used when options will be marked as active via `aria-activedescendant`. +Used when options will be marked as active via `aria-activedescendant`. Each item managed must implement the `Highlightable` interface: ```ts @@ -69,10 +69,10 @@ This directive will not prevent focus from moving out of the trapped region due interaction. ### Regions -Regions can be declared explicitly with an initial focus element by using -the `cdkFocusRegionStart`, `cdkFocusRegionEnd` and `cdkFocusInitial` DOM attributes. -`cdkFocusInitial` specifies the element that will receive focus upon initialization of the region. -`cdkFocusRegionStart` and `cdkFocusRegionEnd` define the region within which focus will be +Regions can be declared explicitly with an initial focus element by using +the `cdkFocusRegionStart`, `cdkFocusRegionEnd` and `cdkFocusInitial` DOM attributes. +`cdkFocusInitial` specifies the element that will receive focus upon initialization of the region. +`cdkFocusRegionStart` and `cdkFocusRegionEnd` define the region within which focus will be trapped. When using the tab key, focus will move through this region and wrap around on either end. For example: @@ -94,7 +94,7 @@ details. ## LiveAnnouncer `LiveAnnouncer` is used to announce messages for screen-reader users using an `aria-live` region. See [the W3C's WAI-ARIA](https://www.w3.org/TR/wai-aria/states_and_properties#aria-live) -for more information on aria-live regions. +for more information on aria-live regions. ### Example ```ts @@ -135,7 +135,7 @@ if you `markForCheck` in the subscription you must put yourself back in the Angu ```ts focusMonitor.monitor(el).subscribe(origin => this.ngZone.run(() => /* ... */ )); -``` +``` Any element that is monitored by calling `monitor` should eventually be unmonitored by calling `stopMonitoring` with the same element. @@ -158,3 +158,39 @@ the host element with `checkChildren` set to `true`. Each of these directives ha `cdkFocusChange` that will emit the new `FocusOrigin` whenever it changes. + +## Styling utilities +The CDK `a11y` package comes with a set of CSS styles that can be used when building accessible +components. To take advantage of them, you have to include the styles in your global stylesheet. +If you're using Material together with the CDK, these styles have been included for you already. + +```scss +@import '~@angular/cdk/text-field/text-field'; + +@include cdk-a11y(); +``` + +### Hiding elements, while keeping them available for screen readers +By default, screen readers and other assistive technology will skip elements that have +`display: none`, `visibility: hidden` etc. In some cases you may need to visually hide an element, +while keeping it available for assistive technology. You can do so using the `cdk-visually-hidden` +class: + +```html +
+ +
+``` + +### Targeting high contrast users +The `a11y` package offers a mixin that allows you to target users that have the Windows high +contrast mode turned on, via a media query. To target high contrast users, you can wrap your +styles with the `cdk-high-contrast` mixin: + +```scss +button { + @include cdk-high-contrast { + outline: solid 1px; + } +} +```