updates Dropdown documentation, adds Figma addon for illustrations (#554)

Author: jasonbasuil

package.json

@@ -117,6 +117,7 @@
     "react-test-renderer": "^16.12.0",
     "react-tracking": "8.1.0",
     "sass-loader": "^8.0.2",
+    "storybook-addon-designs": "^6.2.1",
     "style-loader": "^1.1.3",
     "styled-components": "^5.3.3"
   },

src/Dropdown/Dropdown.mdx

@@ -1,26 +1,26 @@
 import { ArgsTable, Story, Canvas } from '@storybook/addon-docs/blocks';
+import { Figma } from "storybook-addon-designs/blocks"
 import Dropdown from './Dropdown';
 
 # Dropdown
 
 ##
 
 <h4>
-  Dropdowns are toggleable, contextual overlays for displaying lists of links and more. 
-  Dropdowns are built using a third-party library Popper.js, which provides dynamic positioning and viewport detection.
+  A Dropdown displays a list of actions or selectable options that a user can take.
+  Typically contained within a button, an action is initiated based on the selection.
 </h4>
 
 <Canvas>
   <Story id="components-dropdown--default" />
 </Canvas>
 
-### When to use 
-- Reason 1
-- Reason 2
 
 ### When to not use
-- Reason 1
-- Reason 2
+Avoid the Dropdown component if:
+
+- Users can select one or many from the options
+- There are more than 15 options
 
 ## Props
 
@@ -52,23 +52,40 @@ import Dropdown from './Dropdown';
 
 ## Formatting
 
-### States
-
 ### Anatomy 
 - **Toggle: ** A button to open the dropdown menu.
 
 
-### Sizing
+## Best practices
 
-### Alignment
+### General
+The Dropdown component should:
 
+- Be used for secondary actions or information
+- Contain actions or options that are related to each other
+- Be used when the action need not be frequently taken
+- Display actions as disabled when they can only be used sometimes (instead of removing them)
 
-## Best practices
+### UX Copy
 
-### General
+The labels should:
 
-### Behavior
+- Be clear and predictable.
+- Lead with a strong verb that encourages action.
+    - To provide enough context, use {verb} + {noun} format unless the action is clear with a single verb
+- Be concise.
 
-### Implementation
+### To Label, or Not To Label
+
+Use a label if:
+
+- The label needs to be displayed at all times
+- The action(s) taken is more frequent
+
+Use the icon if:
+
+- Space is an issue
+- It is already placed within context (i.e. at the end of a `Card`)
+
+<Figma url="https://www.figma.com/file/471iS3QrpPtXZpS1xbsJ20/Components?node-id=8699%3A42280" />
 
-### UX Copy

yarn.lock

@@ -1540,6 +1540,22 @@
   resolved "https://registry.yarnpkg.com/@emotion/weak-memoize/-/weak-memoize-0.2.5.tgz#8eed982e2ee6f7f4e44c253e12962980791efd46"
   integrity sha512-6U71C2Wp7r5XtFtQzYrW5iKFT67OixrSxjI4MptCHzdSVlgabczzqLe0ZSgnub/5Kp4hSbpDB1tMytZY9pwxxA==
 
+"@figspec/components@^1.0.0":
+  version "1.0.0"
+  resolved "https://registry.yarnpkg.com/@figspec/components/-/components-1.0.0.tgz#b1ddf0593173157cb5e79e50073ca1491bb7c6dc"
+  integrity sha512-a8sgP0YLJ3H0g0pdZPYecxfp9JNVQUTaaU3xcSci8duHXTGkJ7X8QPPCBbyhB+MoxMxnsAh8GjkfZHEr9oIoPQ==
+  dependencies:
+    copy-to-clipboard "^3.0.0"
+    lit-element "^2.4.0"
+    lit-html "^1.1.1"
+
+"@figspec/react@^1.0.0":
+  version "1.0.0"
+  resolved "https://registry.yarnpkg.com/@figspec/react/-/react-1.0.0.tgz#226ff85e146038b284ddf1ddbc086d2d14fe370a"
+  integrity sha512-BkOu3RsKF5vCtPoqsc6Oeyxw4wr9GesFrB9/wDHFqgjzhWsw8erFxCsPxsjdlJD8d8OWVHoM6SWxAaGe/pLdxg==
+  dependencies:
+    "@figspec/components" "^1.0.0"
+
 "@fortawesome/fontawesome-common-types@^0.2.35":
   version "0.2.35"
   resolved "https://registry.yarnpkg.com/@fortawesome/fontawesome-common-types/-/fontawesome-common-types-0.2.35.tgz#01dd3d054da07a00b764d78748df20daf2b317e9"
@@ -5308,7 +5324,7 @@ copy-descriptor@^0.1.0:
   resolved "https://registry.yarnpkg.com/copy-descriptor/-/copy-descriptor-0.1.1.tgz#676f6eb3c39997c2ee1ac3a924fd6124748f578d"
   integrity sha1-Z29us8OZl8LuGsOpJP1hJHSPV40=
 
-copy-to-clipboard@^3, copy-to-clipboard@^3.3.1:
+copy-to-clipboard@^3, copy-to-clipboard@^3.0.0, copy-to-clipboard@^3.3.1:
   version "3.3.1"
   resolved "https://registry.yarnpkg.com/copy-to-clipboard/-/copy-to-clipboard-3.3.1.tgz#115aa1a9998ffab6196f93076ad6da3b913662ae"
   integrity sha512-i13qo6kIHTTpCm8/Wup+0b1mVWETvu2kIMzKoK8FpkLkFxlt0znUAHcMzox+T8sPlqtZXq3CulEjQHsYiGFJUw==
@@ -9474,6 +9490,18 @@ listr2@^3.8.3:
     through "^2.3.8"
     wrap-ansi "^7.0.0"
 
+lit-element@^2.4.0:
+  version "2.5.1"
+  resolved "https://registry.yarnpkg.com/lit-element/-/lit-element-2.5.1.tgz#3fa74b121a6cd22902409ae3859b7847d01aa6b6"
+  integrity sha512-ogu7PiJTA33bEK0xGu1dmaX5vhcRjBXCFexPja0e7P7jqLhTpNKYRPmE+GmiCaRVAbiQKGkUgkh/i6+bh++dPQ==
+  dependencies:
+    lit-html "^1.1.1"
+
+lit-html@^1.1.1:
+  version "1.4.1"
+  resolved "https://registry.yarnpkg.com/lit-html/-/lit-html-1.4.1.tgz#0c6f3ee4ad4eb610a49831787f0478ad8e9ae5e0"
+  integrity sha512-B9btcSgPYb1q4oSOb/PrOT6Z/H+r6xuNzfH4lFli/AWhYwdtrgQkQWBbIc6mdnf6E2IL3gDXdkkqNktpU0OZQA==
+
 load-json-file@^1.0.0:
   version "1.1.0"
   resolved "https://registry.yarnpkg.com/load-json-file/-/load-json-file-1.1.0.tgz#956905708d58b4bab4c2261b04f59f31c99374c0"
@@ -12965,6 +12993,13 @@ store2@^2.12.0:
   resolved "https://registry.yarnpkg.com/store2/-/store2-2.12.0.tgz#e1f1b7e1a59b6083b2596a8d067f6ee88fd4d3cf"
   integrity sha512-7t+/wpKLanLzSnQPX8WAcuLCCeuSHoWdQuh9SB3xD0kNOM38DNf+0Oa+wmvxmYueRzkmh6IcdKFtvTa+ecgPDw==
 
+storybook-addon-designs@^6.2.1:
+  version "6.2.1"
+  resolved "https://registry.yarnpkg.com/storybook-addon-designs/-/storybook-addon-designs-6.2.1.tgz#47fd1a7a098cad027b3891bd72a7f9c1837d94a0"
+  integrity sha512-ihsscab8185HnxqTNZlM4TfrCPVsO7AimVA8BapuqT/sfZQF9m5H9C0plT3kbECdIMh2cmzMBF1Tc9ckWRgpWg==
+  dependencies:
+    "@figspec/react" "^1.0.0"
+
 stream-browserify@^2.0.1:
   version "2.0.2"
   resolved "https://registry.yarnpkg.com/stream-browserify/-/stream-browserify-2.0.2.tgz#87521d38a44aa7ee91ce1cd2a47df0cb49dd660b"