docs(icons): Add more documentation and examples

config/styleguide.config.js

@@ -235,6 +235,7 @@ module.exports = {
         },
         {
           name: 'Icons',
+          content: path.resolve('src/components/Icons/icons.md'),
           components() {
             return compact([
               toggleByEnv('Icon', path.resolve('src/components/Icons/DecorativeIcon/DecorativeIcon.jsx')),

src/components/Icons/DecorativeIcon/DecorativeIcon.jsx

@@ -4,7 +4,7 @@ import PropTypes from 'prop-types'
 import Icon from '../Icon/Icon'
 
 /**
- * An icon that is used just for visual aesthetics.
+ * An icon used for visual aesthetics only.
  *
  * <span class="docs--badge__wip">wip</span>
  */

src/components/Icons/DecorativeIcon/DecorativeIcon.md

@@ -1,43 +1 @@
-### Available Icons
-
-```
-<div className="docs--horizontal-spacing">
-  <DecorativeIcon symbol="caretDown" />
-  <DecorativeIcon symbol="caretUp" />
-  <DecorativeIcon symbol="checkmark" />
-  <DecorativeIcon symbol="leftChevron" />
-  <DecorativeIcon symbol="chevron" />
-  <DecorativeIcon symbol="exclamationPointCircle" />
-  <DecorativeIcon symbol="expander" />
-  <DecorativeIcon symbol="hamburger" />
-  <DecorativeIcon symbol="location" />
-  <DecorativeIcon symbol="minus" />
-  <DecorativeIcon symbol="plus" />
-  <DecorativeIcon symbol="questionMarkCircle" />
-  <DecorativeIcon symbol="spyglass" />
-  <DecorativeIcon symbol="times" />
-</div>
-```
-
-### Modifying color
-
-Use the `variant` prop to alter the icon's color. Each variant has semantic meaning.
-
-```
-<div className="docs--horizontal-spacing">
-  <DecorativeIcon symbol="checkmark" variant="primary" />
-  <DecorativeIcon symbol="incomplete" variant="secondary" />
-  <DecorativeIcon symbol="exclamationPointCircle" variant="error" />
-</div>
-```
-
-### Adjusting size
-
-Use the `size` prop to adjust the icon's size.
-
-```
-<div className="docs--horizontal-spacing">
-  <DecorativeIcon symbol="chevron" variant="primary" size={16} />
-  <DecorativeIcon symbol="exclamationPointCircle" variant="error" size={24} />
-</div>
-```
+Decorative icons do not perform a role beyond visual aesthetics and are hidden from screen readers using the aria-hidden attribute. Usually, the information being communicated with the icon is also conveyed in another manner.

src/components/Icons/Icon/Icon.modules.scss

@@ -100,14 +100,6 @@
   }
 }
 
-.iconIncomplete {
-  composes: icon;
-
-  &::before {
-    content: "\f104";
-  }
-}
-
 .iconLocation {
   composes: icon;
 

src/components/Icons/StandaloneIcon/StandaloneIcon.md

@@ -1,20 +1,13 @@
-### Available Icons
+### Making interactive icons
+
+Standalone icons can also be interactive elements. This example shows the preferred way of creating an interactive icon:
 
 ```
-<div className="docs--horizontal-spacing">
-  <StandaloneIcon symbol="caretDown" a11yText="text" />
-  <StandaloneIcon symbol="caretUp" a11yText="text" />
-  <StandaloneIcon symbol="checkmark" a11yText="text" />
-  <StandaloneIcon symbol="leftChevron" a11yText="text" />
-  <StandaloneIcon symbol="chevron" a11yText="text" />
-  <StandaloneIcon symbol="exclamationPointCircle" a11yText="text" />
-  <StandaloneIcon symbol="expander" a11yText="text" />
-  <StandaloneIcon symbol="hamburger" a11yText="text" />
-  <StandaloneIcon symbol="location" a11yText="text" />
-  <StandaloneIcon symbol="minus" a11yText="text" />
-  <StandaloneIcon symbol="plus" a11yText="text" />
-  <StandaloneIcon symbol="questionMarkCircle" a11yText="text" />
-  <StandaloneIcon symbol="spyglass" a11yText="text" />
-  <StandaloneIcon symbol="times" a11yText="text" />
-</div>
+<button
+  style={{appearance: 'none', background: 'none', border: 0, cursor: 'pointer'}}
+  type="submit">
+    <StandaloneIcon symbol="spyglass" size={48} a11yText="Search this site." />
+</button>
 ```
+
+This will be added as a built in feature in the future, until then follow the above example.

src/components/Icons/icons.md

@@ -0,0 +1,43 @@
+### Available Icons
+
+```
+<div className="docs--horizontal-spacing">
+  <DecorativeIcon symbol="caretDown" />
+  <DecorativeIcon symbol="caretUp" />
+  <DecorativeIcon symbol="checkmark" />
+  <DecorativeIcon symbol="leftChevron" />
+  <DecorativeIcon symbol="chevron" />
+  <DecorativeIcon symbol="exclamationPointCircle" />
+  <DecorativeIcon symbol="expander" />
+  <DecorativeIcon symbol="hamburger" />
+  <DecorativeIcon symbol="location" />
+  <DecorativeIcon symbol="minus" />
+  <DecorativeIcon symbol="plus" />
+  <DecorativeIcon symbol="questionMarkCircle" />
+  <DecorativeIcon symbol="spyglass" />
+  <DecorativeIcon symbol="times" />
+</div>
+```
+
+### Modifying colour
+
+Use the `variant` prop to alter the icon's colour. Each variant has semantic meaning.
+
+```
+<div className="docs--horizontal-spacing">
+  <DecorativeIcon symbol="checkmark" variant="primary" />
+  <DecorativeIcon symbol="times" variant="secondary" />
+  <DecorativeIcon symbol="exclamationPointCircle" variant="error" />
+</div>
+```
+
+### Adjusting size
+
+Use the `size` prop to adjust the icon's size.
+
+```
+<div className="docs--horizontal-spacing">
+  <DecorativeIcon symbol="exclamationPointCircle" size={16} />
+  <DecorativeIcon symbol="exclamationPointCircle" size={24} />
+</div>
+```