docs(material/theming): document strong focus indicators (#22374)

This adds documentation for strong focus indicators as part of the
theming guide. This feature has been "soft launched" inside Google, but
hasn't been documented for widespread adoption. At this stage, I'm
confident enough in the stability of the feature to document it for
public usage.

Author: jelbourn

guides/theming.md

@@ -367,6 +367,85 @@ $my-palette: mat.define-palette(mat.$indigo-palette);
 }
 ```
 
+## Strong focus indicators
+
+By default, most components indicate browser focus by changing their background color as described
+by the Material Design specification. This behavior, however, can fall short of accessibility
+requirements, such as [WCAG][], which require a stronger indication of browser focus.
+
+Angular Material supports rendering highly visible outlines on focused elements. Applications can
+enable these strong focus indicators via two Sass mixins:
+`strong-focus-indicators` and `strong-focus-indicators-theme`.
+
+The `strong-focus-indicators` mixin emits structal indicator styles for all components. This mixin
+should be included exactly once in an application, similar to the `core` mixin described above.
+
+The `strong-focus-indicators-theme` mixin emits only the indicator's color styles. This mixin should
+be included once per theme, similar to the theme mixins described above. Additionally, you can use
+this mixin to change the color of the focus indicators in situations in which the default color
+would not contrast sufficiently with the background color.
+
+The following example includes strong focus indicator styles in an application alongside the rest of
+the custom theme API.
+
+```scss
+@use '~@angular/material' as mat;
+
+@include mat.core();
+@include mat.strong-focus-indicators();
+
+$my-primary: mat.define-palette(mat.$indigo-palette, 500);
+$my-accent: mat.define-palette(mat.$pink-palette, A200, A100, A400);
+
+$my-theme: mat.define-light-theme((
+ color: (
+   primary: $my-primary,
+   accent: $my-accent,
+ )
+));
+
+@include mat.all-component-themes($my-theme);
+@include mat.strong-focus-indicators-theme($my-theme);
+```
+
+### Customizing strong focus indicators
+
+You can pass a configuration map to `strong-focus-indicators` to customize the appearance of the
+indicators. This configuration includes `border-style`, `border-width`, and `border-radius`.
+
+You also can customize the color of indicators with `strong-focus-indicators-theme`. This mixin
+accepts either a theme, as described earlier in this guide, or a CSS color value. When providing a
+theme, the indicators will use the default hue of the primary palette.
+
+The following example includes strong focus indicator styles with custom settings alongside the rest
+of the custom theme API.
+
+```scss
+@use '~@angular/material' as mat;
+
+@include mat.core();
+@include mat.strong-focus-indicators((
+  border-style: dotted,
+  border-width: 4px,
+  border-radius: 2px,
+));
+
+$my-primary: mat.define-palette(mat.$indigo-palette, 500);
+$my-accent: mat.define-palette(mat.$pink-palette, A200, A100, A400);
+
+$my-theme: mat.define-light-theme((
+ color: (
+   primary: $my-primary,
+   accent: $my-accent,
+ )
+));
+
+@include mat.all-component-themes($my-theme);
+@include mat.strong-focus-indicators-theme(purple);
+```
+
+[WCAG]: https://www.w3.org/WAI/standards-guidelines/wcag/glance/
+
 ## Theming and style encapsulation
 
 Angular Material assumes that, by default, all theme styles are loaded as global CSS. If you want