From df70e7c825d89f54551794118d06c6fc509a48b7 Mon Sep 17 00:00:00 2001
From: Daniel <dlu@livefyre.com>
Date: Wed, 11 Mar 2020 12:37:14 -0700
Subject: [PATCH 1/5] Form docs

---
 packages/@react-spectrum/form/docs/Form.mdx | 224 ++++++++++++++++++++
 packages/@react-spectrum/form/src/Form.tsx  |   3 +
 packages/@react-types/form/src/index.d.ts   |  10 +
 3 files changed, 237 insertions(+)
 create mode 100644 packages/@react-spectrum/form/docs/Form.mdx

diff --git a/packages/@react-spectrum/form/docs/Form.mdx b/packages/@react-spectrum/form/docs/Form.mdx
new file mode 100644
index 00000000000..7d3fcbbbd7f
--- /dev/null
+++ b/packages/@react-spectrum/form/docs/Form.mdx
@@ -0,0 +1,224 @@
+<!-- Copyright 2020 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+Unless required by applicable law or agreed to in writing, software distributed under
+the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+OF ANY KIND, either express or implied. See the License for the specific language
+governing permissions and limitations under the License. -->
+
+import {Layout} from '@react-spectrum/docs';
+export default Layout;
+
+import docs from 'docs:@react-spectrum/form';
+import {HeaderInfo, PropTable} from '@react-spectrum/docs';
+import packageData from '../package.json';
+
+```jsx import
+ import {Checkbox} from '@react-spectrum/checkbox';
+ import {Form} from '@react-spectrum/form';
+ import {Radio, RadioGroup} from '@react-spectrum/radio';
+ import {TextField} from '@react-spectrum/textfield';
+ ```
+
+# Form
+
+<p>{docs.exports.Form.description}</p>
+
+<HeaderInfo
+ packageData={packageData}
+ componentNames={['Form']} />
+
+## Example
+
+```tsx example
+<h3 id="label-1">Login</h3>
+<Form width={400} aria-labelledby="label-1">
+  <TextField label="Email" placeholder="abc@adobe.com" />
+  <TextField label="Password" placeholder="1234" />
+  <Checkbox>Remember me</Checkbox>
+</Form>
+```
+
+## Content
+
+Form accepts one or more children to render as its form elements. Label alignment, positioning, and other [properties](#visual-options)
+are set on the Form itself and propagated to its children to generate a cohesive design. To override these top level Form props on individual children, 
+set them directly on the child instead.
+
+```tsx example
+<h3 id="label-2">Sign Up</h3>
+<Form width={400} aria-labelledby="label-2" isRequired necessityIndicator="label">
+  <TextField label="Name" placeholder="Bob Doe" />
+  <TextField label="Email" placeholder="abc@adobe.com" />
+  <TextField label="Address" placeholder="123 Any Street" isRequired={false} />
+</Form>
+```
+
+### Accessibility
+
+As per [W3 Form guidelines](https://www.w3.org/TR/wai-aria-practices/examples/landmarks/form.html), the controls provided to the form should 
+use native host semantics (`button`, `input`, `select`, `textarea`) whenever possible.
+
+## Labeling
+
+### Accessibility
+
+If a label is provided to the Form by adding either the `aria-label` or `aria-labelledby` prop, 
+the element will be identified to assistive technology as a form landmark region. 
+
+```tsx example
+<h3 id="label-3">Personal Information</h3>
+<Form width={400} aria-labelledby="label-3">
+  <TextField label="First Name" placeholder="Bob" />
+  <TextField label="Last Name" placeholder="Dole" />
+  <RadioGroup label="Favorite pet" name="favorite-pet-group">
+    <Radio value="dogs">Dogs</Radio>
+    <Radio value="cats">Cats</Radio>
+    <Radio value="dragons">Dragons</Radio>
+  </RadioGroup>
+</Form>
+```
+
+
+## Props
+
+<PropTable component={docs.exports.Form} links={docs.links} />
+
+## Visual Options
+
+### Label Position
+
+```tsx example
+<Form width={400} marginBottom="20px" labelPosition="top">
+  <TextField label="Name" placeholder="John Smith" />
+  <RadioGroup label="Favorite pet" name="favorite-pet-group">
+    <Radio value="dogs">Dogs</Radio>
+    <Radio value="cats">Cats</Radio>
+  </RadioGroup>
+</Form>
+
+<Form width={400} labelPosition="side">
+  <TextField label="Name" placeholder="John Smith" />
+  <RadioGroup label="Favorite pet" name="favorite-pet-group">
+    <Radio value="dogs">Dogs</Radio>
+    <Radio value="cats">Cats</Radio>
+  </RadioGroup>
+</Form>
+```
+
+### Label Alignment
+
+```tsx example
+<Form width={400} marginBottom="20px" labelAlign="start">
+  <TextField label="Name" placeholder="John Smith" />
+  <RadioGroup label="Favorite pet" name="favorite-pet-group">
+    <Radio value="dogs">Dogs</Radio>
+    <Radio value="cats">Cats</Radio>
+  </RadioGroup>
+</Form>
+
+<Form width={400} labelAlign="end">
+  <TextField label="Name" placeholder="John Smith" />
+  <RadioGroup label="Favorite pet" name="favorite-pet-group">
+    <Radio value="dogs">Dogs</Radio>
+    <Radio value="cats">Cats</Radio>
+  </RadioGroup>
+</Form>
+```
+
+### Quiet
+
+```tsx example
+<Form width={400} isQuiet>
+  <TextField label="Name" placeholder="John Smith" />
+  <RadioGroup label="Favorite pet" name="favorite-pet-group">
+    <Radio value="dogs">Dogs</Radio>
+    <Radio value="cats">Cats</Radio>
+  </RadioGroup>
+</Form>
+```
+
+### Emphasized
+
+```tsx example
+<Form width={400} isEmphasized>
+  <TextField label="Name" placeholder="John Smith" />
+  <RadioGroup label="Favorite pet" name="favorite-pet-group">
+    <Radio value="dogs">Dogs</Radio>
+    <Radio value="cats">Cats</Radio>
+  </RadioGroup>
+</Form>
+```
+
+### Disabled
+
+```tsx example
+<Form width={400} isDisabled>
+  <TextField label="Name" placeholder="John Smith" />
+  <RadioGroup label="Favorite pet" name="favorite-pet-group">
+    <Radio value="dogs">Dogs</Radio>
+    <Radio value="cats">Cats</Radio>
+  </RadioGroup>
+</Form>
+```
+
+### Required and Necessity Indicator
+
+```tsx example
+<Form width={400} marginBottom="20px" necessityIndicator="label">
+  <TextField label="Name" placeholder="John Smith" />
+  <RadioGroup label="Favorite pet" name="favorite-pet-group">
+    <Radio value="dogs">Dogs</Radio>
+    <Radio value="cats">Cats</Radio>
+  </RadioGroup>
+</Form>
+
+<Form width={400} marginBottom="20px" isRequired necessityIndicator="label">
+  <TextField label="Name" placeholder="John Smith" />
+  <RadioGroup label="Favorite pet" name="favorite-pet-group">
+    <Radio value="dogs">Dogs</Radio>
+    <Radio value="cats">Cats</Radio>
+  </RadioGroup>
+</Form>
+
+<Form width={400} isRequired necessityIndicator="icon">
+  <TextField label="Name" placeholder="John Smith" />
+  <RadioGroup label="Favorite pet" name="favorite-pet-group">
+    <Radio value="dogs">Dogs</Radio>
+    <Radio value="cats">Cats</Radio>
+  </RadioGroup>
+</Form>
+```
+
+### Read Only
+
+```tsx example
+<Form width={400} isReadOnly>
+  <TextField label="Name" placeholder="John Smith" />
+  <RadioGroup label="Favorite pet" name="favorite-pet-group">
+    <Radio value="dogs">Dogs</Radio>
+    <Radio value="cats">Cats</Radio>
+  </RadioGroup>
+</Form>
+```
+
+### Validation State
+
+```tsx example
+<Form width={400} marginBottom="20px" validationState="invalid">
+  <TextField label="Name" placeholder="John Smith" />
+  <RadioGroup label="Favorite pet" name="favorite-pet-group">
+    <Radio value="dogs">Dogs</Radio>
+    <Radio value="cats">Cats</Radio>
+  </RadioGroup>
+</Form>
+
+<Form validationState="valid">
+  <TextField label="Name" placeholder="John Smith" />
+  <RadioGroup label="Favorite pet" name="favorite-pet-group">
+    <Radio value="dogs">Dogs</Radio>
+    <Radio value="cats">Cats</Radio>
+  </RadioGroup>
+</Form>
+```
diff --git a/packages/@react-spectrum/form/src/Form.tsx b/packages/@react-spectrum/form/src/Form.tsx
index 0e851546f07..c3bc1ccaf27 100644
--- a/packages/@react-spectrum/form/src/Form.tsx
+++ b/packages/@react-spectrum/form/src/Form.tsx
@@ -79,5 +79,8 @@ function Form(props: SpectrumFormProps, ref: DOMRef<HTMLFormElement>) {
   );
 }
 
+/**
+ * Form provides unified structure, alignment, and styling for a user's form fields.
+ */
 const _Form = React.forwardRef(Form);
 export {_Form as Form};
diff --git a/packages/@react-types/form/src/index.d.ts b/packages/@react-types/form/src/index.d.ts
index 85b0f240bb7..c5131decc87 100644
--- a/packages/@react-types/form/src/index.d.ts
+++ b/packages/@react-types/form/src/index.d.ts
@@ -14,11 +14,21 @@ import {DOMProps, SpectrumLabelableProps, StyleProps, ValidationState} from '@re
 import {ReactElement} from 'react';
 
 export interface SpectrumFormProps extends DOMProps, StyleProps, SpectrumLabelableProps {
+  /** The contents of the form. */
   children: ReactElement<SpectrumLabelableProps> | ReactElement<SpectrumLabelableProps>[],
+  /** Whether the form elements are displayed with their quiet style. */
   isQuiet?: boolean,
+  /** Whether the form elements are rendered with their emphasized style (blue). */
   isEmphasized?: boolean,
+  /** Whether the form elements are disabled. */
   isDisabled?: boolean,
+  /** Whether user input is required on each of the form elements before form submission. */
   isRequired?: boolean,
+  /** Whether the form elements can be selected but not changed by the user. */
   isReadOnly?: boolean,
+  /** 
+   * Whether the form elements should display their "valid" or "invalid" visual styling. 
+   * @default "valid"
+   */
   validationState?: ValidationState
 }

From 5df54acc30238aa96f724d44a1f1e1255739b7de Mon Sep 17 00:00:00 2001
From: Daniel <dlu@livefyre.com>
Date: Wed, 11 Mar 2020 13:52:02 -0700
Subject: [PATCH 2/5] forgot an extra 400 width

---
 packages/@react-spectrum/form/docs/Form.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/@react-spectrum/form/docs/Form.mdx b/packages/@react-spectrum/form/docs/Form.mdx
index 7d3fcbbbd7f..dc5af5583f5 100644
--- a/packages/@react-spectrum/form/docs/Form.mdx
+++ b/packages/@react-spectrum/form/docs/Form.mdx
@@ -214,7 +214,7 @@ the element will be identified to assistive technology as a form landmark region
   </RadioGroup>
 </Form>
 
-<Form validationState="valid">
+<Form width={400} validationState="valid">
   <TextField label="Name" placeholder="John Smith" />
   <RadioGroup label="Favorite pet" name="favorite-pet-group">
     <Radio value="dogs">Dogs</Radio>

From f662c1f7388b0712be78893ce8905bcf49ee32b6 Mon Sep 17 00:00:00 2001
From: Daniel <dlu@livefyre.com>
Date: Tue, 17 Mar 2020 11:38:24 -0700
Subject: [PATCH 3/5] addressing review comments

---
 packages/@react-spectrum/form/docs/Form.mdx   | 2 +-
 packages/@react-types/checkbox/src/index.d.ts | 3 +--
 packages/@react-types/form/src/index.d.ts     | 2 +-
 packages/@react-types/switch/src/index.d.ts   | 3 +--
 4 files changed, 4 insertions(+), 6 deletions(-)

diff --git a/packages/@react-spectrum/form/docs/Form.mdx b/packages/@react-spectrum/form/docs/Form.mdx
index dc5af5583f5..058ef308c66 100644
--- a/packages/@react-spectrum/form/docs/Form.mdx
+++ b/packages/@react-spectrum/form/docs/Form.mdx
@@ -195,7 +195,7 @@ the element will be identified to assistive technology as a form landmark region
 
 ```tsx example
 <Form width={400} isReadOnly>
-  <TextField label="Name" placeholder="John Smith" />
+  <TextField label="Name" value="John Smith" />
   <RadioGroup label="Favorite pet" name="favorite-pet-group">
     <Radio value="dogs">Dogs</Radio>
     <Radio value="cats">Cats</Radio>
diff --git a/packages/@react-types/checkbox/src/index.d.ts b/packages/@react-types/checkbox/src/index.d.ts
index d45d8ab73ac..f439876d51d 100644
--- a/packages/@react-types/checkbox/src/index.d.ts
+++ b/packages/@react-types/checkbox/src/index.d.ts
@@ -32,8 +32,7 @@ export interface CheckboxProps extends CheckboxBase {
 
 export interface SpectrumCheckboxProps extends CheckboxProps, DOMProps, StyleProps {
   /**
-   * By default, checkboxes are not emphasized (gray).
-   * This prop sets the emphasized style (blue) which provides visual prominence.
+   * This prop sets the emphasized style which provides visual prominence.
    */
   isEmphasized?: boolean
 }
diff --git a/packages/@react-types/form/src/index.d.ts b/packages/@react-types/form/src/index.d.ts
index c5131decc87..16016ce3e12 100644
--- a/packages/@react-types/form/src/index.d.ts
+++ b/packages/@react-types/form/src/index.d.ts
@@ -18,7 +18,7 @@ export interface SpectrumFormProps extends DOMProps, StyleProps, SpectrumLabelab
   children: ReactElement<SpectrumLabelableProps> | ReactElement<SpectrumLabelableProps>[],
   /** Whether the form elements are displayed with their quiet style. */
   isQuiet?: boolean,
-  /** Whether the form elements are rendered with their emphasized style (blue). */
+  /** Whether the form elements are rendered with their emphasized style. */
   isEmphasized?: boolean,
   /** Whether the form elements are disabled. */
   isDisabled?: boolean,
diff --git a/packages/@react-types/switch/src/index.d.ts b/packages/@react-types/switch/src/index.d.ts
index 2f408910226..b1679ae556c 100644
--- a/packages/@react-types/switch/src/index.d.ts
+++ b/packages/@react-types/switch/src/index.d.ts
@@ -16,8 +16,7 @@ import {DOMProps, StyleProps} from '@react-types/shared';
 export type SwitchProps = CheckboxBase;
 export interface SpectrumSwitchProps extends SwitchProps, DOMProps, StyleProps {
   /**
-   * By default, switches are not emphasized (gray).
-   * This prop sets the emphasized style (blue) which provides visual prominence.
+   * This prop sets the emphasized style which provides visual prominence.
    * @default "false"
    */
   isEmphasized?: boolean

From 3d734a1ed73a7eb04e3bcbd489475d8be090dc63 Mon Sep 17 00:00:00 2001
From: Daniel <dlu@livefyre.com>
Date: Fri, 20 Mar 2020 16:31:47 -0700
Subject: [PATCH 4/5] addressing review comments

---
 packages/@react-spectrum/form/docs/Form.mdx | 22 ++++++++-------------
 packages/@react-types/form/src/index.d.ts   | 14 ++++++-------
 2 files changed, 15 insertions(+), 21 deletions(-)

diff --git a/packages/@react-spectrum/form/docs/Form.mdx b/packages/@react-spectrum/form/docs/Form.mdx
index 058ef308c66..7e2f2627b18 100644
--- a/packages/@react-spectrum/form/docs/Form.mdx
+++ b/packages/@react-spectrum/form/docs/Form.mdx
@@ -58,7 +58,8 @@ set them directly on the child instead.
 ### Accessibility
 
 As per [W3 Form guidelines](https://www.w3.org/TR/wai-aria-practices/examples/landmarks/form.html), the controls provided to the form should 
-use native host semantics (`button`, `input`, `select`, `textarea`) whenever possible.
+use native host semantics (`button`, `input`, `select`, `textarea`) whenever possible. React Spectrum components such as Button, TextField, and TextArea
+all satisfy this criteria.
 
 ## Labeling
 
@@ -87,10 +88,10 @@ the element will be identified to assistive technology as a form landmark region
 
 ## Visual Options
 
-### Label Position
+### Label Position and Label Alignment
 
 ```tsx example
-<Form width={400} marginBottom="20px" labelPosition="top">
+<Form width={400} marginBottom="20px" labelPosition="top" labelAlign="start">
   <TextField label="Name" placeholder="John Smith" />
   <RadioGroup label="Favorite pet" name="favorite-pet-group">
     <Radio value="dogs">Dogs</Radio>
@@ -98,19 +99,15 @@ the element will be identified to assistive technology as a form landmark region
   </RadioGroup>
 </Form>
 
-<Form width={400} labelPosition="side">
+<Form width={400} marginBottom="20px" labelPosition="top" labelAlign="end">
   <TextField label="Name" placeholder="John Smith" />
   <RadioGroup label="Favorite pet" name="favorite-pet-group">
     <Radio value="dogs">Dogs</Radio>
     <Radio value="cats">Cats</Radio>
   </RadioGroup>
 </Form>
-```
-
-### Label Alignment
 
-```tsx example
-<Form width={400} marginBottom="20px" labelAlign="start">
+<Form width={400} marginBottom="20px" labelPosition="side" labelAlign="start">
   <TextField label="Name" placeholder="John Smith" />
   <RadioGroup label="Favorite pet" name="favorite-pet-group">
     <Radio value="dogs">Dogs</Radio>
@@ -118,7 +115,7 @@ the element will be identified to assistive technology as a form landmark region
   </RadioGroup>
 </Form>
 
-<Form width={400} labelAlign="end">
+<Form width={400} marginBottom="20px" labelPosition="side" labelAlign="end">
   <TextField label="Name" placeholder="John Smith" />
   <RadioGroup label="Favorite pet" name="favorite-pet-group">
     <Radio value="dogs">Dogs</Radio>
@@ -132,10 +129,7 @@ the element will be identified to assistive technology as a form landmark region
 ```tsx example
 <Form width={400} isQuiet>
   <TextField label="Name" placeholder="John Smith" />
-  <RadioGroup label="Favorite pet" name="favorite-pet-group">
-    <Radio value="dogs">Dogs</Radio>
-    <Radio value="cats">Cats</Radio>
-  </RadioGroup>
+  <TextField label="Address" placeholder="123 Any Street" />
 </Form>
 ```
 
diff --git a/packages/@react-types/form/src/index.d.ts b/packages/@react-types/form/src/index.d.ts
index 16016ce3e12..2b27fe3be54 100644
--- a/packages/@react-types/form/src/index.d.ts
+++ b/packages/@react-types/form/src/index.d.ts
@@ -14,20 +14,20 @@ import {DOMProps, SpectrumLabelableProps, StyleProps, ValidationState} from '@re
 import {ReactElement} from 'react';
 
 export interface SpectrumFormProps extends DOMProps, StyleProps, SpectrumLabelableProps {
-  /** The contents of the form. */
+  /** The contents of the Form. */
   children: ReactElement<SpectrumLabelableProps> | ReactElement<SpectrumLabelableProps>[],
-  /** Whether the form elements are displayed with their quiet style. */
+  /** Whether the Form elements are displayed with their quiet style. */
   isQuiet?: boolean,
-  /** Whether the form elements are rendered with their emphasized style. */
+  /** Whether the Form elements are rendered with their emphasized style. */
   isEmphasized?: boolean,
-  /** Whether the form elements are disabled. */
+  /** Whether the Form elements are disabled. */
   isDisabled?: boolean,
-  /** Whether user input is required on each of the form elements before form submission. */
+  /** Whether user input is required on each of the Form elements before Form submission. */
   isRequired?: boolean,
-  /** Whether the form elements can be selected but not changed by the user. */
+  /** Whether the Form elements can be selected but not changed by the user. */
   isReadOnly?: boolean,
   /** 
-   * Whether the form elements should display their "valid" or "invalid" visual styling. 
+   * Whether the Form elements should display their "valid" or "invalid" visual styling. 
    * @default "valid"
    */
   validationState?: ValidationState

From 3a0535312c9144436b3800114011f89f841db0ca Mon Sep 17 00:00:00 2001
From: Daniel <dlu@livefyre.com>
Date: Mon, 23 Mar 2020 13:39:17 -0700
Subject: [PATCH 5/5] Adding aria labels and updating labeling accessibility
 section

---
 packages/@react-spectrum/form/docs/Form.mdx | 30 ++++++++++-----------
 1 file changed, 15 insertions(+), 15 deletions(-)

diff --git a/packages/@react-spectrum/form/docs/Form.mdx b/packages/@react-spectrum/form/docs/Form.mdx
index 7e2f2627b18..0967c6c938e 100644
--- a/packages/@react-spectrum/form/docs/Form.mdx
+++ b/packages/@react-spectrum/form/docs/Form.mdx
@@ -65,8 +65,8 @@ all satisfy this criteria.
 
 ### Accessibility
 
-If a label is provided to the Form by adding either the `aria-label` or `aria-labelledby` prop, 
-the element will be identified to assistive technology as a form landmark region. 
+A label should be provided to the Form by adding either the `aria-label` or `aria-labelledby` prop, so that the element will be identified to assistive
+technology as a form landmark region to which assistive technology can navigate to.
 
 ```tsx example
 <h3 id="label-3">Personal Information</h3>
@@ -91,7 +91,7 @@ the element will be identified to assistive technology as a form landmark region
 ### Label Position and Label Alignment
 
 ```tsx example
-<Form width={400} marginBottom="20px" labelPosition="top" labelAlign="start">
+<Form labelPosition="top" labelAlign="start" aria-label="Form example: label position=top, label alignment=start " width={400} marginBottom="20px">
   <TextField label="Name" placeholder="John Smith" />
   <RadioGroup label="Favorite pet" name="favorite-pet-group">
     <Radio value="dogs">Dogs</Radio>
@@ -99,7 +99,7 @@ the element will be identified to assistive technology as a form landmark region
   </RadioGroup>
 </Form>
 
-<Form width={400} marginBottom="20px" labelPosition="top" labelAlign="end">
+<Form labelPosition="top" labelAlign="end" aria-label="Form example: label position=top, label alignment=end" width={400} marginBottom="20px">
   <TextField label="Name" placeholder="John Smith" />
   <RadioGroup label="Favorite pet" name="favorite-pet-group">
     <Radio value="dogs">Dogs</Radio>
@@ -107,7 +107,7 @@ the element will be identified to assistive technology as a form landmark region
   </RadioGroup>
 </Form>
 
-<Form width={400} marginBottom="20px" labelPosition="side" labelAlign="start">
+<Form labelPosition="side" labelAlign="start" aria-label="Form example: label position=side, label alignment=start" width={400} marginBottom="20px">
   <TextField label="Name" placeholder="John Smith" />
   <RadioGroup label="Favorite pet" name="favorite-pet-group">
     <Radio value="dogs">Dogs</Radio>
@@ -115,7 +115,7 @@ the element will be identified to assistive technology as a form landmark region
   </RadioGroup>
 </Form>
 
-<Form width={400} marginBottom="20px" labelPosition="side" labelAlign="end">
+<Form labelPosition="side" labelAlign="end" aria-label="Form example: label position=side, label alignment=end" width={400} marginBottom="20px">
   <TextField label="Name" placeholder="John Smith" />
   <RadioGroup label="Favorite pet" name="favorite-pet-group">
     <Radio value="dogs">Dogs</Radio>
@@ -127,7 +127,7 @@ the element will be identified to assistive technology as a form landmark region
 ### Quiet
 
 ```tsx example
-<Form width={400} isQuiet>
+<Form isQuiet aria-label="Form example: isQuiet" width={400}>
   <TextField label="Name" placeholder="John Smith" />
   <TextField label="Address" placeholder="123 Any Street" />
 </Form>
@@ -136,7 +136,7 @@ the element will be identified to assistive technology as a form landmark region
 ### Emphasized
 
 ```tsx example
-<Form width={400} isEmphasized>
+<Form isEmphasized aria-label="Form example: isEmphasized" width={400}>
   <TextField label="Name" placeholder="John Smith" />
   <RadioGroup label="Favorite pet" name="favorite-pet-group">
     <Radio value="dogs">Dogs</Radio>
@@ -148,7 +148,7 @@ the element will be identified to assistive technology as a form landmark region
 ### Disabled
 
 ```tsx example
-<Form width={400} isDisabled>
+<Form isDisabled aria-label="Form example: isDisabled" width={400}>
   <TextField label="Name" placeholder="John Smith" />
   <RadioGroup label="Favorite pet" name="favorite-pet-group">
     <Radio value="dogs">Dogs</Radio>
@@ -160,7 +160,7 @@ the element will be identified to assistive technology as a form landmark region
 ### Required and Necessity Indicator
 
 ```tsx example
-<Form width={400} marginBottom="20px" necessityIndicator="label">
+<Form necessityIndicator="label" aria-label="Form example: optional with necessityIndicator=label" width={400} marginBottom="20px">
   <TextField label="Name" placeholder="John Smith" />
   <RadioGroup label="Favorite pet" name="favorite-pet-group">
     <Radio value="dogs">Dogs</Radio>
@@ -168,7 +168,7 @@ the element will be identified to assistive technology as a form landmark region
   </RadioGroup>
 </Form>
 
-<Form width={400} marginBottom="20px" isRequired necessityIndicator="label">
+<Form isRequired necessityIndicator="label" aria-label="Form example: isRequired with necessityIndicator=label" width={400} marginBottom="20px">
   <TextField label="Name" placeholder="John Smith" />
   <RadioGroup label="Favorite pet" name="favorite-pet-group">
     <Radio value="dogs">Dogs</Radio>
@@ -176,7 +176,7 @@ the element will be identified to assistive technology as a form landmark region
   </RadioGroup>
 </Form>
 
-<Form width={400} isRequired necessityIndicator="icon">
+<Form isRequired necessityIndicator="icon" aria-label="Form example: isRequired with necessityIndicator=icon" width={400} >
   <TextField label="Name" placeholder="John Smith" />
   <RadioGroup label="Favorite pet" name="favorite-pet-group">
     <Radio value="dogs">Dogs</Radio>
@@ -188,7 +188,7 @@ the element will be identified to assistive technology as a form landmark region
 ### Read Only
 
 ```tsx example
-<Form width={400} isReadOnly>
+<Form isReadOnly aria-label="Form example: isReadOnly" width={400}>
   <TextField label="Name" value="John Smith" />
   <RadioGroup label="Favorite pet" name="favorite-pet-group">
     <Radio value="dogs">Dogs</Radio>
@@ -200,7 +200,7 @@ the element will be identified to assistive technology as a form landmark region
 ### Validation State
 
 ```tsx example
-<Form width={400} marginBottom="20px" validationState="invalid">
+<Form validationState="invalid" aria-label="Form example: validationState=invalid" width={400} marginBottom="20px">
   <TextField label="Name" placeholder="John Smith" />
   <RadioGroup label="Favorite pet" name="favorite-pet-group">
     <Radio value="dogs">Dogs</Radio>
@@ -208,7 +208,7 @@ the element will be identified to assistive technology as a form landmark region
   </RadioGroup>
 </Form>
 
-<Form width={400} validationState="valid">
+<Form validationState="valid" aria-label="Form example: validationState=valid" width={400}>
   <TextField label="Name" placeholder="John Smith" />
   <RadioGroup label="Favorite pet" name="favorite-pet-group">
     <Radio value="dogs">Dogs</Radio>