Skip to content

Commit c5076ba

Browse files
crisbetojelbourn
authored andcommitted
docs(a11y): add docs about a11y style utilities (#13067)
Adds a couple of paragraphs about the utility styles that come with `cdk/a11y`.
1 parent 714c205 commit c5076ba

File tree

1 file changed

+44
-8
lines changed

1 file changed

+44
-8
lines changed

src/cdk/a11y/a11y.md

Lines changed: 44 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ interface ListKeyManagerOption {
2222
Navigation through options can be made to wrap via the `withWrap` method
2323
```ts
2424
this.keyManager = new FocusKeyManager(...).withWrap();
25-
```
25+
```
2626

2727
### Types of key managers
2828
There are two varieties of `ListKeyManager`, `FocusKeyManager` and `ActiveDescendantKeyManager`.
@@ -37,7 +37,7 @@ interface FocusableOption extends ListKeyManagerOption {
3737
```
3838

3939
#### ActiveDescendantKeyManager
40-
Used when options will be marked as active via `aria-activedescendant`.
40+
Used when options will be marked as active via `aria-activedescendant`.
4141
Each item managed must implement the
4242
`Highlightable` interface:
4343
```ts
@@ -69,10 +69,10 @@ This directive will not prevent focus from moving out of the trapped region due
6969
interaction.
7070

7171
### Regions
72-
Regions can be declared explicitly with an initial focus element by using
73-
the `cdkFocusRegionStart`, `cdkFocusRegionEnd` and `cdkFocusInitial` DOM attributes.
74-
`cdkFocusInitial` specifies the element that will receive focus upon initialization of the region.
75-
`cdkFocusRegionStart` and `cdkFocusRegionEnd` define the region within which focus will be
72+
Regions can be declared explicitly with an initial focus element by using
73+
the `cdkFocusRegionStart`, `cdkFocusRegionEnd` and `cdkFocusInitial` DOM attributes.
74+
`cdkFocusInitial` specifies the element that will receive focus upon initialization of the region.
75+
`cdkFocusRegionStart` and `cdkFocusRegionEnd` define the region within which focus will be
7676
trapped. When using the tab key, focus will move through this region and wrap around on either end.
7777

7878
For example:
@@ -94,7 +94,7 @@ details.
9494
## LiveAnnouncer
9595
`LiveAnnouncer` is used to announce messages for screen-reader users using an `aria-live` region.
9696
See [the W3C's WAI-ARIA](https://www.w3.org/TR/wai-aria/states_and_properties#aria-live)
97-
for more information on aria-live regions.
97+
for more information on aria-live regions.
9898

9999
### Example
100100
```ts
@@ -135,7 +135,7 @@ if you `markForCheck` in the subscription you must put yourself back in the Angu
135135

136136
```ts
137137
focusMonitor.monitor(el).subscribe(origin => this.ngZone.run(() => /* ... */ ));
138-
```
138+
```
139139

140140
Any element that is monitored by calling `monitor` should eventually be unmonitored by calling
141141
`stopMonitoring` with the same element.
@@ -158,3 +158,39 @@ the host element with `checkChildren` set to `true`. Each of these directives ha
158158
`cdkFocusChange` that will emit the new `FocusOrigin` whenever it changes.
159159

160160
<!-- example(focus-monitor-directives) -->
161+
162+
## Styling utilities
163+
The CDK `a11y` package comes with a set of CSS styles that can be used when building accessible
164+
components. To take advantage of them, you have to include the styles in your global stylesheet.
165+
If you're using Material together with the CDK, these styles have been included for you already.
166+
167+
```scss
168+
@import '~@angular/cdk/text-field/text-field';
169+
170+
@include cdk-a11y();
171+
```
172+
173+
### Hiding elements, while keeping them available for screen readers
174+
By default, screen readers and other assistive technology will skip elements that have
175+
`display: none`, `visibility: hidden` etc. In some cases you may need to visually hide an element,
176+
while keeping it available for assistive technology. You can do so using the `cdk-visually-hidden`
177+
class:
178+
179+
```html
180+
<div class="custom-checkbox">
181+
<input type="checkbox" class="cdk-visually-hidden">
182+
</div>
183+
```
184+
185+
### Targeting high contrast users
186+
The `a11y` package offers a mixin that allows you to target users that have the Windows high
187+
contrast mode turned on, via a media query. To target high contrast users, you can wrap your
188+
styles with the `cdk-high-contrast` mixin:
189+
190+
```scss
191+
button {
192+
@include cdk-high-contrast {
193+
outline: solid 1px;
194+
}
195+
}
196+
```

0 commit comments

Comments
 (0)