From 913ef779187807018ea0d017efc3fde8fd418ffc Mon Sep 17 00:00:00 2001
From: Ayesha Mazumdar <a.mazumdar@salesforce.com>
Date: Tue, 9 Jan 2018 11:33:43 -0800
Subject: [PATCH] fix(general-doc-fixes): Fix typos and duplicate docs (#2998)

* fix(general-doc-fixes): Fix typos and duplicate docs

* fix(menus): fix order of docs

* fix(menus): Fix a11y docs

* fix(release-notes): Update date
---
 RELEASENOTES.md                              |   4 +-
 ui/components/icons/_doc.scss                |   4 +-
 ui/components/menus/docs.mdx                 | 112 ++++++++++---------
 ui/components/notifications/_doc.scss        |   2 +-
 ui/components/path/_doc.scss                 |   1 +
 ui/components/pills/base/_index.scss         |  16 ---
 ui/components/progress-ring/base/_index.scss |   2 -
 ui/components/prompt/_doc.scss               |   4 +-
 ui/components/spinners/base/_index.scss      |   2 -
 ui/components/timepicker/_doc.scss           |   2 +-
 ui/components/timepicker/base/_index.scss    |   3 -
 11 files changed, 68 insertions(+), 84 deletions(-)

diff --git a/RELEASENOTES.md b/RELEASENOTES.md
index 5bc873bdbf..17cd8fab01 100644
--- a/RELEASENOTES.md
+++ b/RELEASENOTES.md
@@ -3,12 +3,12 @@
 <!-- Release notes authoring guidelines: http://keepachangelog.com/ -->
 
 <!-- ## [Unreleased] -->
-## **Release [2.5.0] - January 8, 2018**
+## **Release [2.5.0] - January 9, 2018**
 
 ## Features
 
 **General Notes**
-- Updated Color guidelines to include Gray palette and Branding tokens
+- Updated Color guidelines to include Gray palette and Brand Colors
 - Introduced a new documentation style for Badges, Brand Band, Carousel, Chat, Menus, and the Grid utility.
 
 ### The following components have been updated:
diff --git a/ui/components/icons/_doc.scss b/ui/components/icons/_doc.scss
index e305f413d2..e1580c7472 100644
--- a/ui/components/icons/_doc.scss
+++ b/ui/components/icons/_doc.scss
@@ -23,12 +23,12 @@
  * included in the `use` attribute with the underscore separator as shown on
  * the icon page. For example: log_a_call.
  *
- * <h3 class="site-text-heading--label">Changing the background of an icon</h3>
+ * ##### Changing the background of an icon
  *
  * Change a background color using composed class names:
  *
  * ```css
- * .slds-icon-[sprite name]-[icon name] {}
+ * .slds-icon-[sprite name]-[icon name]
  * ```
  *
  * Place the class on the `.slds-icon_container`.
diff --git a/ui/components/menus/docs.mdx b/ui/components/menus/docs.mdx
index 3badfa5ca6..f69f16b42e 100644
--- a/ui/components/menus/docs.mdx
+++ b/ui/components/menus/docs.mdx
@@ -20,49 +20,13 @@ The unordered menu list `<ul>` with `[role="menu"]` should be contained in a `<d
 
 The target HTML element and dropdown need to be wrapped in the class `.slds-dropdown-trigger dropdown-trigger_click`.
 
-## Positioning
-
-There are 3 options for the positioning of the menu dropdown -- left, right, and bottom. To access these options, add a modifier to the `<div>` with class name `slds-dropdown`. For the standard positioning where the dropdown aligns with the left side of the dropdown trigger, use `slds-dropdown_left`, as seen above.
-
-<CodeBlock toggleCode={false}>
-  <div className="slds-dropdown slds-dropdown_left">...</div>
-</CodeBlock>
-
-### Positioned Right
-
-To position the dropdown to align with the right of the dropdown trigger, use `slds-dropdown_right`.
-
-<Example title="poistioned right">
-  <CodeView style={{height: '200px', marginLeft: '90px'}}>
-    <BaseMenu className="slds-dropdown_right" />
-  </CodeView>
-</Example>
-
-### Positioned Bottom
-
-To position the dropdown to sit on top of the dropdown trigger, use `slds-dropdown_bottom`.
-
-<Example title="positioned bottom">
-  <CodeView style={{marginLeft: '45px', marginTop: '163px'}}>
-      <BaseMenu className="slds-dropdown_bottom" />
-  </CodeView>
-</Example>
-
-## Width
-
-To adjust the width of the menu dropdown add modifier `slds-dropdown_*` to the `<div>` with class `slds-dropdown` where the `*` is `xx-small`, `x-small`, `small`, `medium`, or `large`.
-
-<CodeBlock toggleCode={false}>
-  <div className="slds-dropdown slds-dropdown_left slds-dropdown_medium">...</div>
-</CodeBlock>
-
-| Modifier | Example |
-|---|---|
-| `.slds-dropdown_xx-small` <br/> 6rem / 96px | <div style={{height: '200px', width: '320px'}}><BaseMenu className="slds-dropdown_left slds-dropdown_xx-small" /></div> |
-| `.slds-dropdown_x-small` <br/> 12rem / 192px | <div style={{height: '200px', width: '320px'}}><BaseMenu className="slds-dropdown_left slds-dropdown_x-small" /></div> |
-| `.slds-dropdown_small` <br/> 15rem / 240px | <div style={{height: '200px', width: '320px'}}><BaseMenu className="slds-dropdown_left slds-dropdown_small" /></div> |
-| `.slds-dropdown_medium` <br/> 20rem / 320px | <div style={{height: '200px', width: '320px'}}><BaseMenu className="slds-dropdown_left slds-dropdown_medium" /></div> |
-| `.slds-dropdown_large` <br/> 25rem / 400px | <div style={{height: '200px', width: '320px'}}><BaseMenu className="slds-dropdown_left slds-dropdown_large" /></div> |
+## Expected keyboard interactions
+- Arrow keys cycle focus through menu items (you should use JavaScript to disable focus for any disabled items)
+- If a menu item opens a submenu, pressing Enter or the right arrow key opens the submenu and focus goes to the first item in the submenu
+- If a submenu is open, pressing the left arrow key or Esc key closes the submenu and puts focus back on the menu item that opened the submenu
+- Tab key closes the menu and moves focus to the next focusable element on the page
+- Esc key closes the menu and moves focus back to the menu trigger
+- Any character key moves focus to the next menu item that starts with that character, if applicable
 
 ## With Subheaders
 
@@ -173,7 +137,7 @@ To force overflow scrolling after either 5, 7, or 10 items with icons, add the m
 To create a menu with a submenu, add the `slds-has-submenu` class to the list item, `<li>`, that will open the submenu.
 
 <Blockquote type="a11y" header="Accessibility Note">
-In order to open the submenu, set `aria-expanded` to `true` on the `<a>` within the `<li>` when the user clicks or hovers over the list item, or presses enter while focused on the list item.
+Any menu item that opens a submenu must have `aria-haspop="true"` on the `<a>` within the `<li>`. In order to open the submenu, set `aria-expanded` to `true` on that `<a>` when the user clicks or hovers over the list item, or presses enter while focused on the list item. Additionally, the submenu should have `role="menu"` and an `aria-label` attribute whose value matches the name of the <li> that opened the submenu.
 </Blockquote>
 
 <CodeBlock toggleCode={false}>
@@ -181,6 +145,11 @@ In order to open the submenu, set `aria-expanded` to `true` on the `<a>` within
     <a role="menuitem" href="javascript:void(0);" aria-haspopup="true" aria-expanded="true" tabindex="-1">
       ...
     </a>
+    <div class="slds-dropdown slds-dropdown_submenu slds-dropdown_submenu-left">
+      <ul class="slds-dropdown__list" role="menu" aria-label="Name of Item that Opened this Menu">
+        ...
+      </ul>
+    </div>
   </li>
 </CodeBlock>
 
@@ -214,19 +183,56 @@ For an overflow of action items, use the overflow menu with actions styling by a
   </CodeView>
 </Example>
 
+## Positioning
+
+There are 3 options for the positioning of the menu dropdown -- left, right, and bottom. To access these options, add a modifier to the `<div>` with class name `slds-dropdown`. For the standard positioning where the dropdown aligns with the left side of the dropdown trigger, use `slds-dropdown_left`, as seen above.
+
+<CodeBlock toggleCode={false}>
+  <div className="slds-dropdown slds-dropdown_left">...</div>
+</CodeBlock>
+
+### Positioned Right
+
+To position the dropdown to align with the right of the dropdown trigger, use `slds-dropdown_right`.
+
+<Example title="poistioned right">
+  <CodeView style={{height: '200px', marginLeft: '90px'}}>
+    <BaseMenu className="slds-dropdown_right" />
+  </CodeView>
+</Example>
+
+### Positioned Bottom
+
+To position the dropdown to sit on top of the dropdown trigger, use `slds-dropdown_bottom`.
+
+<Example title="positioned bottom">
+  <CodeView style={{marginLeft: '45px', marginTop: '163px'}}>
+      <BaseMenu className="slds-dropdown_bottom" />
+  </CodeView>
+</Example>
+
+## Width
+
+To adjust the width of the menu dropdown add modifier `slds-dropdown_*` to the `<div>` with class `slds-dropdown` where the `*` is `xx-small`, `x-small`, `small`, `medium`, or `large`.
+
+<CodeBlock toggleCode={false}>
+  <div className="slds-dropdown slds-dropdown_left slds-dropdown_medium">...</div>
+</CodeBlock>
+
+| Modifier | Example |
+|---|---|
+| `.slds-dropdown_xx-small` <br/> 6rem / 96px | <div style={{height: '200px', width: '320px'}}><BaseMenu className="slds-dropdown_left slds-dropdown_xx-small" /></div> |
+| `.slds-dropdown_x-small` <br/> 12rem / 192px | <div style={{height: '200px', width: '320px'}}><BaseMenu className="slds-dropdown_left slds-dropdown_x-small" /></div> |
+| `.slds-dropdown_small` <br/> 15rem / 240px | <div style={{height: '200px', width: '320px'}}><BaseMenu className="slds-dropdown_left slds-dropdown_small" /></div> |
+| `.slds-dropdown_medium` <br/> 20rem / 320px | <div style={{height: '200px', width: '320px'}}><BaseMenu className="slds-dropdown_left slds-dropdown_medium" /></div> |
+| `.slds-dropdown_large` <br/> 25rem / 400px | <div style={{height: '200px', width: '320px'}}><BaseMenu className="slds-dropdown_left slds-dropdown_large" /></div> |
+
 ## Accessibility
 
 The main thing that distinguishes menus from other popover blocks is keyboard navigation: elsewhere, users press the Tab key to navigate through actionable items, but in a menu, users press the arrow keys to navigate.
 ### Expected markup
 - Menu trigger is a focusable element (`<a>` or `<button>`) with `aria-haspopup="true"`
-- Menu has `role="menu"` and an `aria-labelledby` attribute whose value is the id of the menu trigger
+- Menu has `role="menu"` and an `aria-label` attribute whose value is the name of the menu trigger
 - Menu items have `role="menuitem"`, `role="menuitemcheckbox"`, or `role="menuitemradio"`
 - Menu items that open a submenu have both `aria-haspop="true"` and `aria-expanded` set to true or false on the `<a>` within the `<li>`, depending if the submenu is open or closed
-- Submenu has `role="menu"` and an `aria-labelledby` attribute whose value matches the name of the `<li>` that opened the submenu
-### Expected keyboard interactions
-- Arrow keys cycle focus through menu items (you should use JS to disable focus for any disabled items)
-- If a menu item opens a submenu, pressing enter or the right arrow key opens the submenu and focus goes to the first item in the submenu
-- If a submenu is open, pressing the left arrow key or Esc key closes the submenu and puts focus back on the menu item that opened the submenu
-- Tab key closes menu and moves focus to the next focusable element on the page
-- Esc key closes menu and moves focus back to the menu trigger
-- Any character key moves focus to the next menu item that starts with that character, if applicable
+- Submenu has `role="menu"` and an `aria-label` attribute whose value matches the name of the `<li>` that opened the submenu
diff --git a/ui/components/notifications/_doc.scss b/ui/components/notifications/_doc.scss
index 40fb1830d2..c86a59adc9 100644
--- a/ui/components/notifications/_doc.scss
+++ b/ui/components/notifications/_doc.scss
@@ -20,7 +20,7 @@
  * * Entity icon with background color
  * * Subject field for the reminder
  * * The time/date of when the event/task is occurring
- * * An‘X’ icon to dismiss the reminder
+ * * An ‘X’ icon to dismiss the reminder
  *
  * @base
  * @name notifications
diff --git a/ui/components/path/_doc.scss b/ui/components/path/_doc.scss
index 263c4ff675..e421bf5e27 100644
--- a/ui/components/path/_doc.scss
+++ b/ui/components/path/_doc.scss
@@ -31,6 +31,7 @@
  * - `left` and `right` arrow keys move focus _and_ selection, with `aria-selected="true"`
  *
  * **Responsive path**
+ *
  * When the Path needs to be placed in a more narrow column on desktop (between 360px and 564px) the class `.slds-region_small` should be placed on the container so it can adapt. If the container is between 565px and 1280px, the class `.slds-region_medium` should be applied.
  *
  * @summary A process component communicates to the user the progress of a particular process.
diff --git a/ui/components/pills/base/_index.scss b/ui/components/pills/base/_index.scss
index 8127f49047..760796bc4d 100644
--- a/ui/components/pills/base/_index.scss
+++ b/ui/components/pills/base/_index.scss
@@ -2,22 +2,6 @@
 // Licensed under BSD 3-Clause - see LICENSE.txt or git.io/sfdc-license
 
 /**
- * To create a pill, apply the `.slds-pill` class on a `<span>`.
- *
- * Depending on your context, you will either need a linked pill or a pill option inside of a listbox.
- *
- * For linked pills, a modifier class of `slds-pill--link` needs to be added to the existing `<span>` with the classname of `slds-pill`. You need an `<a>` inside of the span with the `slds-pill--link` class. The `<a>` will get the classname of `slds-pill__action`. This will treat the interactions differently from an unlinked pill option inside of a listbox.
- *
- * For both linked pills and unlinked pill options, a `<span>` with the classname of `slds-pill__label` should contain the string of text describing the pill object.
- *
- * Note, that a linked pill should not be used as a pill option inside of a listbox.
- *
- * Additionally, a pill can have an icon or image that sits to the left-hand side of the `.slds-pill__label`. That icon or image should receive the class `.slds-pill__icon_container`.
- *
- * You may also want the functionality to remove the pill as a selection. An "X" icon is normally used and will sit to the right-hand side of the `.slds-pill__label`. That icon should receive the class `.slds-pill__remove`.
- *
- * A `.slds-pill_container` can be used as a visual container for multiple pill(s).
- *
  * @summary Initializes pill
  *
  * @name base
diff --git a/ui/components/progress-ring/base/_index.scss b/ui/components/progress-ring/base/_index.scss
index bef7d1f922..fd265596fb 100644
--- a/ui/components/progress-ring/base/_index.scss
+++ b/ui/components/progress-ring/base/_index.scss
@@ -2,8 +2,6 @@
 // Licensed under BSD 3-Clause - see LICENSE.txt or git.io/sfdc-license
 
 /**
- * Progress Ring component
- *
  * @summary Progress Ring component
  *
  * @variant
diff --git a/ui/components/prompt/_doc.scss b/ui/components/prompt/_doc.scss
index 94ce4a2d20..9fa9c10a9a 100644
--- a/ui/components/prompt/_doc.scss
+++ b/ui/components/prompt/_doc.scss
@@ -17,10 +17,10 @@
  * - Modal has an `aria-describedby` attribute that matches the id of the modal message container.
  * - Modal message container container should have `tab-index="0"`
  *
- * **Expected keyboard interaction (sme as Modal, with the addition of):**
+ * **Expected keyboard interaction (same as Modal, with the addition of):**
  * - Modal message container should take initial focus
  *
- * @summary Prompt notice grabs the user’s attention & alert them of system-related issues/updates.
+ * @summary Prompt notice grabs the user’s attention & alerts them of system-related issues/updates.
  *
  * @base
  * @name prompt
diff --git a/ui/components/spinners/base/_index.scss b/ui/components/spinners/base/_index.scss
index 9cabbd913f..d121d80879 100644
--- a/ui/components/spinners/base/_index.scss
+++ b/ui/components/spinners/base/_index.scss
@@ -30,8 +30,6 @@
 /* stylelint-enable selector-class-pattern */
 
 /**
- * This is the gray base class for spinner
- *
  * @name base
  * @selector .slds-spinner
  * @restrict div
diff --git a/ui/components/timepicker/_doc.scss b/ui/components/timepicker/_doc.scss
index 159c65a997..8707971f31 100644
--- a/ui/components/timepicker/_doc.scss
+++ b/ui/components/timepicker/_doc.scss
@@ -4,7 +4,7 @@
 /**
  * #### Implementation Notes and Requirements
  *
- * The timepicker has the following markup requirements:
+ * A timepicker is used to select a single time. The component is using the combobox HTML structure and has the following markup requirements:
  *
  * **Desktop**
  * - Add `.slds-is-open` to the element with `.slds-dropdown-trigger` to invoke the dropdown that contains the list of time options.
diff --git a/ui/components/timepicker/base/_index.scss b/ui/components/timepicker/base/_index.scss
index eb66fda9df..dd055ce31a 100644
--- a/ui/components/timepicker/base/_index.scss
+++ b/ui/components/timepicker/base/_index.scss
@@ -2,9 +2,6 @@
 // Licensed under BSD 3-Clause - see LICENSE.txt or git.io/sfdc-license
 
 /**
- * A timepicker is used to select a single time. The component is using the combobox
- * HTML structure.
- *
  * @summary Initializes a timepicker
  *
  * @name base