diff --git a/.stylelintrc.yml b/.stylelintrc.yml
index 830c21021..1b0f930df 100644
--- a/.stylelintrc.yml
+++ b/.stylelintrc.yml
@@ -27,7 +27,7 @@ rules:
selector-pseudo-class-no-unknown: true
## General / Sheet
- no-duplicate-selectors: true
+ # no-duplicate-selectors: true
no-empty-source: true
no-extra-semicolons: true
diff --git a/docs/_data/sidebars/left-navigation-sidebar.yml b/docs/_data/sidebars/left-navigation-sidebar.yml
index e9fec47c1..1e679176c 100755
--- a/docs/_data/sidebars/left-navigation-sidebar.yml
+++ b/docs/_data/sidebars/left-navigation-sidebar.yml
@@ -208,7 +208,7 @@ entries:
url: /components/token.html
output: web
- - title: Toggle
+ - title: Toggle / Switch
url: /components/toggle.html
output: web
diff --git a/docs/pages/components/toggle.md b/docs/pages/components/toggle.md
index f22e53fbe..8e69011a6 100644
--- a/docs/pages/components/toggle.md
+++ b/docs/pages/components/toggle.md
@@ -1,24 +1,120 @@
---
-title: Toggle
+title: Toggle / Switch
id: toggle
-keywords: toggle
+keywords: toggle, swtich
sidebar: left-navigation-sidebar
toc: false
permalink: components/toggle.html
folder: components
---
-The toggle 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”.
-
-## Toggle Sizes
+## Toggle with Label on top
+To clarify the meaning of the toggle, use a label above it (ex. Live).
-The toggle can be set to 4 sizes: `--xs`, `--s`, normal and `--l`. When used with forms, it is recommended to use the small size so that form components will be consistent.
+{% capture default %}
+
+
+
+
+
+
+{% endcapture %}
+{% include display-component.html component=default %}
+## 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 %}
+
+
+
+
+{% 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 %}
+
+
+
+{% 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 %}
+
+{% endcapture %}
+{% include display-component.html component=default %}
+
+
+## Compact Mode
+`fd-toggle--compact` modifier can be used to render the compact size of the toggle
+{% capture default %}
+
+
+
+{% endcapture %}
+{% include display-component.html component=default %}
+
+
+## Other Size Options
+
+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: `--semantic` modifier is currently not supported by these optional sizes
{% capture default %}
@@ -41,16 +137,6 @@ The toggle can be set to 4 sizes: `--xs`, `--s`, normal and `--l`. When used wit