From ec8bed61193a1b30287a1fa1db3440bb3065fb09 Mon Sep 17 00:00:00 2001
From: Topher Fangio <topher@profoundry.us>
Date: Thu, 22 Dec 2016 02:35:52 -0600
Subject: [PATCH] docs(chips): Update overview with more info. (#2341)

Update the Chips overview with additional information and context.

 - Add section regarding disabled chips
 - Note `(select)` and `(deselect)` outputs
 - Add hint about `<md-basic-chip>`
 - Fix a few typos
---
 src/lib/chips/OVERVIEW.md | 20 +++++++++++++++-----
 1 file changed, 15 insertions(+), 5 deletions(-)

diff --git a/src/lib/chips/OVERVIEW.md b/src/lib/chips/OVERVIEW.md
index 33caeb0c989..7159fdc9f36 100644
--- a/src/lib/chips/OVERVIEW.md
+++ b/src/lib/chips/OVERVIEW.md
@@ -1,4 +1,4 @@
-`<md-chip-list>` displays a list of values as individual chips.
+`<md-chip-list>` displays a list of values as individual, keyboard accessible, chips.
 
 <!-- example(chips-overview) -->
 
@@ -16,15 +16,25 @@ _Note: chips are still early in their development and more features are being ac
 By default, `<md-chip>` has Material Design styles applied. For a chip with no styles applied,
 use `<md-basic-chip>`. You can then customize the chip appearance by adding your own CSS.
 
+_Hint: `<md-basic-chip>` receives the `md-basic-chip` CSS class in addition to the `md-chip` class._
+
 ### Selection
 Chips can be selected via the `selected` property. Selection can be disabled by setting
-`selectable` to `false` on the `<md-chip-list>`. 
+`selectable` to `false` on the `<md-chip-list>`.
 
-### Keyboard interation
-Users can move through the chips using the arrow keys and select them with the space.
+Selection emits the `(select)` output while deselecting emits the `(deselect)` output. Both outputs
+receive a ChipEvent object with a structure of `{ chip: alteredChip }`.
+
+### Disabled chips
+Individual chips may be disabled by applying the `disabled` attribute to the chip. When disabled,
+chips are neither selectable nor focusable. Currently, disabled chips receive no special styling.
+
+### Keyboard interaction
+Users can move through the chips using the arrow keys and select/deselect them with the space. Chips
+also gain focus when clicked, ensuring keyboard navigation starts at the appropriate chip.
 
 
 ### Theming
-The color of an `<md-chip>` can be changed by using the `color` property. By default, chips
+The selected color of an `<md-chip>` can be changed by using the `color` property. By default, chips
 use a neutral background color based on the current theme (light or dark). This can be changed to 
 `'primary'`, `'accent'`, or `'warn'`.