docs(focus indicators): Add documentation for focus indicators.

guides/theming.md

@@ -251,3 +251,34 @@ function changeTheme(themeName) {
 ### Theming your own components
 For more details about theming your own components,
 see [theming-your-components.md](./theming-your-components.md).
+
+### Showing strong focus indicators
+Angular Material has built-in support for showing **strong focus indicators** on all components.
+These focus indicators render as highly visible outlines around elements.
+
+<!-- example(focus-indicators-overview) -->
+
+Strong focus indicators are off by default. To turn them on, include these mixins:
+
+```scss
+@import '@angular/material/core/focus-indicator/focus-indicator';
+
+// Including this mixin will enable strong focus indicators for your app.
+// This mixin should only be included once in your app.
+@include mat-strong-focus-indicators();
+
+// Choose a color for the focus indicators.
+$color: mat-color(mat-palette($mat-deep-purple));
+
+// Including this mixin will theme the focus indicators.
+// This mixin can be included multiple times throughout your app
+// to change the focus indicator's color.
+@include mat-strong-focus-indicators-theme($color);
+```
+
+You can also use the class `.mat-focus-indicator` to add focus indicators to your own components.
+
+```html
+<!-- Adding a focus indicator to a custom, non-Material button. -->
+<div role="button" tabindex="0" class="mat-focus-indicator">My custom button</div>
+```

src/components-examples/material/core/focus-indicators-overview/focus-indicators-overview-example.html

@@ -0,0 +1 @@
+<button mat-button>Click me</button>

src/components-examples/material/core/focus-indicators-overview/focus-indicators-overview-example.scss

@@ -0,0 +1,13 @@
+@import '../material/core/focus-indicator/focus-indicator';
+
+// Including this mixin will enable strong focus indicators for your app.
+// This mixin should only be included once in your app.
+@include mat-strong-focus-indicators();
+
+// Choose a color for the focus indicators.
+$color: mat-color(mat-palette($mat-deep-purple));
+
+// Including this mixin will theme the focus indicators.
+// This mixin can be included multiple times throughout your app
+// to change the focus indicator's color.
+@include mat-strong-focus-indicators-theme($color);

src/components-examples/material/core/focus-indicators-overview/focus-indicators-overview-example.ts

@@ -0,0 +1,12 @@
+import {Component} from '@angular/core';
+
+/**
+ * @title Focus indicators overview.
+ */
+@Component({
+  selector: 'focus-indicators-overview-example',
+  styleUrls: ['focus-indicators-overview-example.css'],
+  templateUrl: 'focus-indicators-overview-example.html',
+})
+export class FocusIndicatorsOverviewExample {
+}

src/components-examples/material/core/index.ts

@@ -5,15 +5,18 @@ import {MatCheckboxModule} from '@angular/material/checkbox';
 import {MatRippleModule} from '@angular/material/core';
 import {MatInputModule} from '@angular/material/input';
 import {ElevationOverviewExample} from './elevation-overview/elevation-overview-example';
+import {FocusIndicatorsOverviewExample} from './focus-indicators-overview/focus-indicators-overview-example';
 import {RippleOverviewExample} from './ripple-overview/ripple-overview-example';
 
 export {
   ElevationOverviewExample,
+  FocusIndicatorsOverviewExample,
   RippleOverviewExample,
 };
 
 const EXAMPLES = [
   ElevationOverviewExample,
+  FocusIndicatorsOverviewExample,
   RippleOverviewExample,
 ];