docs(cdk/a11y): update Sass docs for new theming API (#22468)

This change updates the Sass documentation for cdk/a11y to reflect the
new `@use`-based API. Additionally, it adds documentation for the
parameters to `cdk.high-contrast`.

(cherry picked from commit 2a9854e)

Author: jelbourn

src/cdk/a11y/a11y.md

@@ -178,22 +178,24 @@ the host element with `checkChildren` set to `true`. Each of these directives ha
 
 ### 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.
+The `cdk/a11y` package comes with Sass mixins that produce styles useful for building
+accessible experiences. 
 
-```scss
-@import '~@angular/cdk/text-field/text-field';
+#### Hiding elements in an accessible way
 
-@include cdk-a11y();
-```
+Screen readers and other assistive technology skip elements that have `display: none`,
+`visibility: hidden`, `opacity: 0`, `height: 0`, or `width: 0`. In some cases you may need to
+visually hide an element while keeping it available to assistive technology. You can do so using
+the `a11y-visually-hidden` Sass mixin, which emits the `.cdk-visually-hidden` CSS class.
 
-#### Hiding elements in an accessible way
+If you're using Angular Material, this class is included automatically by Angular Material's theming
+system. Otherwise, you can include this mixin in a global stylesheet.
 
-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:
+```scss
+@use '~@angular/cdk';
+
+@include cdk.a11y-visually-hidden();
+```
 
 ```html
 <div class="custom-checkbox">
@@ -203,15 +205,36 @@ class:
 
 #### 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. To target high contrast users, you can wrap your styles with the
-`cdk-high-contrast` mixin. The mixin works by targeting a CSS class which is added to the `body`
-by the CDK when high contrast mode is detected at runtime.
+Microsoft Windows includes an accessibility feature called [Windows High Contrast Mode][]. The
+`cdk/a11y` package provides a Sass mixin that lets you define styles that only apply in high
+contrast mode. To create a high contrast style, define your style inside the `high-contrast` mixin.
+
+The mixin works by targeting a CSS class which is added to the `body` by the CDK when high contrast
+mode is detected at runtime, via the `HighContrastModeDetector` service.
 
 ```scss
+@use '~@angular/cdk';
+
 button {
-  @include cdk-high-contrast {
+  @include cdk.high-contrast() {
     outline: solid 1px;
   }
 }
 ```
+
+The `high-contrast` mixin accepts two optional parameters, `$target` and `$encapsulation`.
+
+The `$target` parameter allows you to specify which variation of high contrast mode your style
+targets. The accepted values are `active` (default), `black-on-white`, and `white-on-black`. These
+values correspond to the supported values for the
+[`-ms-high-contrast` media query][ms-high-contrast].
+
+The `$encapsulation` parameter affects how the emitted styles interact with style encapsulation.
+The supported values are `on`, `off`, and `any`. The default value is `any`, which works for any
+encapsulation scenario by emitting two selectors. Specifying either `on` or `off` slightly reduces
+the amount of CSS emitted by limiting the styles to components with encapsulation enabled or
+disabled, respectively. The styles emitted for encapsulated components work for both Angular's
+emulated style encapsulation and for native Shadow DOM encapsulation.
+
+[Windows High Contrast Mode]: https://support.microsoft.com/en-us/windows/use-high-contrast-mode-in-windows-10-fedc744c-90ac-69df-aed5-c8a90125e696
+[ms-high-contrast]: https://blogs.windows.com/msedgedev/2020/09/17/styling-for-windows-high-contrast-with-new-standards-for-forced-colors/