The greatest documentation quest 2020 - vf-button edition. (#1348)

* reduces the available buttons to be used in examples

* renames outline as secondary

* updates readme with some usage criterai

* ch-ch-cha-changelog

* Add line break

* brings back other variants but hides them

Co-authored-by: Ken Hawkins <khawkins98@gmail.com>

components/vf-button/CHANGELOG.md

@@ -1,3 +1,8 @@
+### 1.4.0
+
+* Removes variants that are not to be used from the examples available.
+* Adds usage documentation.
+
 ### 1.3.1
 
 * React: Use react-dom-fragment to return HTML fragments.

components/vf-button/README.md

@@ -4,7 +4,33 @@
 
 ## About
 
-Button styling
+Buttons are clickable elements that trigger an action. They can communicate calls to action, are visually prominent, and allow users to interact with the pages in various ways.
+
+## Usage
+
+The `vf-button` component can be used with forms on a page but can also be used as a prominent 'call to action' link that goes to another page with more information.
+
+### When To Use
+
+A site visitor generally would expect a button to submit data or take action, and if used as a link to navigate to another page.
+
+Each form on a page should only have one primary button, any remaining buttons should use the secondary (outline primary) button.
+
+As the `vf-button` is relatively large to add to its visual dominence, depending on the context you may wish to use the `vf-button--small` variant.
+
+#### Alignment
+
+As a general rule, the `vf-button` should be left aligned on the page and when used inside as part of a larger component. When used in conjuction with a single form input, like a search input, the `vf-button` needs to be inline with the input and to the right of it. When a `vf-button` is used in a banner it needs to follow the content and be right aligned.
+
+### When Not To Use
+
+If using the `vf-button` as a link do not use it to link to content on the same page. This is where something like the <a href="/components/vf-link-list/#vf-link-list--easy">`vf-link-list`</a> component should be used.
+
+### Label
+
+The button text should be short and clear. Depending on the action of the button it should use agreed microcopy<sup>*</sup>.
+
+<sup>*</sup>to be done.
 
 ## Install
 

components/vf-button/vf-button.config.yml

@@ -5,14 +5,16 @@ context:
   component-type: element
 variants:
   - name: default
-    label: Primary
+    hidden: true
+  - name: Primary
     context:
       text: a primary button
       theme: primary
-  - name: secondary
+  - name: Secondary
     context:
-      text: a secondary button
-      theme: secondary
+      text: an outline style
+      theme: primary
+      style: ["outline"]
   - name: tertiary
     context:
       text: a tertiary button
@@ -22,32 +24,39 @@ variants:
       text: a small button
       theme: primary
       size: sm
+  - name: link
+    context:
+      text: a link variant
+      button_href: "JavaScript:Void(0);"
+      theme: primary
+
+  # TODO: get rid of these on the next major release
   - name: regular
+    hidden: true
     context:
       text: a regular button
       theme: primary
   - name: large
+    hidden: true
     context:
       text: a large button
       theme: primary
       size: lg
   - name: pill
+    hidden: true
     context:
       text: a pill style
       theme: primary
       style: ["pill"]
   - name: rounded
+    hidden: true
     context:
       text: a rounded style
       theme: primary
       style: ["rounded"]
   - name: outline
+    hidden: true
     context:
       text: an outline style
       theme: primary
       style: ["outline"]
-  - name: link
-    context:
-      text: a link variant
-      button_href: "JavaScript:Void(0);"
-      theme: primary