Clarify id description

WordPress · Mar 15, 2022 · e53fca1 · e53fca1
1 parent e2b842f
commit e53fca1
Show file tree

Hide file tree

Showing 3 changed files with 12 additions and 9 deletions.
diff --git a/packages/components/src/base-control/README.md b/packages/components/src/base-control/README.md
@@ -1,14 +1,15 @@
 # BaseControl
 
-BaseControl component is used to generate labels and help text for components handling user inputs.
+`BaseControl` is a component used to generate labels and help text for components handling user inputs.
 
 ## Usage
 
-Render a BaseControl for a textarea input:
+Render a `BaseControl` for a textarea input:
 
 ```jsx
 import { BaseControl } from '@wordpress/components';
 
+// The `id` prop is necessary to accessibly associate the label with the textarea
 const MyBaseControl = () => (
 	<BaseControl id="textarea-1" label="Text" help="Enter some text" __nextHasNoMarginBottom={ true }>
 		<textarea id="textarea-1" />
@@ -22,10 +23,10 @@ The component accepts the following props:
 
 ### id
 
-The id of the element to which labels and help text are being generated. That element should be passed as a child.
+The HTML `id` of the element (passed in as a child to `BaseControl`) to which labels and help text are being generated. This is necessary to accessibly associate the label with that element.
 
 -   Type: `String`
--   Required: Yes
+-   Required: No
 
 ### label
 
@@ -73,16 +74,17 @@ Start opting into the new margin-free styles that will become the default in a f
 
 ## BaseControl.VisualLabel
 
-`BaseControl.VisualLabel` component is used to render a purely visual label inside a `BaseControl` component.
-It should only be used in cases where the children being rendered inside BaseControl are already properly labeled, e.g., a button, but we want an additional visual label for that section equivalent to the labels BaseControl would otherwise use if the label prop was passed.
+`BaseControl.VisualLabel` is used to render a purely visual label inside a `BaseControl` component.
+
+It should only be used in cases where the children being rendered inside BaseControl are already accessibly labeled, e.g., a button, but we want an additional visual label for that section equivalent to the labels `BaseControl` would otherwise use if the `label` prop was passed.
 
 ## Usage
 
 ```jsx
 import { BaseControl } from '@wordpress/components';
 
 const MyBaseControl = () => (
-	<BaseControl help="Pressing the Select an author button will open a modal that allows an advanced mechanism for author selection">
+	<BaseControl help="This button is already accessibly labeled.">
 		<BaseControl.VisualLabel>Author</BaseControl.VisualLabel>
 		<Button>Select an author</Button>
 	</BaseControl>

diff --git a/packages/components/src/base-control/index.tsx b/packages/components/src/base-control/index.tsx
@@ -24,6 +24,7 @@ import {
  * // Render a `BaseControl` for a textarea input
  * import { BaseControl } from '@wordpress/components';
  *
+ * // The `id` prop is necessary to accessibly associate the label with the textarea
  * const MyBaseControl = () => (
  *   <BaseControl id="textarea-1" label="Text" help="Enter some text" __nextHasNoMarginBottom={ true }>
  *     <textarea id="textarea-1" />

diff --git a/packages/components/src/base-control/types.ts b/packages/components/src/base-control/types.ts
@@ -20,8 +20,8 @@ export type BaseControlProps = {
 	 */
 	__nextHasNoMarginBottom?: boolean;
 	/**
-	 * The id of the element to which labels and help text are being generated.
-	 * That element should be passed as a child.
+	 * The HTML `id` of the element (passed in as a child to `BaseControl`) to which labels and help text are being generated.
+	 * This is necessary to accessibly associate the label with that element.
 	 */
 	id?: string;
 	/**