Toggle doc updates

src/pages/components/toggle/style.mdx

@@ -6,6 +6,23 @@ description:
 tabs: ['Usage', 'Style', 'Code', 'Accessibility']
 ---
 
+<PageDescription>
+
+The following page documents visual specifications such as color, typography,
+structure, and size.
+
+</PageDescription>
+
+<AnchorLinks>
+
+<AnchorLink>Color</AnchorLink>
+<AnchorLink>Typography</AnchorLink>
+<AnchorLink>Structure</AnchorLink>
+<AnchorLink>Size</AnchorLink>
+<AnchorLink>Feedback</AnchorLink>
+
+</AnchorLinks>
+
 ## 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']
 </Column>
 </Row>
 
-<Caption>Interactive toggle states</Caption>
+<Caption>Interactive toggle states.</Caption>
 
 ## 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` |
 
 <div className="image--fixed">
 
@@ -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
 </Caption>
 
-## Sizes
+## Size
 
 | Size       | Height px / rem |
 | ---------- | --------------- |
@@ -124,3 +144,9 @@ phrase and any proper nouns capitalized, and no more than three words.
 </div>
 
 <Caption>Toggle sizes | px / rem</Caption>
+
+## 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).

src/pages/components/toggle/usage.mdx

@@ -19,6 +19,7 @@ commonly used for “on/off” switches.
 
 <AnchorLink>Live demo</AnchorLink>
 <AnchorLink>Overview</AnchorLink>
+<AnchorLink>Formatting</AnchorLink>
 <AnchorLink>Content</AnchorLink>
 <AnchorLink>Behaviors</AnchorLink>
 <AnchorLink>Default toggle</AnchorLink>
@@ -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.
 
+<Row>
+<Column colLg={8}>
+
+![Toggle being used in context of a product UI](images/toggle_usage_overview.png)
+
+</Column>
+</Row>
+
+<Caption>Toggle being used in context of a product UI</Caption>
+
 ## Variants
 
 | Variant                           | Purpose                                                                                                                                                                  |
@@ -69,64 +80,123 @@ user “flips the switch”. They are commonly used for “on/off” switches.
 
 <Caption>Default and small toggle variants</Caption>
 
+## 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.
+
+<Row>
+<Column colLg={8}>
+
+![Anatomy of default and small toggle variants](images/toggle-usage-anatomy.png)
+
+</Column>
+</Row>
+
+<Caption>Anatomy of default and small toggle</Caption>
+
+<Row>
+<Column colSm={2} colMd={4} colLg={4}>
+
+#### 1. Default toggle
+
+A. Label <br /> B. Toggle <br /> C. Action text <br />
+
+</Column>
+<Column colSm={2} colMd={4} colLg={4}>
+
+#### 2. Small toggle
+
+A. Label (optional) <br /> B. Toggle <br /> C. Action text (optional) <br /> D.
+Checkmark tick (on state) <br />
+
+</Column>
+</Row>
+
 ## 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.
 
 <Row>
 <Column colLg={8}>
 
-![Default and small toggle variants](images/toggle-usage-states.png)
+![Example of a default toggle in context](images/toggle-usage-default.png)
 
 </Column>
 </Row>
 
-<Caption>Example of toggle states</Caption>
+<Caption>Example of a default toggle in context</Caption>
 
-## 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.
 
 <Row>
 <Column colLg={8}>
 
-![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)
 
 </Column>
 </Row>
 
-<Caption>Example of a default toggle in context</Caption>
+<Caption>Example of a small toggle with action text in context</Caption>
 
-## Small toggle
+<br />
 
-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.
 
 <Row>
 <Column colLg={8}>