Described form group a11y

CHANGELOG.md

@@ -6,6 +6,7 @@
 - Converted `EuiFilterButton` to TypeScript ([#2761](https://github.com/elastic/eui/pull/2761))
 - Converted `EuiFilterSelectItem` to TypeScript ([#2761](https://github.com/elastic/eui/pull/2761))
 - Converted `EuiFieldSearch` to TypeScript ([#2775](https://github.com/elastic/eui/pull/2775))
+- Improved `EuiDescribedFormGroup` accessibility by avoiding duplicated output in screen readers ([#2783](https://github.com/elastic/eui/pull/2783))
 - Added `data-test-subj` to the `EuiContextMenuItem` in `EuiTablePagination` ([#2778](https://github.com/elastic/eui/pull/2778))
 
 **Bug fixes**

src-docs/src/views/form_layouts/described_form_group.js

@@ -10,6 +10,7 @@ import {
   EuiRange,
   EuiSelect,
   EuiSwitch,
+  EuiLink,
 } from '../../../../src/components';
 
 import makeId from '../../../../src/components/form/form_row/make_id';
@@ -86,45 +87,38 @@ export default class extends Component {
     return (
       <EuiForm>
         <EuiDescribedFormGroup
-          idAria="single-example-aria"
           title={<h3>Single text field</h3>}
+          legend="Single text field"
           description={
             <Fragment>
-              When using this with a single form row where this text serves as
-              the help text for the input, it is a good idea to pass{' '}
-              <EuiCode>idAria=&quot;someID&quot;</EuiCode> to the form group and
-              pass
-              <EuiCode>describedByIds=&#123;[someID]&#125;</EuiCode> to its form
-              row.
+              A single text field that can be used to display additional text.
+              It can have{' '}
+              <EuiLink href="http://www.elastic.co" target="_blank">
+                links
+              </EuiLink>{' '}
+              or any other type of content.
             </Fragment>
           }>
-          <EuiFormRow
-            label="Text field"
-            describedByIds={['single-example-aria']}>
-            <EuiFieldText name="first" />
+          <EuiFormRow label="Text field">
+            <EuiFieldText name="first" aria-label="Example" />
           </EuiFormRow>
         </EuiDescribedFormGroup>
 
         <EuiDescribedFormGroup
-          idAria="no-description"
-          title={<h3>No description</h3>}>
-          <EuiFormRow label="Text field" describedByIds={['no-description']}>
+          title={<h3>No description</h3>}
+          legend="No description">
+          <EuiFormRow label="Text field">
             <EuiFieldText name="first" />
           </EuiFormRow>
         </EuiDescribedFormGroup>
 
         <EuiDescribedFormGroup
-          title={<strong>Multiple fields</strong>}
-          titleSize="m"
+          title={<h3>Multiple fields</h3>}
+          legend="Multiple fields"
           description="Here are three form rows. The first form row does not have a title.">
           <EuiFormRow
             hasEmptyLabelSpace
-            helpText={
-              <span>
-                We do not pass <EuiCode>describedByIds</EuiCode> when there are
-                multiple form rows.
-              </span>
-            }>
+            helpText={<span>This is a help text</span>}>
             <EuiSelect
               hasNoInitialSelection
               options={[
@@ -146,6 +140,7 @@ export default class extends Component {
 
         <EuiDescribedFormGroup
           title={<h2>Full width</h2>}
+          legend="Full width"
           titleSize="xxxs"
           description={
             <Fragment>

src-docs/src/views/form_layouts/form_layouts_example.js

@@ -9,6 +9,7 @@ import {
   EuiForm,
   EuiFormRow,
   EuiDescribedFormGroup,
+  EuiCallOut,
 } from '../../../../src/components';
 
 import FormRows from './form_rows';
@@ -116,13 +117,27 @@ export const FormLayoutsExample = {
         },
       ],
       text: (
-        <p>
-          Use <EuiCode>EuiDescribedFormGroup</EuiCode> component to associate
-          multiple <EuiCode>EuiFormRow</EuiCode>s. It can also simply be used
-          with one <EuiCode>EuiFormRow</EuiCode> as a way to display help text
-          (or additional text) next to the field instead of below (on mobile,
-          will revert to being stacked).
-        </p>
+        <div>
+          <p>
+            Use <EuiCode>EuiDescribedFormGroup</EuiCode> component to associate
+            multiple <EuiCode>EuiFormRow</EuiCode>s. It can also simply be used
+            with one <EuiCode>EuiFormRow</EuiCode> as a way to display
+            additional text next to the field (on mobile, it will revert to
+            being stacked).
+          </p>
+          <EuiCallOut
+            iconType="accessibility"
+            color="warning"
+            title={
+              <span>
+                In order for a described form group to be properly read as a
+                group with a title, add the <EuiCode>legend</EuiCode> prop. This
+                is only for accessibility, however, so it will be visibly
+                hidden.
+              </span>
+            }
+          />
+        </div>
       ),
       props: {
         EuiDescribedFormGroup,