Skip to content

docs(a11y): add docs about a11y style utilities #13067

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Sep 11, 2018
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 44 additions & 8 deletions src/cdk/a11y/a11y.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`.
Expand All @@ -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
Expand Down Expand Up @@ -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:
Expand All @@ -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
Expand Down Expand Up @@ -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.
Expand All @@ -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.

<!-- example(focus-monitor-directives) -->

## 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
<div class="custom-checkbox">
<input type="checkbox" class="cdk-visually-hidden">
</div>
```

### 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;
}
}
```