Radio button usage updates

src/pages/components/radio-button/usage.mdx

@@ -17,18 +17,61 @@ one selection from the group is allowed.
 
 <AnchorLink>Overview</AnchorLink>
 <AnchorLink>Live demo</AnchorLink>
-<AnchorLink>Format</AnchorLink>
-<AnchorLink>Default selection</AnchorLink>
+<AnchorLink>Formatting</AnchorLink>
+<AnchorLink>Content</AnchorLink>
+<AnchorLink>Behaviors</AnchorLink>
+<AnchorLink>Related</AnchorLink>
+<AnchorLink>References</AnchorLink>
 <AnchorLink>Feedback</AnchorLink>
 
 </AnchorLinks>
 
 ## Overview
 
-Radio buttons represent a group of mutually exclusive choices, compared to
-checkboxes that allow users to make one or more selections from a group. In use
-cases where only one selection from a group is allowed, use the radio button
-component instead of the checkbox.
+Radio buttons are used for mutually exclusive choices, not for multiple choices.
+Only one radio button can be selected at a time. When a user chooses a new item,
+the previous choice is automatically deselected.
+
+### When to use
+
+#### Form
+
+Can be used in forms on a full page, in modals, or on side panels.
+
+#### Settings
+
+Used to change from one setting to another in a menu, page, or component.
+
+#### Selection in lists
+
+Used to choose a singular item within data tables or lists.
+
+<Row>
+<Column colLg={8}>
+
+![Example of radio buttons in a form](images/radio-button-usage-1.png)
+
+</Column>
+</Row>
+
+### When not to use
+
+If a user can select many option from a list, use checkboxes instead of radio
+buttons. Radio buttons allow the user to select only one item in a set whereas
+checkboxes allow the user to select multiple options.
+
+<DoDontRow>
+  <DoDont caption="Do use checkboxes when multiple items can be selected.">
+
+![Do use checkboxes when multiple items can be selected.](images/radio-button-usage-2-do.png)
+
+  </DoDont>
+  <DoDont type="dont" caption="Don't use radio buttons when multiple items can be selected.">
+
+![Don't use radio buttons when multiple items can be selected.](images/radio-button-usage-2-dont.png)
+
+  </DoDont>
+</DoDontRow>
 
 ## Live demo
 
@@ -82,26 +125,274 @@ component instead of the checkbox.
   `}</ComponentVariant>
 </ComponentDemo>
 
-## Format
+## Formatting
+
+### Anatomy
+
+The radio button component is comprised of a set of clickable circles (the
+inputs) with text labels positioned to the right. If there is a group of radio
+buttons, a group label can be added.
+
+<Row>
+<Column colLg={8}>
+
+![Anatomy of radio buttons](images/radio-button-usage-3.png)
+
+</Column>
+</Row>
+
+1. **Radio button group label (optional):** Describes the group of options or
+   provides guidance for making a selection.
+2. **Radio button input:** A radio button indicating the appropriate state. By
+   default an option is selected.
+3. **Radio button label:** Describes the information you want to select or
+   unselect.
+
+### Alignment
+
+Radio button labels are positioned to the right of their inputs in languages
+that read left to right. If there is a radio button grouping, they can be laid
+out vertically or horizontally depending on the use case and the structure of
+the UI. When possible, arrange the radio button and checkbox groups vertically
+for easier reading.
 
-#### Headings
+<Row>
+<Column colLg={8}>
+
+![Vertically stacked versus horizontal alignment](images/radio-button-usage-4.png)
+
+</Column>
+</Row>
+
+<Caption>Vertically stacked versus horizontal alignment</Caption>
+
+For languages that read right to left, it's acceptable to place labels to the
+left of the inputs.
+
+<Row>
+<Column colLg={8}>
+
+![Example of radio buttons for languages that read right to left instead of left to right](images/radio-button-usage-13.png)
+
+</Column>
+</Row>
+
+<Caption>
+  Example of radio buttons for languages that read right to left instead of left
+  to right
+</Caption>
+
+### Placement
+
+The radio button component is often used in forms. Forms can be placed on a full
+page, in a modal, or in a side panel. A radio button can also be used for
+changing settings in a menu or selecting a singular item in a data table.
+
+<Row>
+<Column colLg={8}>
+
+![Placement of radio buttons](images/radio-button-usage-5.png)
+
+</Column>
+</Row>
+
+Radio buttons in a form should be placed at least 32px (`layout-03`) below or
+before the next component. Spacing of 24px (`layout-02`) or 16px (`layout-01`)
+can also be used when space is more restricted or if the form is more complex.
+
+For more information on spacing in forms, see our
+[form style guidance](https://www.carbondesignsystem.com/components/form/style).
+
+<Row>
+<Column colLg={8}>
+
+![Spacing between a radio button and other components in a form](images/radio-button-usage-6.png)
+
+</Column>
+</Row>
+
+<Caption>Spacing between a radio button and other components in a form</Caption>
+
+## Content
+
+### Main elements
+
+#### Group labels (optional)
 
 If necessary, a heading can accompany a set of radio buttons to provide further
-clarity for the user. Use sentence-style capitalization (only the first word in
-a phrase and any proper nouns capitalized).
+context or clarity.
+
+- A group label can either state the category of the grouping or describe what
+  actions to take below.
+- Use sentence case for group labels.
+- In some cases, a group of radio buttons may be within a larger group of
+  components that already have a group label. In this case, an additional group
+  label for the radio button component itself is not needed.
+- Regardless of whether the label is visible in the interface, a group label is
+  always needed in code, whether it’s for one checkbox or a group of them. See
+  the
+  [radio button code tab](https://www.carbondesignsystem.com/components/radio-button/code)
+  for more information.
+
+#### Radio button labels
 
-#### Labels
+- Always use clear and concise labels for radio buttons.
+- Be explicit about the results that will follow if the radio button is
+  selected.
+- Labels appear to the right of radio button inputs.
 
-Always use a clear and concise label for radio buttons. Be explicit about the
-action that will follow if the radio button is selected. Labels appear to the
-right of radio buttons. Use sentence-style capitalization (only the first word
-in a phrase and any proper nouns capitalized) and no more than three words.
+### Overflow content
 
-## Default selection
+- We recommend radio button labels being fewer than three words.
+- If you are tight on space, consider rewording the label. Do not truncate radio
+  button label text with an ellipsis.
+- Long labels may wrap to a second line, and this is preferable to truncation.
+- Text should wrap beneath the radio button so the control and label are top
+  aligned.
+
+<Row>
+<Column colLg={8}>
+
+![Spacing between a radio button and other components in a form](images/radio-button-usage-11.png)
+
+</Column>
+</Row>
+
+<DoDontRow>
+<DoDont caption="Do let text wrap beneath the radio button so the control and label are top aligned.">
+
+![Do let text wrap beneath the radio button so the control and label are top aligned.](images/radio-button-usage-12-do.png)
+
+</DoDont>
+<DoDont type="dont" caption="Do not vertically center wrapped text with the radio button.">
+
+![Do not vertically center wrapped text with the radio button.](images/radio-button-usage-12-dont.png)
+
+</DoDont>
+</DoDontRow>
+
+### Further guidance
+
+For further content guidance, see Carbon's
+[content guidelines](https://www.carbondesignsystem.com/guidelines/content/overview).
+
+## Behaviors
+
+### States
+
+The radio button input allows for two states: unselected and selected. The
+default view of a radio button is having at least one radio button preselected.
+Only one radio button should be selected at a time. When a user chooses a new
+item, the previous choice is automatically deselected.
+
+<Row>
+<Column colLg={8}>
+
+![Examples of selected and unselected radio buttons](images/radio-button-usage-7.png)
+
+</Column>
+</Row>
+
+In addition to unselected and selected states, radio buttons also have states
+for focus and disabled.
+
+<Row>
+<Column colLg={8}>
+
+![Examples of focus states and disabled states](images/radio-button-usage-8.png)
+
+</Column>
+</Row>
+
+### Interactions
+
+#### Mouse
+
+Users can trigger an item by clicking the radio button input directly or by
+clicking the radio button label. Having both regions interactive creates a more
+accessible click target.
+
+<Row>
+<Column colLg={8}>
+
+![Click targets for radio buttons](images/radio-button-usage-10.png)
+
+</Column>
+</Row>
+
+#### Keyboard
+
+One radio button should be selected by default. Users can navigate between radio
+button inputs by pressing `Up` or `Down` arrow keys. Users can trigger a state
+change by pressing `Space` while the checkbox input has focus. For additional
+keyboard interactions, see
+the [accessibility tab](https://www.carbondesignsystem.com/components/radio-button/accessibility).
+
+#### Screenreader
+
+VoiceOver: Users can navigate between radio buttons by pressing the `Up` and
+`Down` arrow keys.
+
+JAWS: Users can navigate between radio buttons by pressing the `Up` and `Down`
+arrow keys.
+
+NVDA: Users can navigate between radio buttons by pressing the `Up` and `Down`
+arrow keys.
+
+For additional information,
+see [screen reader tests](https://www.carbondesignsystem.com/components/radio-button/accessibility#accessibility-testing).
+
+### Default selection
 
 A set of radio buttons should default to having one option selected. Never
 display them without a default selection.
 
+## Related
+
+#### Radio buttons versus checkboxes
+
+Radio buttons allow users to select one option from a group of mutually
+exclusive choices, while checkboxes allow for a selection of one of more options
+from a group. In the use cases where multiple selections are allowed, use the
+[checkbox component](https://www.carbondesignsystem.com/components/checkbox/usage)
+instead of the radio button.
+
+#### Radio button verses selectable tile
+
+Radio buttons should have concise, easy to compare options. If more information
+is required to make a choice, like pricing plans or additional links, consider
+using a
+[selectable tile](https://www.carbondesignsystem.com/components/tile/usage#selectable).
+
+#### Structured list
+
+If a user needs to choose a singular item from a list that has simple data and
+multiple columns, a selectable
+[structured list](https://carbondesignsystem.com/components/structured-list/usage)
+can be used.
+
+#### Tables
+
+See the
+[data table component](https://www.carbondesignsystem.com/components/data-table/usage#radio-selection)
+for guidance on how to use radio buttons within a table.
+
+#### Radio button verses toggle switch
+
+[Toggle switches](https://www.carbondesignsystem.com/components/toggle/usage)
+are preferred when the user options are true or false. By comparison, radio
+buttons are mutually exclusive and can have many other options.
+
+## References
+
+Jakob Nielson,
+[Checkboxes vs. Radio Buttons](https://www.nngroup.com/articles/checkboxes-vs-radio-buttons/)
+(Nielsen Norman Group, 2004)
+
+Kara Pernice,
+[Radio Buttons: Select One by Default or Leave All Unselected?](https://www.nngroup.com/articles/radio-buttons-default-selection/)
+(Nielsen Norman Group, 2014)
+
 ## Feedback
 
 Help us improve this component by providing feedback, asking questions, and