docs: add best practices doc on icons (#238)

Matt Goo · web-flow · commit ab19eca8d04a · 2018-08-24T14:34:55.000-07:00
diff --git a/docs/best-practices.md b/docs/best-practices.md
@@ -0,0 +1,16 @@
+## Importing Font Icons
+
+If you need to import font icons to your app, the best way is to include it as a `<link>` tag in the head of your document. For example if you're using Material Icons you would add this to your `<head>`:
+
+```html
+<link href="https://fonts.googleapis.com/icon?family=Material+Icons"
+  rel="stylesheet">
+```
+
+Further details documented on [Material Icons docs ](https://google.github.io/material-design-icons/#icon-font-for-the-web).
+
+By not including the font icon inside your CSS file, it reduces the file size. By reducing CSS file size, you decrease the time to initial load since CSS files are render blocking. This does present some drawbacks -- the main issue being FOUC (Flash of unstyled content). Your users will not see the actual icons until the font icon file loads.
+
+### Use with MDC Ripple
+
+If you load your font icons with a [Ripple](../packages/ripple) with the above method, you will need to set the height and width of the icons. This is because MDC Ripple calculates the ripple size from the initial height/width.
diff --git a/packages/button/README.md b/packages/button/README.md
@@ -57,3 +57,7 @@ Sass mixins may be available to customize various aspects of the Components. Ple
 MDC Web repository for more information on what mixins are available, and how to use them.
 
 [Advanced Sass Mixins](https://github.com/material-components/material-components-web/blob/master/packages/mdc-button/README.md#sass-mixins)
+
+## Usage with Icons
+
+Please see our [Best Practices doc](../../docs/best-practices.md#importing-font-icons) when importing or using icon fonts.
diff --git a/packages/card/README.md b/packages/card/README.md
@@ -165,3 +165,7 @@ Sass mixins may be available to customize various aspects of the Components. Ple
 MDC Web repository for more information on what mixins are available, and how to use them.
 
 [Advanced Sass Mixins](https://github.com/material-components/material-components-web/blob/master/packages/mdc-card/README.md#sass-mixins)
+
+## Usage with Icons
+
+Please see our [Best Practices doc](../../docs/best-practices.md#importing-font-icons) when importing or using icon fonts.
diff --git a/packages/fab/README.md b/packages/fab/README.md
@@ -57,3 +57,7 @@ Sass mixins may be available to customize various aspects of the components. Ple
 MDC Web repository for more information on what mixins are available, and how to use them.
 
 [Advanced Sass Mixins](https://github.com/material-components/material-components-web/blob/master/packages/mdc-fab/README.md#advanced-sass-mixins)
+
+## Usage with Icons
+
+Please see our [Best Practices doc](../../docs/best-practices.md#importing-font-icons) when importing or using icon fonts.
diff --git a/packages/material-icon/README.md b/packages/material-icon/README.md
@@ -55,3 +55,7 @@ Prop Name | Type | Description
 icon | string | Type of icon to be displayed.
 className | string | Classes to pass on to the root `<i>` element.
 hasRipple | n/a | If present on element, it will enable the ripple on the icon.
+
+## Usage with Icons
+
+Please see our [Best Practices doc](../../docs/best-practices.md#importing-font-icons) for further reading.
diff --git a/packages/tab-indicator/README.md b/packages/tab-indicator/README.md
@@ -88,3 +88,7 @@ Sass mixins may be available to customize various aspects of the components. Ple
 MDC Web repository for more information on what mixins are available, and how to use them.
 
 [Advanced Sass Mixins](https://github.com/material-components/material-components-web/blob/master/packages/mdc-tab-indicator/README.md#sass-mixins)
+
+## Usage with Icons
+
+Please see our [Best Practices doc](../../docs/best-practices.md#importing-font-icons) when importing or using icon fonts.
diff --git a/packages/tab/README.md b/packages/tab/README.md
@@ -90,3 +90,7 @@ Sass mixins may be available to customize various aspects of the components. Ple
 MDC Web repository for more information on what mixins are available, and how to use them.
 
 [Advanced Sass Mixins](https://github.com/material-components/material-components-web/blob/master/packages/mdc-tab/README.md#sass-mixins)
+
+## Usage with Icons
+
+Please see our [Best Practices doc](../../docs/best-practices.md#importing-font-icons) when importing or using icon fonts.
diff --git a/packages/text-field/README.md b/packages/text-field/README.md
@@ -113,3 +113,7 @@ Sass mixins may be available to customize various aspects of the Components. Ple
 MDC Web repository for more information on what mixins are available, and how to use them.
 
 [Advanced Sass Mixins](https://github.com/material-components/material-components-web/blob/master/packages/mdc-textfield/README.md)
+
+## Usage with Icons
+
+Please see our [Best Practices doc](../../docs/best-practices.md#importing-font-icons) when importing or using icon fonts.
diff --git a/packages/top-app-bar/README.md b/packages/top-app-bar/README.md
@@ -92,3 +92,7 @@ Sass mixins may be available to customize various aspects of the Components. Ple
 MDC Web repository for more information on what mixins are available, and how to use them.
 
 [Advanced Sass Mixins](https://github.com/material-components/material-components-web/blob/master/packages/mdc-top-app-bar/README.md#sass-mixins)
+
+## Usage with Icons
+
+Please see our [Best Practices doc](../../docs/best-practices.md#importing-font-icons) when importing or using icon fonts.
