docs(form-field): add docs for appearance and mention that color type is supported (#10274)

* docs(form-field): add docs for `appearance`

* add color to supported input types

Author: mmalerba

src/lib/form-field/form-field.md

@@ -13,6 +13,31 @@ The following Angular Material components are designed to work inside a `<mat-fo
 
 <!-- example(form-field-overview) -->
 
+### Form field appearance variants
+The `mat-form-field` supports 4 different appearance variants which can be set via the `appearance`
+input. The `legacy` appearance is the default style that the `mat-form-field` has traditionally had.
+It shows the input box with an underline underneath it. The `standard` appearance is a slightly
+updated version of the `legacy` appearance that has spacing that is more consistent with the `fill`
+and `outline` appearances. The `fill` appearance displays the form field with a filled background
+box in addition to the underline. Finally the `outline` appearance shows the form field with a
+border all the way around, not just an underline.
+
+There are a couple differences to be aware of between the `legacy` appearance and the newer
+`standard`, `fill`, and `outline` appearances. The `matPrefix` and `matSuffix` elements are center
+aligned by default for the newer appearances. The Material Design spec shows this as being the
+standard way to align prefix and suffix icons in the newer appearance variants. We do not recommend
+using text prefix and suffixes in the new variants because the label and input do not have the same
+alignment. It is therefore impossible to align the prefix or suffix in a way that looks good when
+compared with both the label and input text.
+
+The second important difference is that the `standard`, `fill`, and `outline` appearances do not
+promote placeholders to labels. For the `legacy` appearance specifying
+`<input placeholder="placeholder">` will result in a floating label being added to the
+`mat-form-field`. For the newer variants it will just add a normal placeholder to the input. If you
+want a floating label, add a `<mat-label>` to the `mat-form-filed`.
+
+<!-- example(form-field-appearance) -->
+
 ### Floating label
 
 The floating label is a text label displayed on top of the form field control when

src/lib/input/input.md

@@ -17,6 +17,7 @@ also contains an `<mat-placeholder>` element.
 
 The following [input types](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input) can
 be used with `matInput`:
+* color
 * date
 * datetime-local
 * email

src/material-examples/form-field-appearance/form-field-appearance-example.css

@@ -0,0 +1 @@
+/** No CSS for this example */

src/material-examples/form-field-appearance/form-field-appearance-example.html

@@ -0,0 +1,32 @@
+<p>
+  <mat-form-field appearance="legacy">
+    <mat-label>Legacy form field</mat-label>
+    <input matInput placeholder="Placeholder">
+    <mat-icon matSuffix>sentiment_very_satisfied</mat-icon>
+    <mat-hint>Hint</mat-hint>
+  </mat-form-field>
+</p>
+<p>
+  <mat-form-field appearance="standard">
+    <mat-label>Standard form field</mat-label>
+    <input matInput placeholder="Placeholder">
+    <mat-icon matSuffix>sentiment_very_satisfied</mat-icon>
+    <mat-hint>Hint</mat-hint>
+  </mat-form-field>
+</p>
+<p>
+  <mat-form-field appearance="fill">
+    <mat-label>Fill form field</mat-label>
+    <input matInput placeholder="Placeholder">
+    <mat-icon matSuffix>sentiment_very_satisfied</mat-icon>
+    <mat-hint>Hint</mat-hint>
+  </mat-form-field>
+</p>
+<p>
+  <mat-form-field appearance="outline">
+    <mat-label>Outline form field</mat-label>
+    <input matInput placeholder="Placeholder">
+    <mat-icon matSuffix>sentiment_very_satisfied</mat-icon>
+    <mat-hint>Hint</mat-hint>
+  </mat-form-field>
+</p>

src/material-examples/form-field-appearance/form-field-appearance-example.ts

@@ -0,0 +1,9 @@
+import {Component} from '@angular/core';
+
+/** @title Form field appearance variants */
+@Component({
+  selector: 'form-field-appearance-example',
+  templateUrl: 'form-field-appearance-example.html',
+  styleUrls: ['form-field-appearance-example.css']
+})
+export class FormFieldAppearanceExample {}