From 27c4065b3f1b75223b06a3640b1c80799fae5804 Mon Sep 17 00:00:00 2001 From: Marie Lucca <40550942+francinelucca@users.noreply.github.com> Date: Fri, 1 Nov 2024 12:31:35 -0400 Subject: [PATCH] Docs: add a11y guidance regarding required fields (#878) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Docs: add a11y guidance regarding required fields * Update content/ui-patterns/forms/overview.mdx Co-authored-by: Armağan --------- Co-authored-by: Armağan --- content/components/checkbox.mdx | 2 +- content/components/form-control.mdx | 28 +++++++++ content/ui-patterns/forms/overview.mdx | 78 +++++++++++++++++++++++++- 3 files changed, 106 insertions(+), 2 deletions(-) diff --git a/content/components/checkbox.mdx b/content/components/checkbox.mdx index 51a4e4e7e..fc5d4990e 100644 --- a/content/components/checkbox.mdx +++ b/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 diff --git a/content/components/form-control.mdx b/content/components/form-control.mdx index 78191698f..3401222fc 100644 --- a/content/components/form-control.mdx +++ b/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. + + + + {` + + + Form Input Label + + + + `} + Set the required field in the form control + + + {` + + + Form Input Label + + + + `} + Don’t set the required field on the underlying input + + + ### Known accessibility issues (GitHub staff only) diff --git a/content/ui-patterns/forms/overview.mdx b/content/ui-patterns/forms/overview.mdx index f6932b23f..30b87430b 100644 --- a/content/ui-patterns/forms/overview.mdx +++ b/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. + + + + {` + + + Form Input Label + + + + `} + Set the required field in the form control + + + {` + + + Form Input Label + + + + `} + Don’t set the required field on the underlying input + + + +An individual radio button cannot be marked as required. You may indicate a required selection within a [radio group](/components/radio-group). + + + + {` + + + Radio Group Label + + + + + Choice one + + + + + + Choice two + + +`} + Set the required field in the radio group + + + {` + + + Radio Group Label + + + + + Choice one + + + + + + Choice two + + + + `} + Don’t set the required field on an individual radio + + + +Individual checkboxes may be marked as required, as well as [checkbox groups](/components/checkbox-group). ### Input (required)