Docs: add a11y guidance regarding required fields (#878)

* Docs: add a11y guidance regarding required fields

* Update content/ui-patterns/forms/overview.mdx

Co-authored-by: Armağan <[email protected]>

---------

Co-authored-by: Armağan <[email protected]>

content/components/checkbox.mdx

@@ -39,7 +39,7 @@ Checkboxes are capable of showing two forms of selection: checked (left) or inde
 ### Best practices
 
 - An individual checkbox should not have its own validation message or style. Instead, show a validation message on the [checkbox group](/components/checkbox-group). For more information, see the [Validation Message](../ui-patterns/forms/overview#validation) section in the Forms documentation.
-- An individual checkbox button cannot be marked as required. Instead, make a selection required using the [checkbox group](/components/checkbox-group). For more information, see the [Required field indicator](../ui-patterns/forms/overview#required-field-indicator) in the Forms documentation.
+- While there are certain use cases where an individual checkbox may be required, the most common use case is to require a selection from a [checkbox group](/components/checkbox-group). In this case, an individual checkbox button should not be marked as required, but the checkbox group should be marked as required instead. For more information, see the [Required field indicator](../ui-patterns/forms/overview#required-field-indicator) in the Forms documentation.
 
 ## Accessibility
 

content/components/form-control.mdx

@@ -4,6 +4,7 @@ description: Form control displays a labelled input and, optionally, associated
 reactId: form_control
 ---
 
+import Code from '@primer/gatsby-theme-doctocat/src/components/code'
 import ComponentLayout from '~/src/layouts/component-layout'
 export default ComponentLayout
 import {AccessibilityLink} from '~/src/components/accessibility-link'
@@ -28,6 +29,33 @@ To learn more about anatomy, input methods, forms structure, validation, and mor
 
 When using symbols -e.g., an asterisk (*)- to indicate particular fields are required within a form, consider adding a "Required fields are marked with an asterisk (\*)" message at the top of the form for extra clarity.
 
+When marking a control as required, opt to mark the form control as required instead of the input contained within it. The form control will ensure that the required state is passed down to the input element.
+
+<DoDontContainer>
+  <Do>
+        <Code classname="language-jsx">{`
+      <FormControl required>
+  <FormControl.Label>
+    Form Input Label
+  </FormControl.Label>
+  <Checkbox />
+</FormControl>
+    `}</Code>
+    <Caption>Set the required field in the form control</Caption>
+  </Do>
+  <Dont>
+    <Code classname="language-jsx">{`
+      <FormControl>
+  <FormControl.Label>
+    Form Input Label
+  </FormControl.Label>
+  <Checkbox required />
+</FormControl>
+    `}</Code>
+    <Caption>Don’t set the required field on the underlying input</Caption>
+  </Dont>
+</DoDontContainer>
+
 ### Known accessibility issues (GitHub staff only)
 
  <AccessibilityLink label="FormControl"/>

content/ui-patterns/forms/overview.mdx

@@ -5,6 +5,7 @@ current_page: overview
 ---
 
 import {Box, Heading} from '@primer/react'
+import Code from '@primer/gatsby-theme-doctocat/src/components/code'
 import FormsLayout from '~/src/layouts/forms-layout'
 export default FormsLayout
 
@@ -35,7 +36,82 @@ This guidance applies to situations where all fields are required. The exception
 
 Fields visually marked as required should also be set as required in code. This creates a parity in experience for all users.
 
-An individual checkbox or radio button cannot be marked as required.
+When marking a field as required, opt to mark the [form control](/components/form-control) as required instead of the input contained within it. The [form control](/components/form-control) will ensure that the required state is passed down to the input element.
+
+<DoDontContainer>
+  <Do>
+        <Code classname="language-jsx">{`
+      <FormControl required>
+  <FormControl.Label>
+    Form Input Label
+  </FormControl.Label>
+  <Checkbox />
+</FormControl>
+    `}</Code>
+    <Caption>Set the required field in the form control</Caption>
+  </Do>
+  <Dont>
+    <Code classname="language-jsx">{`
+      <FormControl>
+  <FormControl.Label>
+    Form Input Label
+  </FormControl.Label>
+  <Checkbox required />
+</FormControl>
+    `}</Code>
+    <Caption>Don’t set the required field on the underlying input</Caption>
+  </Dont>
+</DoDontContainer>
+
+An individual radio button cannot be marked as required. You may indicate a required selection within a [radio group](/components/radio-group).
+
+<DoDontContainer>
+  <Do>
+        <Code classname="language-jsx">{`
+       <RadioGroup name="radioGroup" required>
+  <RadioGroup.Label>
+    Radio Group Label
+  </RadioGroup.Label>
+  <FormControl>
+    <Radio value="one" />
+    <FormControl.Label>
+      Choice one
+    </FormControl.Label>
+  </FormControl>
+  <FormControl>
+    <Radio value="two" defaultChecked />
+    <FormControl.Label>
+      Choice two
+    </FormControl.Label>
+  </FormControl>
+</RadioGroup>`}</Code>
+    <Caption>Set the required field in the radio group</Caption>
+  </Do>
+  <Dont>
+    <Code classname="language-jsx">{`
+      <RadioGroup name="radioGroup">
+  <RadioGroup.Label>
+    Radio Group Label
+  </RadioGroup.Label>
+  <FormControl>
+    <Radio value="one" required />
+    <FormControl.Label>
+      Choice one
+    </FormControl.Label>
+  </FormControl>
+  <FormControl>
+    <Radio value="two" defaultChecked />
+    <FormControl.Label>
+      Choice two
+    </FormControl.Label>
+  </FormControl>
+</RadioGroup>
+    `}</Code>
+    <Caption>Don’t set the required field on an individual radio</Caption>
+  </Dont>
+</DoDontContainer>
+
+Individual checkboxes may be marked as required, as well as [checkbox groups](/components/checkbox-group).
 
 ### Input (required)