Update toggle documentation

Author: saad-mo

docs/pages/components/toggle.md

@@ -8,38 +8,72 @@ permalink: components/toggle.html
 folder: components
 ---
 
-The toggle/swtich component is used to activate or deactivate an element. Uses a visual metaphor that is know to the user with visible differences between on and off state.
+The toggle/switch is meant to resemble a physical switch and allow a user to turn a setting “on” or “off”. It should be used to switch between two states/modes: active or inactive.
 {: .docs-intro}
 
-It is recommended to always display the toggle with a label above it as well as the label of the selected state. For example, the label above would be Active, the toggle state would be "on" and the selected state label displayed to the right of the toggle would be "Yes".
+It is recommended to always display the toggle with a label above it as well as the label of the selected state. For example, the label above would be Active, the toggle state would be “on” and the selected state label displayed to the right of the toggle would be “Yes”.
 
-<br>
 
-## Toggle Options
-In addition to the default option, there are two additional modifiers avialable:
-- `fd-toggle--label`: renders `off` and `on` labels inside the toggle switch
-- `fd-toggle--semantic`: renders semnatic colors and icons inside the toggle switch
-
-> Note: `fd-toggle--label` modifier only supports up to three characters by default. The width of the component will not increase to accomodate longer labels and will need to be a css override, for example - `<span class="fd-toggle" style="width: 70px">`
+## Toggle with Label on top
+To clarify the meaning of the toggle, use a label above it (ex. Live).
 
 {% capture default %}
-<label>
-    <span class="fd-toggle">
-        <input type="checkbox" name="" value="" id="y21YO391">
-        <span class="fd-toggle__switch" role="presentation"></span>
-    </span>
-</label>
+<div class="fd-form__set">
+    <div class="fd-form__item">
+        <label class="fd-form__label" for="y21YO391">Live:</label>
+        <label>
+            <span class="fd-toggle">
+                <input type="checkbox" name="" value="" id="y21YO391">
+                <span class="fd-toggle__switch" role="presentation"></span>
+            </span>
+        </label>
+    </div>
+</div>
+{% endcapture %}
+{% include display-component.html component=default %}
 
-<label>
-    <span class="fd-toggle fd-toggle--label">
-        <input type="checkbox" name="" value="" id="eKVll635">
-        <span class="fd-toggle__switch" role="presentation">
-            <span class="fd-toggle__label--on">ON</span>
-            <span class="fd-toggle__label--off">OFF</span>
+## Toggle with label on the side
+When the value of the toggle requires translation, it is suggested to display the text value (ex. On/Off) outside and to the right of of the toggle to allow for longer translations.  (ex. French translation of “On” is “Allumez”)
+
+{% capture default %}
+<div class="fd-form__item fd-form__item--check">
+    <label class="fd-form__label" for="y21YO3911">
+        <span class="fd-toggle fd-form__control">
+            <input type="checkbox" name="" value="" id="y21YO3911">
+            <span class="fd-toggle__switch" role="presentation"></span>
         </span>
-    </span>
-</label>
+        Allumez
+    </label>
+</div>
 
+{% endcapture %}
+{% include display-component.html component=default %}
+
+
+To clarify the current state, display the text value to the right of the toggle (ex. On or Off). 
+
+{% capture default %}
+    <div class="fd-form__item fd-form__item--check">
+        <label class="fd-form__label" for="y21YO3911">
+            <span class="fd-toggle fd-form__control">
+                <input type="checkbox" name="" value="" id="y21YO3911">
+                <span class="fd-toggle__switch" role="presentation"></span>
+            </span>
+            Off
+        </label>
+    </div>
+{% endcapture %}
+{% include display-component.html component=default %}
+
+
+> **Note:** Use a checkbox instead: 
+> -	If it is not clear if the control is showing a state or action. 
+> -	If there are more than two options.
+
+## Symantic Toggle
+`fd-toggle--semantic` modifier renders semnatic colors and icons inside the toggle switch
+
+{% capture default %}
 <label>
     <span class="fd-toggle fd-toggle--semantic">
         <input type="checkbox" name="" value="" id="Enrat404">
@@ -54,7 +88,7 @@ In addition to the default option, there are two additional modifiers avialable:
 
 
 ## Compact Mode
-`fd-toggle--compact` modifier can be used to render the compact size of the toggle `--label` and `--semantic` options are also avialable with the `compact` mode. 
+`fd-toggle--compact` modifier can be used to render the compact size of the toggle 
 {% capture default %}
 <label>
     <span class="fd-toggle fd-toggle--compact">
@@ -63,16 +97,6 @@ In addition to the default option, there are two additional modifiers avialable:
     </span>
 </label>
 
-<label>
-    <span class="fd-toggle fd-toggle--compact fd-toggle--label">
-        <input type="checkbox" name="" value="" id="eKVll635">
-        <span class="fd-toggle__switch" role="presentation">
-            <span class="fd-toggle__label--on">ON</span>
-            <span class="fd-toggle__label--off">OFF</span>
-        </span>
-    </span>
-</label>
-
 <label>
     <span class="fd-toggle fd-toggle--compact fd-toggle--semantic">
         <input type="checkbox" name="" value="" id="Enrat404">
@@ -90,7 +114,7 @@ In addition to the default option, there are two additional modifiers avialable:
 
 In addition to `default` and `--compact`, the toggle can be set to 3 sizes: `--xs`, `--s` and `--l`. When used with forms, it is recommended to use the small size so that form components will be consistent.
 
-> Node: `--label` and `--semantic` modifiers are currently not supported by these optional sizes
+> Node: `--semantic` modifier is currently not supported by these optional sizes
 
 {% capture default %}
 <div class="fd-form__item fd-form__item--check">