feat(Icon): New dimmed prop to lighten icons

src/Icon/README.mdx

@@ -5,6 +5,7 @@ menu: Components
 
 import {Playground, Props} from 'docz';
 import Icon from './';
+import Text from '../Text';
 import DiskIcon from '../icons/Disk';
 import PlusIcon from '../icons/Plus';
 import SearchIcon from '../icons/Search';
@@ -22,7 +23,10 @@ Using the `<Icon />` wrapper component allows you to dynamically display icons b
 <Playground>
 	<Icon name="disk" />
 	<Icon name="plus" />
-	<Icon name="search" />
+	<Text as="div" size="xxl">
+		<Icon name="search" />
+		<Icon name="search" scale={0} />
+	</Text>
 </Playground>
 
 ## Using individual icons
@@ -51,11 +55,11 @@ The following props are available on both the individual icon components as well
 
 ## Aligning icons with text
 
-When placed next to or inside of text, icons tend to sit a bit too low compared to the text's baseline. Use the Boolean `vAlign` prop to nudge the icon up by a few pixels to visually align it with its surrounding text.
+When placed next to or inside of text, icons tend to sit a bit too low compared to the text's baseline. They also often look darker than text, even if they "technically" have the same colour. The props `vAlign` and `dimmed` exist to compensate for these issues. Use the Boolean `vAlign` prop to nudge the icon up by a few pixels to visually align it with its surrounding text. Use `dimmed` to make the icon slightly transparent to match the text's appearance.
 
 <Playground>
-	<PlusIcon /> Without vAlign
+	<PlusIcon /> Without vAlign and undimmed
 	<br />
 	<br />
-	<PlusIcon vAlign /> With vAlign
+	<PlusIcon vAlign dimmed /> With vAlign and dimmed
 </Playground>

src/Icon/index.js

@@ -46,6 +46,12 @@ Icon.defaultProps = {
 };
 
 Icon.propTypes = {
+	/**
+	 * Set the opacity of the icon to the value specified
+	 * as the theme's `textDimStrength`. Useful when an icon's colour
+	 * looks too strong compared to surrounding text
+	 */
+	dimmed: PropTypes.string,
 	/**
 	 * Display the icon in any valid CSS color. By default, icons
 	 * use the colour of their containing element (`currentColor`).

src/icons/BaseSvg.js

@@ -1,5 +1,5 @@
 import PropTypes from 'prop-types';
-import styled, {css} from 'styled-components';
+import styled from 'styled-components';
 
 import {pxToRem, pxToEm} from '../utils/units';
 
@@ -18,12 +18,12 @@ const Svg = styled.svg.attrs({
 
 	${p =>
 		p.spacingLeft &&
-		css`
+		`
 			margin-left: ${p.spacingLeft};
 		`}
 	${p =>
 		p.spacingRight &&
-		css`
+		`
 			margin-right: ${p.spacingRight};
 		`}
 
@@ -32,18 +32,25 @@ const Svg = styled.svg.attrs({
 
 	${p =>
 		p.vAlign &&
-		css`
+		`
 			/* Use to align icons with surrounding body text */
 			position: relative;
 			top: -0.12em;
 		`}
+
+	${p =>
+		p.dimmed &&
+		`
+			opacity: ${p.theme.textDimStrength};
+		`}
 `;
 
 Svg.defaultProps = {
 	scale: 1,
 };
 
 Svg.propTypes = {
+	dimmed: PropTypes.bool,
 	scale: PropTypes.number,
 	vAlign: PropTypes.bool,
 	spacingLeft: PropTypes.oneOfType([PropTypes.string, PropTypes.func]),