diff --git a/src/pages/components/toggle/images/toggle-style-color.png b/src/pages/components/toggle/images/toggle-style-color.png index eb4aacb4224..2566fa09899 100644 Binary files a/src/pages/components/toggle/images/toggle-style-color.png and b/src/pages/components/toggle/images/toggle-style-color.png differ diff --git a/src/pages/components/toggle/images/toggle-style-default-spec.png b/src/pages/components/toggle/images/toggle-style-default-spec.png index fad1d1a0708..46c56fbc7aa 100644 Binary files a/src/pages/components/toggle/images/toggle-style-default-spec.png and b/src/pages/components/toggle/images/toggle-style-default-spec.png differ diff --git a/src/pages/components/toggle/images/toggle-style-sizes.png b/src/pages/components/toggle/images/toggle-style-sizes.png index 5c1348cbbf8..e9b8f7671fa 100644 Binary files a/src/pages/components/toggle/images/toggle-style-sizes.png and b/src/pages/components/toggle/images/toggle-style-sizes.png differ diff --git a/src/pages/components/toggle/images/toggle-style-small-spec.png b/src/pages/components/toggle/images/toggle-style-small-spec.png index 7611238c266..f2c0e44433d 100644 Binary files a/src/pages/components/toggle/images/toggle-style-small-spec.png and b/src/pages/components/toggle/images/toggle-style-small-spec.png differ diff --git a/src/pages/components/toggle/images/toggle-style-states.png b/src/pages/components/toggle/images/toggle-style-states.png index e970aa08a1e..70da1fff676 100644 Binary files a/src/pages/components/toggle/images/toggle-style-states.png and b/src/pages/components/toggle/images/toggle-style-states.png differ diff --git a/src/pages/components/toggle/images/toggle-usage-anatomy.png b/src/pages/components/toggle/images/toggle-usage-anatomy.png new file mode 100644 index 00000000000..94d821d956a Binary files /dev/null and b/src/pages/components/toggle/images/toggle-usage-anatomy.png differ diff --git a/src/pages/components/toggle/images/toggle-usage-small-with-action-text.png b/src/pages/components/toggle/images/toggle-usage-small-with-action-text.png new file mode 100644 index 00000000000..35481b8c598 Binary files /dev/null and b/src/pages/components/toggle/images/toggle-usage-small-with-action-text.png differ diff --git a/src/pages/components/toggle/images/toggle-usage-variants.png b/src/pages/components/toggle/images/toggle-usage-variants.png index 47f0cd638b1..36848003050 100644 Binary files a/src/pages/components/toggle/images/toggle-usage-variants.png and b/src/pages/components/toggle/images/toggle-usage-variants.png differ diff --git a/src/pages/components/toggle/images/toggle_usage_overview.png b/src/pages/components/toggle/images/toggle_usage_overview.png new file mode 100644 index 00000000000..805da411e18 Binary files /dev/null and b/src/pages/components/toggle/images/toggle_usage_overview.png differ diff --git a/src/pages/components/toggle/style.mdx b/src/pages/components/toggle/style.mdx index 980ee79678d..5586362dbf2 100755 --- a/src/pages/components/toggle/style.mdx +++ b/src/pages/components/toggle/style.mdx @@ -6,6 +6,23 @@ description: tabs: ['Usage', 'Style', 'Code', 'Accessibility'] --- + + +The following page documents visual specifications such as color, typography, +structure, and size. + + + + + +Color +Typography +Structure +Size +Feedback + + + ## Color | Element | Property | Color token | @@ -30,6 +47,9 @@ tabs: ['Usage', 'Style', 'Code', 'Accessibility'] ### Interactive states +The default and small toggle can be switched on and off across focus, disabled, +and read-only states. + | State | Element | Property | Color token | | --------- | ----------- | ---------------- | ------------------------- | | Focus | Toggle | border | `$focus` | @@ -57,7 +77,7 @@ tabs: ['Usage', 'Style', 'Code', 'Accessibility'] -Interactive toggle states +Interactive toggle states. ## Typography @@ -98,7 +118,7 @@ phrase and any proper nouns capitalized, and no more than three words. | Toggle | width | 32 / 2 | – | | | height | 16 / 1 | – | | Handle | height, width | 10 / 0.625 | `$spacing-03` | -| Action text | margin left | 8/ 0.5 | `$spacing-03` | +| Action text | margin left | 8 / 0.5 | `$spacing-03` |
@@ -110,7 +130,7 @@ phrase and any proper nouns capitalized, and no more than three words. Structure and spacing measurements for small toggle | px / rem -## Sizes +## Size | Size | Height px / rem | | ---------- | --------------- | @@ -124,3 +144,9 @@ phrase and any proper nouns capitalized, and no more than three words.
Toggle sizes | px / rem + +## Feedback + +Help us improve this component by providing feedback, asking questions, and +leaving any other comments on +[GitHub](https://github.com/carbon-design-system/carbon-website/issues/new?assignees=&labels=feedback&template=feedback.md). diff --git a/src/pages/components/toggle/usage.mdx b/src/pages/components/toggle/usage.mdx index d0120861410..4aef0075554 100755 --- a/src/pages/components/toggle/usage.mdx +++ b/src/pages/components/toggle/usage.mdx @@ -19,6 +19,7 @@ commonly used for “on/off” switches. Live demo Overview +Formatting Content Behaviors Default toggle @@ -52,6 +53,16 @@ Toggle is a control that is used to quickly switch between two possible states. Toggles are only used for these binary actions that occur immediately after the user “flips the switch”. They are commonly used for “on/off” switches. + + + +![Toggle being used in context of a product UI](images/toggle_usage_overview.png) + + + + +Toggle being used in context of a product UI + ## Variants | Variant | Purpose | @@ -69,64 +80,123 @@ user “flips the switch”. They are commonly used for “on/off” switches. Default and small toggle variants +## Formatting + +### Anatomy + +Default and small toggles are both comprised of a component label, a toggle +button, and action text. Default toggles are required to display a component +label and action text, unlike the small toggle, where both these elements are +optional. The small toggle displays a checkmark tick in the on state to ensure +the toggle is still accessible when label and action text are unavailable. + + + + +![Anatomy of default and small toggle variants](images/toggle-usage-anatomy.png) + + + + +Anatomy of default and small toggle + + + + +#### 1. Default toggle + +A. Label
B. Toggle
C. Action text
+ + + + +#### 2. Small toggle + +A. Label (optional)
B. Toggle
C. Action text (optional)
D. +Checkmark tick (on state)
+ + + + ## Content #### Label text Label text must accompany a toggle to further clarify the action that the toggle -performs. +performs. Label text is optional for small toggle. #### Action text Use text to describe the binary action of toggle so that the action is clear. Action text must be three words or less and is displayed on the side of a -toggle. +toggle. Action text is optional for small toggle. #### Language Use adjectives rather than verbs to describe actions and the state of the object affected. +### Further guidance + +For further content guidance, see Carbon’s +[content guidelines](https://carbondesignsystem.com/guidelines/content/overview/). + ## Behaviors ### States -Toggles have six states: on, off, focus, disabled, skeleton, and read-only. +The default and small toggle have two main states: **on** and **off**. Other +interactive states are **focus**, **disabled**, **read-only**, and **skeleton**. +For more information on toggle states, see the +[Style tab](https://carbondesignsystem.com/components/toggle/style/). + +| State | When to use | +| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| On | When a user clicks or uses the arrow keys to switch on the component. | +| Off | When a user clicks or uses the arrow keys to switch off the component. | +| Focus | When a user presses tab or clicks on the toggle, it becomes focused, indicating the user has successfully navigated to the component. | +| Disabled | When a user is not allowed to interact with the toggle due to either permissions, dependencies, or pre-requisites. The disabled state completely removes the interactive function from a component. The styling is not subject to WCAG contrast compliance. | +| Read-only | When the user can review but not modify the component. This state removes all interactive functions like the disabled state but can still be focusable, accessible by screen readers, and passes visual contrast for readability. | +| Skeleton | Use on an initial page load to indicate that the toggle has not yet fully loaded. | + +## Default toggle + +The default toggle is larger in size than the small toggle. They are commonly +used in forms and can appear within full pages of information that are not +restricted in space. Default toggles are required to display a visible label and +action text. -![Default and small toggle variants](images/toggle-usage-states.png) +![Example of a default toggle in context](images/toggle-usage-default.png) -Example of toggle states +Example of a default toggle in context -## Default toggle +## Small toggle -Default toggles are larger in size than small toggles. They are commonly used in -forms and can appear within full pages of information that are not restricted in -space. Default toggles are required to display visible label and action text. +Small toggle is often used in condensed spaces and appear inline with other +components or content. The label and action text are optional for small toggle. -![Example of a default toggle in context](images/toggle-usage-default.png) +![Example of a small toggle with action text in context](images/toggle-usage-small-with-action-text.png) -Example of a default toggle in context +Example of a small toggle with action text in context -## Small toggle +
-Small toggles are often used in condensed spaces and appear inline with other -components or content, for example, inside -[data table](/components/data-table/usage) rows. Unlike the default toggle, the -small toggle is more compact in size and displays a checkmark tick in the on -state to ensure the toggle is still accessible without requiring visible label -or action text. +Unlike the default toggle, the small toggle is more compact in size and displays +a checkmark tick in the on state to ensure the toggle is still accessible +without requiring visible label or action text. For example, inside +[data table](/components/data-table/usage) rows.