Merge branch 'master' into refactor/notched-outline

packages/mdc-list/README.md

@@ -374,8 +374,9 @@ CSS Class | Description
 `mdc-list-item__text` |	Mandatory. Wrapper for list item text content (displayed as middle column of the list item).
 `mdc-list-item__primary-text` | Optional, primary text for the list item. Should be the child of `mdc-list-item__text`.
 `mdc-list-item__secondary-text` | Optional, secondary text for the list item. Displayed below the primary text. Should be the child of `mdc-list-item__text`.
-`mdc-list-item--selected` | Optional, styles the row in an selected* state.
-`mdc-list-item--activated` | Optional, styles the row in an activated* state.
+`mdc-list-item--disabled` | Optional, styles the row in the disabled state.
+`mdc-list-item--selected` | Optional, styles the row in the selected* state.
+`mdc-list-item--activated` | Optional, styles the row in the activated* state.
 `mdc-list-item__graphic` | Optional, the first tile in the row (in LTR languages, the first column of the list item). Typically an icon or image.
 `mdc-list-item__meta`	| Optional, the last tile in the row (in LTR languages, the last column of the list item). Typically small text, icon. or image.
 `mdc-list-group` | Optional, wrapper around two or more mdc-list elements to be grouped together.
@@ -384,14 +385,11 @@ CSS Class | Description
 `mdc-list-divider--padded` | Optional, leaves gaps on each side of divider to match padding of `list-item__meta`.
 `mdc-list-divider--inset` | Optional, increases the leading margin of the divider so that it does not intersect the avatar column.
 
-> NOTE: `mdc-list-divider` class can be used between list items (example 1) *OR* between two lists (example 2).
+> NOTE: The `mdc-list-divider` class can be used between list items *OR* between two lists (see respective examples under [List Dividers](#list-dividers)).
 
-> NOTE: the difference between selected and activated states:
-
-* *Selected* state should be implemented on the `.mdc-list-item` when it is likely to change soon. Eg., selecting one or more photos to share in Google Photos.
-* Multiple items can be selected at the same time when using the *selected* state.
-* *Activated* state is similar to selected state, however should only be implemented once within a specific list.
-* *Activated* state is more permanent than selected state, and will **NOT** change soon relative to the lifetime of the page.
+> NOTE: In Material Design, the selected and activated states apply in different, mutually-exclusive situations:
+> * *Selected* state should be applied on the `.mdc-list-item` when it is likely to frequently change due to user choice. E.g., selecting one or more photos to share in Google Photos.
+> * *Activated* state is more permanent than selected state, and will **NOT** change soon relative to the lifetime of the page. Common examples are navigation components such as the list within a navigation drawer.
 
 ### Sass Mixins
 
@@ -426,6 +424,8 @@ list. The `Arrow`, `Home`, and `End` keys should be used for navigating internal
 item. The MDCList will perform the following actions for each key press. Since list interaction will toggle a radio
 button or checkbox within the list item, the list will not toggle `tabindex` for those elements.
 
+Any disabled list items (with the `mdc-list-item--disabled` class applied) will be excluded from keyboard navigation.
+
 Key | Action
 --- | ---
 `ArrowUp` | When the list is in a vertical orientation, it will cause the previous list item to receive focus.

packages/mdc-menu/README.md

@@ -106,6 +106,11 @@ Menus can contain a group of list items that can represent the selection state o
 </div>
 ```
 
+### Disabled Menu Items
+
+Menu items can be disabled by adding the `mdc-list-item--disabled` modifier class (from [MDC List](../mdc-list)).
+Disabled menu items will be excluded from keyboard navigation.
+
 ### Anchors and Positioning
 
 #### Anchored To Parent