From f3f32dd466ff1976c19fb3485af1c836654eafa8 Mon Sep 17 00:00:00 2001
From: William Stanton <william.stanton@workday.com>
Date: Wed, 19 Nov 2025 15:13:37 -0500
Subject: [PATCH 01/10] docs: Accessibility for FormField and TextInput

---
 .../react/form-field/stories/FormField.mdx    | 158 ++++++++++++------
 .../form-field/stories/examples/Caution.tsx   |  10 +-
 .../form-field/stories/examples/Error.tsx     |   2 +-
 .../stories/examples/GroupedInputs.tsx        |   4 +-
 .../react/text-input/stories/TextInput.mdx    |  56 ++++++-
 5 files changed, 162 insertions(+), 68 deletions(-)

diff --git a/modules/react/form-field/stories/FormField.mdx b/modules/react/form-field/stories/FormField.mdx
index 2bac266a32..0d1b0e4c17 100644
--- a/modules/react/form-field/stories/FormField.mdx
+++ b/modules/react/form-field/stories/FormField.mdx
@@ -1,22 +1,22 @@
 import {ExampleCodeBlock, Specifications, SymbolDoc} from '@workday/canvas-kit-docs';
 import * as FormFieldStories from './FormField.stories';
 
-import { Basic } from './examples/Basic';
-import { Caution } from './examples/Caution';
-import { Error } from './examples/Error';
-import { Disabled } from './examples/Disabled';
-import { HiddenLabel } from './examples/HiddenLabel';
-import { LabelPositionHorizontalStart } from './examples/LabelPositionHorizontalStart';
-import { LabelPositionHorizontalEnd } from './examples/LabelPositionHorizontalEnd';
-import { RefForwarding } from './examples/RefForwarding';
-import { Required } from './examples/Required';
-import { Custom } from './examples/Custom';
-import { CustomId } from './examples/CustomId';
-import { AllFields } from './examples/AllFields';
-import { Hint } from './examples/Hint';
-import { Grow } from './examples/Grow';
-import { ThemedError } from './examples/ThemedErrors';
-import { GroupedInputs } from './examples/GroupedInputs';
+import {Basic} from './examples/Basic';
+import {Caution} from './examples/Caution';
+import {Error} from './examples/Error';
+import {Disabled} from './examples/Disabled';
+import {HiddenLabel} from './examples/HiddenLabel';
+import {LabelPositionHorizontalStart} from './examples/LabelPositionHorizontalStart';
+import {LabelPositionHorizontalEnd} from './examples/LabelPositionHorizontalEnd';
+import {RefForwarding} from './examples/RefForwarding';
+import {Required} from './examples/Required';
+import {Custom} from './examples/Custom';
+import {CustomId} from './examples/CustomId';
+import {AllFields} from './examples/AllFields';
+import {Hint} from './examples/Hint';
+import {Grow} from './examples/Grow';
+import {ThemedError} from './examples/ThemedErrors';
+import {GroupedInputs} from './examples/GroupedInputs';
 
 <Meta of={FormFieldStories} />
 
@@ -31,43 +31,6 @@ by passing in `TextInput`, `Select`, `RadioGroup` and other form elements to `Fo
 yarn add @workday/canvas-kit-react
 ```
 
-## Accessibility
-
-The `FormField` adds a `for` attribute to the `FormField.Label` (`<label>` element) element that
-matches the `id` attribute of the `FormField.Input` which is usually a `input` element. This both
-labels the input for screen readers and other assitive technology as well as will focus on the input
-when the user clicks on the label. If your form field input component is more complicated, the
-`FormField` will also add an `id` to the `FormField.Label` and an `aria-labelledby` to the
-`FormField.Input` component. You can then forward the `aria-labelledby` to whatever elements you
-need for the proper accessibility.
-
-For example, the DOM will look something like this:
-
-```html
-<div>
-  <label id="label-abc" for="input-abc">First Name</label>
-  <input id="input-abc" aria-labelledby="label-abc" />
-</div>
-```
-
-Some components, like `MultiSelect`, have an additional `role=listbox` element that also needs to
-link to the `label` element. The resulting DOM will look something like:
-
-```html
-<div>
-  <label id="label-abc" for="input-abc">States you've lived in</label>
-  <input id="input-abc" aria-labelledby="label-abc" role="combobox" ... />
-  <ul role="listbox" aria-labelledby="label-abc">
-    <li>Texas</li>
-    <li>California</li>
-  </ul>
-</div>
-```
-
-The `MultiSelect` component gets the `aria-labelledby` from the `FormField.Input` and forwards it to
-both the `input[role=combobox]` element and the `ul[role=listbox]` element so the screen reader
-knows the label for both is "States you've lived in".
-
 ## Usage
 
 ### Basic
@@ -90,18 +53,32 @@ Use the caution state when a value is valid but there is additional information.
 
 <ExampleCodeBlock code={Caution} />
 
+> **Accessibility Note**: Caution state **will not** include the `aria-invalid` attribute on the
+> input for screen readers. Use error states when values are not valid.
+
 ### Error
 
 Use the error state when the value is no longer valid.
 
 <ExampleCodeBlock code={Error} />
 
+> **Accessibility Note**: Error states include visual color changes to the input border and
+> **require** supplemental "error" text for colorblind users to distinguish between fields in an
+> error state from fields with standard hint text. Read more about
+> [Failure of Success Criterion 1.4.1 due to identifying required or error fields using color differences only](https://www.w3.org/WAI/WCAG22/Techniques/failures/F81)
+
 ### Disabled
 
 Set the `disabled` prop of `FormField.Input` to prevent users from interacting with it.
 
 <ExampleCodeBlock code={Disabled} />
 
+> **Accessibility Note**: Disabled form elements are exempt from
+> [WCAG minimum contrast guidelines](https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html).
+> Despite this exemption, disabled fields are more difficult for low vision and colorblind users to
+> perceive and may harm the usability of the form. Consider using text elements instead, or
+> read-only fields if users cannot modify data.
+
 ### Hint
 
 Use `FormField.Hint` to display a short message below the input component and `FormField.Field` to
@@ -109,6 +86,10 @@ ensure proper alignment.
 
 <ExampleCodeBlock code={Hint} />
 
+> **Accessibility Note**: Hints are automatically associated to the input field with the
+> `aria-describedby` attribute. This ensures that screen readers can automatically announce the hint
+> text to users when the input field is focused.
+
 ### Label Position
 
 Set the `orientation` prop of the Form Field to designate the position of the label relative to the
@@ -149,12 +130,16 @@ for required fields are suffixed by a red asterisk.
 
 <ExampleCodeBlock code={Required} />
 
+> **Accessibility Note**: The HTML `required` attribute is automatically added to the input field
+> and announced by screen readers. Consider adding a note at the top of your form indicating that
+> fields marked with an asterisk (\*) are required. This provides context for all users.
+
 ### Grouped Inputs
 
 Use `FormFieldGroup` when you have a group of inputs that need to be associated to one another, like
 `RadioGroup` or a group of `Checkbox`'s. `FormFieldGroup` renders a `fieldset` element and
-`FormFieldGroup.Label` renders a `legend` element. These elements will allow for correct
-accessibility of grouped inputs.
+`FormFieldGroup.Label` renders a `legend` element. These elements will allow screen readers to
+automatically announce the legend's context when focusing on the inputs in the group.
 
 `FormFieldGroup` supports the same props of `FormField`:
 
@@ -164,6 +149,11 @@ accessibility of grouped inputs.
 
 <ExampleCodeBlock code={GroupedInputs} />
 
+> **Accessibility Note**: In addition to radio button and checkbox groups, `FormFieldGroup` can be
+> useful in any situation where the form needs to have multiple sets of identical input fields. For
+> example, a form with identical fields for a Shipping address and a Billing address. The legend
+> provides critical context for screen reader users in these situations.
+
 ### Custom
 
 If you need full customization you can use the `FormField` behavior hooks to build your own
@@ -207,6 +197,64 @@ Form Field and its subcomponents support custom styling via the `cs` prop. For m
 check our
 ["How To Customize Styles"](https://workday.github.io/canvas-kit/?path=/docs/styling-guides-customizing-styles--docs).
 
+## Accessibility
+
+`FormField` provides essential accessibility features to ensure form inputs are properly labeled and
+described for all users, including those using assistive technologies. This section covers both the
+technical implementation and best practices for creating accessible forms.
+
+### Label Association
+
+The `FormField` adds a `for` attribute to the `FormField.Label` (`<label>` element) element that
+matches the `id` attribute of the `FormField.Input` which is usually a `input` element. This both
+labels the input for screen readers and other assistive technology as well as will focus on the
+input when the user clicks on the label. If your form field input component is more complicated, the
+`FormField` will also add an `id` to the `FormField.Label` and an `aria-labelledby` to the
+`FormField.Input` component. You can then forward the `aria-labelledby` to whatever elements you
+need for the proper accessibility.
+
+For example, the DOM will look something like this:
+
+```html
+<div>
+  <label id="label-abc" for="input-abc">First Name</label>
+  <input id="input-abc" aria-labelledby="label-abc" />
+</div>
+```
+
+Some components, like `MultiSelect`, have an additional `role=listbox` element that also needs to
+link to the `label` element. The resulting DOM will look something like:
+
+```html
+<div>
+  <label id="label-abc" for="input-abc">States you've lived in</label>
+  <input id="input-abc" aria-labelledby="label-abc" role="combobox" ... />
+  <ul role="listbox" aria-labelledby="label-abc">
+    <li>Texas</li>
+    <li>California</li>
+  </ul>
+</div>
+```
+
+The `MultiSelect` component gets the `aria-labelledby` from the `FormField.Input` and forwards it to
+both the `input[role=combobox]` element and the `ul[role=listbox]` element so the screen reader
+knows the label for both is "States you've lived in".
+
+### Label Text Best Practices
+
+- **Be Clear and Concise**: Labels should clearly describe the purpose of the input field.
+- **Use Visible Labels Instead of Only Placeholders**: Always provide a persistent and accessible
+  label with `FormField.Label`. Do not rely solely on placeholder text, as it can disappear while
+  typing and may not be accessible to assistive technologies. Use the `isHidden` prop on
+  `FormField.Label` if a hidden label is required for visual design.
+
+### Screen Reader Experience
+
+- The label is announced when the input receives focus.
+- Required, disabled, and invalid statuses are announced automatically.
+- Help text and error messages are announced automatically when focused.
+- For grouped inputs, the group label (`legend`) is announced automatically when focused.
+
 ## Component API
 
 <SymbolDoc name="FormField" />
diff --git a/modules/react/form-field/stories/examples/Caution.tsx b/modules/react/form-field/stories/examples/Caution.tsx
index 84617ef189..8f761f1d6f 100644
--- a/modules/react/form-field/stories/examples/Caution.tsx
+++ b/modules/react/form-field/stories/examples/Caution.tsx
@@ -4,7 +4,7 @@ import {TextInput} from '@workday/canvas-kit-react/text-input';
 import {Flex} from '@workday/canvas-kit-react/layout';
 
 export const Caution = () => {
-  const [value, setValue] = React.useState('');
+  const [value, setValue] = React.useState('hi');
 
   const handleChange = (event: React.ChangeEvent<HTMLInputElement>) => {
     setValue(event.target.value);
@@ -13,10 +13,12 @@ export const Caution = () => {
   return (
     <Flex>
       <FormField error="caution">
-        <FormField.Label>First Name</FormField.Label>
+        <FormField.Label>Create Password</FormField.Label>
         <FormField.Field>
-          <FormField.Input as={TextInput} value={value} onChange={handleChange} />
-          <FormField.Hint>Cannot contain numbers</FormField.Hint>
+          <FormField.Input as={TextInput} type="password" value={value} onChange={handleChange} />
+          <FormField.Hint>
+            Alert: Password strength is weak, using more characters is recommended.
+          </FormField.Hint>
         </FormField.Field>
       </FormField>
     </Flex>
diff --git a/modules/react/form-field/stories/examples/Error.tsx b/modules/react/form-field/stories/examples/Error.tsx
index dc346a6161..4f64a60684 100644
--- a/modules/react/form-field/stories/examples/Error.tsx
+++ b/modules/react/form-field/stories/examples/Error.tsx
@@ -17,7 +17,7 @@ export const Error = () => {
         <FormField.Label>Password</FormField.Label>
         <FormField.Field>
           <FormField.Input as={TextInput} type="password" value={value} onChange={handleChange} />
-          <FormField.Hint>Must Contain a number and a capital letter</FormField.Hint>
+          <FormField.Hint>Error: Must Contain a number and a capital letter</FormField.Hint>
         </FormField.Field>
       </FormField>
     </Flex>
diff --git a/modules/react/form-field/stories/examples/GroupedInputs.tsx b/modules/react/form-field/stories/examples/GroupedInputs.tsx
index 705691737c..f9528a71b5 100644
--- a/modules/react/form-field/stories/examples/GroupedInputs.tsx
+++ b/modules/react/form-field/stories/examples/GroupedInputs.tsx
@@ -160,7 +160,7 @@ export const GroupedInputs = () => {
             })}
           </FormFieldGroup.List>
           <FormFieldGroup.Hint>
-            {error === 'error' && 'You must choose one topping'}
+            {error === 'error' && 'Error: You must choose one topping'}
           </FormFieldGroup.Hint>
         </FormFieldGroup>
         <FormFieldGroup error={radioError} isRequired>
@@ -186,7 +186,7 @@ export const GroupedInputs = () => {
               </FormFieldGroup.Input>
             </FormFieldGroup.List>
             <FormFieldGroup.Hint>
-              {radioError === 'error' ? 'You must choose a crust' : null}
+              {radioError === 'error' ? 'Error: You must choose a crust' : null}
             </FormFieldGroup.Hint>
           </FormFieldGroup.Field>
         </FormFieldGroup>
diff --git a/modules/react/text-input/stories/TextInput.mdx b/modules/react/text-input/stories/TextInput.mdx
index 340fbf2599..5c0632b8a4 100644
--- a/modules/react/text-input/stories/TextInput.mdx
+++ b/modules/react/text-input/stories/TextInput.mdx
@@ -35,8 +35,8 @@ yarn add @workday/canvas-kit-react
 
 ### Basic Example
 
-Text Input should be used in tandem with [Form Field](/components/inputs/form-field/) to meet
-accessibility standards.
+Text Input should be used in tandem with [Form Field](/components/inputs/form-field/) to ensure
+proper label association and screen reader support.
 
 <ExampleCodeBlock code={Basic} />
 
@@ -53,6 +53,12 @@ before a value has been provided.
 
 <ExampleCodeBlock code={Placeholder} />
 
+> **Accessibility Note**: Always provide a persistent `FormField.Label` and never rely on
+> placeholder text as the only label for an input. Placeholders can disappear or lack sufficient
+> contrast, making them unreliable for screen readers. Use placeholders only for short format
+> examples (e.g., "name@example.com"), and place detailed instructions or guidance in
+> `FormField.Hint` instead of the placeholder.
+
 ### Ref Forwarding
 
 Text Input supports [ref forwarding](https://reactjs.org/docs/forwarding-refs.html). It will forward
@@ -100,12 +106,15 @@ method to change width. The `width` prop is used to correctly position other inn
 
 <ExampleCodeBlock code={Icons} />
 
+> **Accessibility Note**: In this example, the mail icon is decorative and hidden from screen
+> readers. If icons are used for conveying meaning in addition to the label text, a text alternative
+> must be provided for screen readers.
+
 ### Error States
 
-Set the `error` prop of the wrapping Form Field to `"caution"` or
-`"error"` to set the Text Input to the Caution or Error state, respectively. You
-will also need to set the `hintId` and `hintText` props on the Form Field to meet accessibility
-standards.
+Set the `error` prop of the wrapping Form Field to `"caution"` or `"error"` to set the Text Input to
+the Caution or Error state, respectively. You will also need to set the `hintId` and `hintText`
+props on the Form Field to meet accessibility standards.
 
 The `error` prop may be applied directly to the Text Input with a value of
 `TextInput.ErrorType.Caution` or `TextInput.ErrorType.Error` if Form Field is not being used.
@@ -118,6 +127,41 @@ The `error` prop may be applied directly to the Text Input with a value of
 
 <ExampleCodeBlock code={Error} />
 
+## Accessibility
+
+`TextInput` should be used with [Form Field](?path=/docs/components-inputs-form-field--docs) to
+ensure proper labeling, error handling, and help text association. See
+[FormField's accessibility documentation](?path=/docs/components-inputs-form-field--docs#accessibility)
+for comprehensive guidance on form accessibility best practices.
+
+### Autocomplete Attribute
+
+- Add appropriate `autoComplete` values to indicate the input's purpose (e.g., `"email"`, `"name"`,
+  `"street-address"`, `"tel"`). Read more about
+  [Identify Input Purpose](https://www.w3.org/WAI/WCAG22/Understanding/identify-input-purpose.html).
+- Autocomplete enables browser autofill and helps assistive technologies understand the field's
+  purpose, benefiting users with cognitive disabilities and motor impairments.
+- Autocomplete also helps password managers identify the correct fields.
+
+### Input Type for Mobile Keyboards
+
+While `TextInput` renders `<input type="text">`, consider using specialized input types for better
+mobile keyboard support:
+
+- `type="email"` for email addresses (shows @ key on mobile keyboards)
+- `type="tel"` for phone numbers (shows numeric keypad on mobile)
+- `type="url"` for web addresses (shows .com key on mobile keyboards)
+- `type="search"` for search inputs (shows search icon and enables search-specific behaviors)
+
+### Screen Reader Experience
+
+When properly implemented with `FormField`, screen readers will announce:
+
+- The label text when the input receives focus.
+- Required, disabled, or read-only status.
+- Help text and error messages (via `aria-describedby`).
+- The current value or "blank" if empty.
+
 ## Component API
 
 <SymbolDoc name="TextInput" fileName="/react/" />

From 2b90c7537bb6e8642b9446e7346391b2e6cfd7cd Mon Sep 17 00:00:00 2001
From: William Stanton <william.stanton@workday.com>
Date: Wed, 19 Nov 2025 15:37:34 -0500
Subject: [PATCH 02/10] docs: Deleting Error & Caution from TextInput

Reducing redundancy in the Error & Caution docs. Making FormField the single source of truth.
---
 .../react/text-input/stories/TextInput.mdx    | 29 ++++---------------
 .../text-input/stories/TextInput.stories.ts   |  8 -----
 .../text-input/stories/examples/Caution.tsx   | 21 --------------
 .../text-input/stories/examples/Error.tsx     | 21 --------------
 4 files changed, 6 insertions(+), 73 deletions(-)
 delete mode 100644 modules/react/text-input/stories/examples/Caution.tsx
 delete mode 100644 modules/react/text-input/stories/examples/Error.tsx

diff --git a/modules/react/text-input/stories/TextInput.mdx b/modules/react/text-input/stories/TextInput.mdx
index 5c0632b8a4..d00d84d72f 100644
--- a/modules/react/text-input/stories/TextInput.mdx
+++ b/modules/react/text-input/stories/TextInput.mdx
@@ -4,10 +4,8 @@ import {
   SymbolDoc,
   Specifications,
 } from '@workday/canvas-kit-docs';
-import {Caution} from './examples/Caution';
 import {Basic} from './examples/Basic';
 import {Disabled} from './examples/Disabled';
-import {Error} from './examples/Error';
 import {Grow} from './examples/Grow';
 import {LabelPosition} from './examples/LabelPosition';
 import {Placeholder} from './examples/Placeholder';
@@ -112,20 +110,10 @@ method to change width. The `width` prop is used to correctly position other inn
 
 ### Error States
 
-Set the `error` prop of the wrapping Form Field to `"caution"` or `"error"` to set the Text Input to
-the Caution or Error state, respectively. You will also need to set the `hintId` and `hintText`
-props on the Form Field to meet accessibility standards.
-
-The `error` prop may be applied directly to the Text Input with a value of
-`TextInput.ErrorType.Caution` or `TextInput.ErrorType.Error` if Form Field is not being used.
-
-#### Caution
-
-<ExampleCodeBlock code={Caution} />
-
-#### Error
-
-<ExampleCodeBlock code={Error} />
+Form Field provides error and caution states for Text Input. Set the `error` prop on Form Field to
+`"error"` or `"caution"` and use `FormField.Hint` to provide error messages. See
+[Form Field's Error documentation](?path=/docs/components-inputs-form-field--docs#error-states) for
+examples and accessibility guidance.
 
 ## Accessibility
 
@@ -145,13 +133,8 @@ for comprehensive guidance on form accessibility best practices.
 
 ### Input Type for Mobile Keyboards
 
-While `TextInput` renders `<input type="text">`, consider using specialized input types for better
-mobile keyboard support:
-
-- `type="email"` for email addresses (shows @ key on mobile keyboards)
-- `type="tel"` for phone numbers (shows numeric keypad on mobile)
-- `type="url"` for web addresses (shows .com key on mobile keyboards)
-- `type="search"` for search inputs (shows search icon and enables search-specific behaviors)
+`TextInput` defaults to `<input type="text">`, but for better mobile keyboard support, use more
+specific `type` attributes (like `"email"`, `"tel"`, `"url"`, or `"search"`) as needed.
 
 ### Screen Reader Experience
 
diff --git a/modules/react/text-input/stories/TextInput.stories.ts b/modules/react/text-input/stories/TextInput.stories.ts
index f854d9d5c2..abe303fa66 100644
--- a/modules/react/text-input/stories/TextInput.stories.ts
+++ b/modules/react/text-input/stories/TextInput.stories.ts
@@ -4,10 +4,8 @@ import mdxDoc from './TextInput.mdx';
 
 import {TextInput} from '@workday/canvas-kit-react/text-input';
 
-import {Caution as CautionExample} from './examples/Caution';
 import {Basic as BasicExample} from './examples/Basic';
 import {Disabled as DisabledExample} from './examples/Disabled';
-import {Error as ErrorExample} from './examples/Error';
 import {Grow as GrowExample} from './examples/Grow';
 import {LabelPosition as LabelPositionExample} from './examples/LabelPosition';
 import {Placeholder as PlaceholderExample} from './examples/Placeholder';
@@ -28,18 +26,12 @@ export default {
 
 type Story = StoryObj<typeof TextInput>;
 
-export const Caution: Story = {
-  render: CautionExample,
-};
 export const Basic: Story = {
   render: BasicExample,
 };
 export const Disabled: Story = {
   render: DisabledExample,
 };
-export const Error: Story = {
-  render: ErrorExample,
-};
 export const Grow: Story = {
   render: GrowExample,
 };
diff --git a/modules/react/text-input/stories/examples/Caution.tsx b/modules/react/text-input/stories/examples/Caution.tsx
deleted file mode 100644
index bfdbf0b66f..0000000000
--- a/modules/react/text-input/stories/examples/Caution.tsx
+++ /dev/null
@@ -1,21 +0,0 @@
-import React from 'react';
-import {FormField} from '@workday/canvas-kit-react/form-field';
-import {TextInput} from '@workday/canvas-kit-react/text-input';
-
-export const Caution = () => {
-  const [value, setValue] = React.useState('invalid@email');
-
-  const handleChange = (event: React.ChangeEvent<HTMLInputElement>) => {
-    setValue(event.target.value);
-  };
-
-  return (
-    <FormField error="caution">
-      <FormField.Label>Email</FormField.Label>
-      <FormField.Field>
-        <FormField.Input as={TextInput} onChange={handleChange} value={value} />
-        <FormField.Hint>Please enter a valid email.</FormField.Hint>
-      </FormField.Field>
-    </FormField>
-  );
-};
diff --git a/modules/react/text-input/stories/examples/Error.tsx b/modules/react/text-input/stories/examples/Error.tsx
deleted file mode 100644
index 7f453e274e..0000000000
--- a/modules/react/text-input/stories/examples/Error.tsx
+++ /dev/null
@@ -1,21 +0,0 @@
-import React from 'react';
-import {FormField} from '@workday/canvas-kit-react/form-field';
-import {TextInput} from '@workday/canvas-kit-react/text-input';
-
-export const Error = () => {
-  const [value, setValue] = React.useState('invalid@email');
-
-  const handleChange = (event: React.ChangeEvent<HTMLInputElement>) => {
-    setValue(event.target.value);
-  };
-
-  return (
-    <FormField error="error">
-      <FormField.Label>Email</FormField.Label>
-      <FormField.Field>
-        <FormField.Input as={TextInput} onChange={handleChange} value={value} />
-        <FormField.Hint>Please enter a valid email.</FormField.Hint>
-      </FormField.Field>
-    </FormField>
-  );
-};

From c4caafdb29e6279ac8b583a6a0e31ca34a591050 Mon Sep 17 00:00:00 2001
From: William Stanton <william.stanton@workday.com>
Date: Thu, 20 Nov 2025 10:43:23 -0500
Subject: [PATCH 03/10] docs: Accessibility for TextArea

---
 modules/react/text-area/stories/TextArea.mdx  | 52 +++++++++++++------
 .../text-area/stories/TextArea.stories.ts     |  9 +---
 .../text-area/stories/examples/Caution.tsx    | 21 --------
 .../text-area/stories/examples/Error.tsx      | 21 --------
 .../react/text-input/stories/TextInput.mdx    |  5 +-
 5 files changed, 40 insertions(+), 68 deletions(-)
 delete mode 100644 modules/react/text-area/stories/examples/Caution.tsx
 delete mode 100644 modules/react/text-area/stories/examples/Error.tsx

diff --git a/modules/react/text-area/stories/TextArea.mdx b/modules/react/text-area/stories/TextArea.mdx
index 202a998526..0488140002 100644
--- a/modules/react/text-area/stories/TextArea.mdx
+++ b/modules/react/text-area/stories/TextArea.mdx
@@ -4,10 +4,8 @@ import {
   Specifications,
   InformationHighlight,
 } from '@workday/canvas-kit-docs';
-import {Caution} from './examples/Caution';
 import {Basic} from './examples/Basic';
 import {Disabled} from './examples/Disabled';
-import {Error} from './examples/Error';
 import {Grow} from './examples/Grow';
 import {LabelPosition} from './examples/LabelPosition';
 import {Placeholder} from './examples/Placeholder';
@@ -34,8 +32,8 @@ yarn add @workday/canvas-kit-react
 
 ### Basic Example
 
-Text Area should be used in tandem with [Form Field](/components/inputs/form-field/) to meet
-accessibility standards.
+Text Area should be used in tandem with [Form Field](/components/inputs/form-field/) to ensure
+proper label association and screen reader support.
 
 <ExampleCodeBlock code={Basic} />
 
@@ -47,11 +45,16 @@ Set the `disabled` prop of the Text Area to prevent users from interacting with
 
 ### Placeholder
 
-Set the `placeholder` prop of the Text Input to display a sample of its expected format or value
+Set the `placeholder` prop of the Text Area to display a sample of its expected format or value
 before a value has been provided.
 
 <ExampleCodeBlock code={Placeholder} />
 
+> **Accessibility Note**: Always provide a persistent `FormField.Label` and never rely on
+> placeholder text as the only label for a text area. Placeholders can disappear or lack sufficient
+> contrast. Use placeholders only for short format examples, and place detailed instructions or
+> guidance in `FormField.Hint` instead of the placeholder.
+
 ### Ref Forwarding
 
 Text Area supports [ref forwarding](https://reactjs.org/docs/forwarding-refs.html). It will forward
@@ -71,6 +74,10 @@ accepts the following values:
 
 <ExampleCodeBlock code={ResizeConstraints} />
 
+> **Accessibility Note**: Allowing users to resize the text area (default `resize: both`) improves
+> accessibility by letting them adjust it for comfort. Avoid disabling resizing (`resize: none`)
+> unless necessary, and always ensure the initial size meets the needs of your content.
+
 ### Grow
 
 Set the `grow` prop of the Text Area to `true` to configure the Text Area to expand to the width of
@@ -94,21 +101,36 @@ Labels for required fields are suffixed by a red asterisk.
 
 ### Error States
 
-Set the `error` prop of the wrapping Form Field to `"caution"` or
-`"error"` to set the Text Area to the Caution or Error state, respectively. You will
-also need to set the `hintId` and `hintText` props on the Form Field to meet accessibility
-standards.
+Form Field provides error and caution states for Text Area. Set the `error` prop on Form Field to
+`"error"` or `"caution"` and use `FormField.Hint` to provide error messages. See
+[Form Field's Error documentation](?path=/docs/components-inputs-form-field--docs#error-states) for
+examples and accessibility guidance.
+
+## Accessibility
+
+`TextArea` should be used with [Form Field](?path=/docs/components-inputs-form-field--docs) to
+ensure proper labeling, error handling, and help text association. See
+[FormField's accessibility documentation](?path=/docs/components-inputs-form-field--docs#accessibility)
+for comprehensive guidance on form accessibility best practices.
+
+### Character Limits
 
-The `error` prop may be applied directly to the Text Area with a value of `"TextArea.ErrorType.Caution"`
-or `TextArea.ErrorType.Error` if Form Field is not being used.
+When limiting text area length:
 
-#### Caution
+- Use the `maxLength` attribute to enforce the limit programmatically.
+- For longer limits (100+ characters), consider adding character count information to
+  `FormField.Hint`.
+- Avoid announcing character counts after every keystroke, as this disrupts screen reader users.
 
-<ExampleCodeBlock code={Caution} />
+### Screen Reader Experience
 
-#### Error
+When properly implemented with `FormField`, screen readers will announce:
 
-<ExampleCodeBlock code={Error} />
+- The label text when the text area receives focus.
+- Required, disabled, or read-only status.
+- Help text and error messages (via `aria-describedby`).
+- The current value or "blank" if empty.
+- That it's a multi-line text input field.
 
 ## Component API
 
diff --git a/modules/react/text-area/stories/TextArea.stories.ts b/modules/react/text-area/stories/TextArea.stories.ts
index 76d3a882bd..ef40f8a6f2 100644
--- a/modules/react/text-area/stories/TextArea.stories.ts
+++ b/modules/react/text-area/stories/TextArea.stories.ts
@@ -4,10 +4,8 @@ import mdxDoc from './TextArea.mdx';
 
 import {TextArea} from '@workday/canvas-kit-react/text-area';
 
-import {Caution as CautionExample} from './examples/Caution';
 import {Basic as BasicExample} from './examples/Basic';
 import {Disabled as DisabledExample} from './examples/Disabled';
-import {Error as ErrorExample} from './examples/Error';
 import {Grow as GrowExample} from './examples/Grow';
 import {LabelPosition as LabelPositionExample} from './examples/LabelPosition';
 import {Placeholder as PlaceholderExample} from './examples/Placeholder';
@@ -28,18 +26,13 @@ export default {
 
 type Story = StoryObj<typeof TextArea>;
 
-export const Caution: Story = {
-  render: CautionExample,
-};
 export const Basic: Story = {
   render: BasicExample,
 };
 export const Disabled: Story = {
   render: DisabledExample,
 };
-export const Error: Story = {
-  render: ErrorExample,
-};
+
 export const Grow: Story = {
   render: GrowExample,
 };
diff --git a/modules/react/text-area/stories/examples/Caution.tsx b/modules/react/text-area/stories/examples/Caution.tsx
deleted file mode 100644
index 1e520f1c9d..0000000000
--- a/modules/react/text-area/stories/examples/Caution.tsx
+++ /dev/null
@@ -1,21 +0,0 @@
-import React from 'react';
-import {FormField} from '@workday/canvas-kit-react/form-field';
-import {TextArea} from '@workday/canvas-kit-react/text-area';
-
-export const Caution = () => {
-  const [value, setValue] = React.useState('');
-
-  const handleChange = (event: React.ChangeEvent<HTMLTextAreaElement>) => {
-    setValue(event.target.value);
-  };
-
-  return (
-    <FormField error="caution">
-      <FormField.Label>Please enter your review.</FormField.Label>
-      <FormField.Field>
-        <FormField.Input as={TextArea} onChange={handleChange} value={value} />
-        <FormField.Hint>Please enter your review.</FormField.Hint>
-      </FormField.Field>
-    </FormField>
-  );
-};
diff --git a/modules/react/text-area/stories/examples/Error.tsx b/modules/react/text-area/stories/examples/Error.tsx
deleted file mode 100644
index 87a1454a9b..0000000000
--- a/modules/react/text-area/stories/examples/Error.tsx
+++ /dev/null
@@ -1,21 +0,0 @@
-import React from 'react';
-import {FormField} from '@workday/canvas-kit-react/form-field';
-import {TextArea} from '@workday/canvas-kit-react/text-area';
-
-export const Error = () => {
-  const [value, setValue] = React.useState('');
-
-  const handleChange = (event: React.ChangeEvent<HTMLTextAreaElement>) => {
-    setValue(event.target.value);
-  };
-
-  return (
-    <FormField error="error">
-      <FormField.Label>Leave a Review</FormField.Label>
-      <FormField.Field>
-        <FormField.Input as={TextArea} onChange={handleChange} value={value} />
-        <FormField.Hint>Please enter your review.</FormField.Hint>
-      </FormField.Field>
-    </FormField>
-  );
-};
diff --git a/modules/react/text-input/stories/TextInput.mdx b/modules/react/text-input/stories/TextInput.mdx
index d00d84d72f..31d5994133 100644
--- a/modules/react/text-input/stories/TextInput.mdx
+++ b/modules/react/text-input/stories/TextInput.mdx
@@ -53,9 +53,8 @@ before a value has been provided.
 
 > **Accessibility Note**: Always provide a persistent `FormField.Label` and never rely on
 > placeholder text as the only label for an input. Placeholders can disappear or lack sufficient
-> contrast, making them unreliable for screen readers. Use placeholders only for short format
-> examples (e.g., "name@example.com"), and place detailed instructions or guidance in
-> `FormField.Hint` instead of the placeholder.
+> contrast. Use placeholders only for short format examples (e.g., "name@example.com"), and place
+> detailed instructions or guidance in `FormField.Hint` instead of the placeholder.
 
 ### Ref Forwarding
 

From 8e88127532132b65c92ee26103751824972ad915 Mon Sep 17 00:00:00 2001
From: William Stanton <william.stanton@workday.com>
Date: Thu, 20 Nov 2025 14:30:23 -0500
Subject: [PATCH 04/10] docs: Creating new TextArea example

---
 ...ing.mdx => TestingTableWithFormFields.mdx} |  0
 .../TestingTextAreaWithCharLimit.mdx          |  8 +++
 .../Forms/CommentBoxWithCharLimit.tsx         | 54 +++++++++++++++++++
 3 files changed, 62 insertions(+)
 rename modules/docs/mdx/accessibility/{AccessibilityTesting.mdx => TestingTableWithFormFields.mdx} (100%)
 create mode 100644 modules/docs/mdx/accessibility/TestingTextAreaWithCharLimit.mdx
 create mode 100644 modules/docs/mdx/accessibility/examples/Forms/CommentBoxWithCharLimit.tsx

diff --git a/modules/docs/mdx/accessibility/AccessibilityTesting.mdx b/modules/docs/mdx/accessibility/TestingTableWithFormFields.mdx
similarity index 100%
rename from modules/docs/mdx/accessibility/AccessibilityTesting.mdx
rename to modules/docs/mdx/accessibility/TestingTableWithFormFields.mdx
diff --git a/modules/docs/mdx/accessibility/TestingTextAreaWithCharLimit.mdx b/modules/docs/mdx/accessibility/TestingTextAreaWithCharLimit.mdx
new file mode 100644
index 0000000000..c8cd598e93
--- /dev/null
+++ b/modules/docs/mdx/accessibility/TestingTextAreaWithCharLimit.mdx
@@ -0,0 +1,8 @@
+import {ExampleCodeBlock} from '@workday/canvas-kit-docs';
+import CommentBoxWithCharLimit from './examples/Forms/CommentBoxWithCharLimit';
+
+<Meta title="Guides/Accessibility/Testing/TextArea With Character Limit" />
+
+## TextArea with character limit
+
+<ExampleCodeBlock code={CommentBoxWithCharLimit} />
diff --git a/modules/docs/mdx/accessibility/examples/Forms/CommentBoxWithCharLimit.tsx b/modules/docs/mdx/accessibility/examples/Forms/CommentBoxWithCharLimit.tsx
new file mode 100644
index 0000000000..25929b956d
--- /dev/null
+++ b/modules/docs/mdx/accessibility/examples/Forms/CommentBoxWithCharLimit.tsx
@@ -0,0 +1,54 @@
+import React from 'react';
+import {FormField} from '@workday/canvas-kit-react/form-field';
+import {TextArea} from '@workday/canvas-kit-react/text-area';
+import {AriaLiveRegion, AccessibleHide} from '@workday/canvas-kit-react/common';
+
+const MAX_CHARACTERS = 200;
+const DEBOUNCE_DELAY = 2000; // 2 seconds after user stops typing
+
+export default function CommentBoxWithCharLimit() {
+  const [value, setValue] = React.useState('');
+  const [liveUpdateStr, setLiveUpdateStr] = React.useState('');
+  const hintTextStr = `${value.length} of ${MAX_CHARACTERS} characters`;
+
+  const handleChange = (event: React.ChangeEvent<HTMLTextAreaElement>) => {
+    setValue(event.target.value);
+  };
+
+  const handleBlur = () => {
+    setLiveUpdateStr('');
+  };
+
+  React.useEffect(() => {
+    // Immediately announce when limit is reached (bypass debounce)
+    if (value.length === MAX_CHARACTERS) {
+      setLiveUpdateStr(`Character limit reached. ${value.length} of ${MAX_CHARACTERS} characters`);
+      return;
+    }
+
+    // Otherwise, debounce the updates
+    const timer = setTimeout(() => {
+      setLiveUpdateStr(hintTextStr);
+    }, DEBOUNCE_DELAY);
+    return () => clearTimeout(timer);
+  }, [hintTextStr]);
+
+  return (
+    <FormField>
+      <FormField.Label>Comments</FormField.Label>
+      <FormField.Field>
+        <FormField.Input
+          as={TextArea}
+          onChange={handleChange}
+          onBlur={handleBlur}
+          value={value}
+          maxLength={MAX_CHARACTERS}
+        />
+        <FormField.Hint>
+          {hintTextStr}
+          <AriaLiveRegion as={AccessibleHide}>{liveUpdateStr}</AriaLiveRegion>
+        </FormField.Hint>
+      </FormField.Field>
+    </FormField>
+  );
+}

From 2d7dc9e28824826fd729724d05b945f8d1db2f6a Mon Sep 17 00:00:00 2001
From: William Stanton <william.stanton@workday.com>
Date: Thu, 20 Nov 2025 17:29:37 -0500
Subject: [PATCH 05/10] docs: Reorganizing & adding docs to MDX

---
 .../mdx/accessibility/AriaLiveRegions.mdx     | 29 +++++++++----------
 .../TestingTextAreaWithCharLimit.mdx          |  8 -----
 .../CommentBoxWithCharLimit.tsx               | 10 +++----
 3 files changed, 18 insertions(+), 29 deletions(-)
 delete mode 100644 modules/docs/mdx/accessibility/TestingTextAreaWithCharLimit.mdx
 rename modules/docs/mdx/accessibility/examples/{Forms => AriaLiveRegions}/CommentBoxWithCharLimit.tsx (87%)

diff --git a/modules/docs/mdx/accessibility/AriaLiveRegions.mdx b/modules/docs/mdx/accessibility/AriaLiveRegions.mdx
index 4c1e617e4b..ccde41050f 100644
--- a/modules/docs/mdx/accessibility/AriaLiveRegions.mdx
+++ b/modules/docs/mdx/accessibility/AriaLiveRegions.mdx
@@ -3,7 +3,7 @@ import {AriaLiveRegion} from '@workday/canvas-kit-react/common';
 import {FilterListWithLiveStatus} from './examples/AriaLiveRegions/FilterListWithLiveStatus';
 import {VisibleLiveRegion} from './examples/AriaLiveRegions/VisibleLiveRegion';
 import {HiddenLiveRegion} from './examples/AriaLiveRegions/HiddenLiveRegion';
-import {TextInputWithLiveError} from './examples/AriaLiveRegions/TextInputWithLiveError';
+import {CommentBoxWithCharLimit} from './examples/AriaLiveRegions/CommentBoxWithCharLimit';
 
 <Meta title="Guides/Accessibility/ARIA Live Regions" component={AriaLiveRegion} />
 
@@ -61,21 +61,20 @@ describe how many items in the list are shown.
 
 <ExampleCodeBlock code={FilterListWithLiveStatus} />
 
-## Text input with live inline error
+## Debouncing an `AriaLiveRegion`: `TextArea` with character limit
 
-In this example, a live region is applied to the inline error message that will appear below the
-text input. Listen for the screen reader to automatically describe the error message as you leave
-the input field blank.
+Using a live region to announce the character count of a text area can help screen reader users
+track their progress. However, announcing on every keystroke would be extremely disruptive—imagine
+hearing "5 of 200 characters... 6 of 200 characters... 7 of 200 characters" for each letter typed!
+In this example, we've implemented debouncing to wait 2 seconds after the user stops typing before
+announcing the count.
 
-**Note:** Use this example with discretion. Using live regions for automatically announcing form
-errors to screen reader users can be a nice experience for simple forms with a very limited number
-of error conditions. As forms increase in complexity, live regions on each error message can become
-increasingly distracting and disruptive to the experience, especially if users are trying to first
-understand the information that is required of them to complete the task.
+**Note:** Turn on a screen reader for this experience.
 
-**Note:** The `<AriaLiveRegion>` component is used inside of the `Hint` to ensure the live region
-remains in the browser DOM at all times. The `Hint` is only rendered in the DOM when it contains
-content, so it will not work reliably as a live region for screen readers using the
-`as={AriaLiveRegion}` prop.
+- Used the `as={AccessibleHide}` prop to hide the live region from view with CSS
+- The live region will only update when a 2 second timer expires after the last keystroke
+- If users have reached the maximum number of characters, the live region will update immediately to
+  inform users that they have reached the limit
+- The live region will be cleared on blur events when users leave the field
 
-<ExampleCodeBlock code={TextInputWithLiveError} />
+<ExampleCodeBlock code={CommentBoxWithCharLimit} />
diff --git a/modules/docs/mdx/accessibility/TestingTextAreaWithCharLimit.mdx b/modules/docs/mdx/accessibility/TestingTextAreaWithCharLimit.mdx
deleted file mode 100644
index c8cd598e93..0000000000
--- a/modules/docs/mdx/accessibility/TestingTextAreaWithCharLimit.mdx
+++ /dev/null
@@ -1,8 +0,0 @@
-import {ExampleCodeBlock} from '@workday/canvas-kit-docs';
-import CommentBoxWithCharLimit from './examples/Forms/CommentBoxWithCharLimit';
-
-<Meta title="Guides/Accessibility/Testing/TextArea With Character Limit" />
-
-## TextArea with character limit
-
-<ExampleCodeBlock code={CommentBoxWithCharLimit} />
diff --git a/modules/docs/mdx/accessibility/examples/Forms/CommentBoxWithCharLimit.tsx b/modules/docs/mdx/accessibility/examples/AriaLiveRegions/CommentBoxWithCharLimit.tsx
similarity index 87%
rename from modules/docs/mdx/accessibility/examples/Forms/CommentBoxWithCharLimit.tsx
rename to modules/docs/mdx/accessibility/examples/AriaLiveRegions/CommentBoxWithCharLimit.tsx
index 25929b956d..52d2d81657 100644
--- a/modules/docs/mdx/accessibility/examples/Forms/CommentBoxWithCharLimit.tsx
+++ b/modules/docs/mdx/accessibility/examples/AriaLiveRegions/CommentBoxWithCharLimit.tsx
@@ -6,7 +6,7 @@ import {AriaLiveRegion, AccessibleHide} from '@workday/canvas-kit-react/common';
 const MAX_CHARACTERS = 200;
 const DEBOUNCE_DELAY = 2000; // 2 seconds after user stops typing
 
-export default function CommentBoxWithCharLimit() {
+export const CommentBoxWithCharLimit = () => {
   const [value, setValue] = React.useState('');
   const [liveUpdateStr, setLiveUpdateStr] = React.useState('');
   const hintTextStr = `${value.length} of ${MAX_CHARACTERS} characters`;
@@ -44,11 +44,9 @@ export default function CommentBoxWithCharLimit() {
           value={value}
           maxLength={MAX_CHARACTERS}
         />
-        <FormField.Hint>
-          {hintTextStr}
-          <AriaLiveRegion as={AccessibleHide}>{liveUpdateStr}</AriaLiveRegion>
-        </FormField.Hint>
+        <FormField.Hint>{hintTextStr}</FormField.Hint>
+        <AriaLiveRegion as={AccessibleHide}>{liveUpdateStr}</AriaLiveRegion>
       </FormField.Field>
     </FormField>
   );
-}
+};

From a5e7311241fdae169f34d54ba0b06444dd00292d Mon Sep 17 00:00:00 2001
From: William Stanton <william.stanton@workday.com>
Date: Wed, 26 Nov 2025 16:40:02 -0500
Subject: [PATCH 06/10] docs: Refactoring InputGroup examples

Discovering we can't use 'as={InputGroup}' on 'FormField.Input' component because it breaks assumptions about which elements to apply input id value for the label.
---
 .../react/form-field/stories/FormField.mdx    | 32 +++++++-------
 .../stories/examples/HiddenLabel.tsx          | 33 +++++++++++----
 modules/react/text-area/stories/TextArea.mdx  |  4 ++
 .../text-input/stories/examples/Icons.tsx     | 42 ++++++++++---------
 4 files changed, 69 insertions(+), 42 deletions(-)

diff --git a/modules/react/form-field/stories/FormField.mdx b/modules/react/form-field/stories/FormField.mdx
index 0d1b0e4c17..1844b95c92 100644
--- a/modules/react/form-field/stories/FormField.mdx
+++ b/modules/react/form-field/stories/FormField.mdx
@@ -67,6 +67,17 @@ Use the error state when the value is no longer valid.
 > error state from fields with standard hint text. Read more about
 > [Failure of Success Criterion 1.4.1 due to identifying required or error fields using color differences only](https://www.w3.org/WAI/WCAG22/Techniques/failures/F81)
 
+### Hint
+
+Use `FormField.Hint` to display a short message below the input component and `FormField.Field` to
+ensure proper alignment.
+
+<ExampleCodeBlock code={Hint} />
+
+> **Accessibility Note**: Hints are automatically associated to the input field with the
+> `aria-describedby` attribute. This ensures that screen readers can automatically announce the hint
+> text to users when the input field is focused.
+
 ### Disabled
 
 Set the `disabled` prop of `FormField.Input` to prevent users from interacting with it.
@@ -79,17 +90,6 @@ Set the `disabled` prop of `FormField.Input` to prevent users from interacting w
 > perceive and may harm the usability of the form. Consider using text elements instead, or
 > read-only fields if users cannot modify data.
 
-### Hint
-
-Use `FormField.Hint` to display a short message below the input component and `FormField.Field` to
-ensure proper alignment.
-
-<ExampleCodeBlock code={Hint} />
-
-> **Accessibility Note**: Hints are automatically associated to the input field with the
-> `aria-describedby` attribute. This ensures that screen readers can automatically announce the hint
-> text to users when the input field is focused.
-
 ### Label Position
 
 Set the `orientation` prop of the Form Field to designate the position of the label relative to the
@@ -130,9 +130,9 @@ for required fields are suffixed by a red asterisk.
 
 <ExampleCodeBlock code={Required} />
 
-> **Accessibility Note**: The HTML `required` attribute is automatically added to the input field
-> and announced by screen readers. Consider adding a note at the top of your form indicating that
-> fields marked with an asterisk (\*) are required. This provides context for all users.
+> **Accessibility Note**: The HTML `required` attribute will be added to the input field and
+> announced by screen readers. Consider adding a note at the top of your form indicating that fields
+> marked with an asterisk (\*) are required. This provides context for all users.
 
 ### Grouped Inputs
 
@@ -184,6 +184,10 @@ In cases where you want to hide the label while still meeting accessibility stan
 
 <ExampleCodeBlock code={HiddenLabel} />
 
+> **Accessibility Note**: Hidden labels are typically not recommended. In this example, a
+> universally recognizable icon like a magnifying glass signaling "search"may be a suitable
+> alternative to visible text labels.
+
 ### Themed Errors
 
 You can theme your error rings by wrapping an input in a `CanvasProvider` and defining
diff --git a/modules/react/form-field/stories/examples/HiddenLabel.tsx b/modules/react/form-field/stories/examples/HiddenLabel.tsx
index 79dee5387f..95838e2bb5 100644
--- a/modules/react/form-field/stories/examples/HiddenLabel.tsx
+++ b/modules/react/form-field/stories/examples/HiddenLabel.tsx
@@ -1,12 +1,24 @@
 import React from 'react';
-import {FormField} from '@workday/canvas-kit-react/form-field';
+import {
+  FormField,
+  useFormFieldModel,
+  useFormFieldInput,
+} from '@workday/canvas-kit-react/form-field';
 import {Flex} from '@workday/canvas-kit-react/layout';
 import {TextInput, InputGroup} from '@workday/canvas-kit-react/text-input';
 import {SystemIcon} from '@workday/canvas-kit-react/icon';
 import {searchIcon} from '@workday/canvas-system-icons-web';
 
+/**
+ * Using `as={InputGroup}` on `FormField.Input` will break the label associations necessary for accessibility.
+ * In this example, we've rendered `FormField.Field` as `InputGroup` and then hoisted the `id` of the input from the FormField model.
+ * This allows us to set the `id` of the `InputGroup.Input` correctly for proper label association.
+ */
+
 export const HiddenLabel = () => {
   const [value, setValue] = React.useState('');
+  const model = useFormFieldModel();
+  const {id: formFieldInputId} = useFormFieldInput(model);
 
   const handleChange = (event: React.ChangeEvent<HTMLInputElement>) => {
     setValue(event.target.value);
@@ -14,15 +26,18 @@ export const HiddenLabel = () => {
 
   return (
     <Flex>
-      <FormField>
+      <FormField model={model}>
         <FormField.Label isHidden>Search</FormField.Label>
-        <FormField.Field>
-          <FormField.Input as={InputGroup}>
-            <InputGroup.InnerStart pointerEvents="none">
-              <SystemIcon icon={searchIcon} size="small" />
-            </InputGroup.InnerStart>
-            <InputGroup.Input as={TextInput} onChange={handleChange} />
-          </FormField.Input>
+        <FormField.Field as={InputGroup}>
+          <InputGroup.InnerStart>
+            <SystemIcon icon={searchIcon} size="small" />
+          </InputGroup.InnerStart>
+          <InputGroup.Input
+            as={TextInput}
+            id={formFieldInputId}
+            onChange={handleChange}
+            value={value}
+          />
         </FormField.Field>
       </FormField>
     </Flex>
diff --git a/modules/react/text-area/stories/TextArea.mdx b/modules/react/text-area/stories/TextArea.mdx
index 0488140002..910cee13b1 100644
--- a/modules/react/text-area/stories/TextArea.mdx
+++ b/modules/react/text-area/stories/TextArea.mdx
@@ -121,6 +121,10 @@ When limiting text area length:
 - For longer limits (100+ characters), consider adding character count information to
   `FormField.Hint`.
 - Avoid announcing character counts after every keystroke, as this disrupts screen reader users.
+  Check out
+  [Debouncing an AriaLiveRegion: TextArea with character limit](?path=/docs/guides-accessibility-aria-live-regions--docs#debouncing-an-arialiveregion-textarea-with-character-limit)
+  for an example of how to wait for users to stop typing before announcing the character count to
+  screen readers.
 
 ### Screen Reader Experience
 
diff --git a/modules/react/text-input/stories/examples/Icons.tsx b/modules/react/text-input/stories/examples/Icons.tsx
index 97b66cbe75..0affa3d688 100644
--- a/modules/react/text-input/stories/examples/Icons.tsx
+++ b/modules/react/text-input/stories/examples/Icons.tsx
@@ -1,32 +1,36 @@
 import React from 'react';
 
 import {mailIcon} from '@workday/canvas-system-icons-web';
-import {FormField} from '@workday/canvas-kit-react/form-field';
+import {
+  FormField,
+  useFormFieldModel,
+  useFormFieldInput,
+} from '@workday/canvas-kit-react/form-field';
 import {InputGroup} from '@workday/canvas-kit-react/text-input';
 import {SystemIcon} from '@workday/canvas-kit-react/icon';
 
+/**
+ * Using `as={InputGroup}` on `FormField.Input` will break the label associations necessary for accessibility.
+ * In this example, we've rendered `FormField.Field` as `InputGroup` and then hoisted the `id` of the input from the FormField model.
+ * This allows us to set the `id` of the `InputGroup.Input` correctly for proper label association.
+ */
+
 export const Icons = () => {
+  const model = useFormFieldModel();
+  const {id: formFieldInputId} = useFormFieldInput(model);
+
   return (
-    <FormField>
+    <FormField model={model}>
       <FormField.Label>Email</FormField.Label>
-      <FormField.Field>
-        <InputGroupFormFieldForwarder />
+      <FormField.Field as={InputGroup}>
+        <InputGroup.InnerStart>
+          <SystemIcon icon={mailIcon} size="small" />
+        </InputGroup.InnerStart>
+        <InputGroup.Input id={formFieldInputId} autoComplete="email" />
+        <InputGroup.InnerEnd>
+          <InputGroup.ClearButton />
+        </InputGroup.InnerEnd>
       </FormField.Field>
     </FormField>
   );
 };
-
-// create a prop forwarding component for FormField to forward to
-const InputGroupFormFieldForwarder = (props: {}) => {
-  return (
-    <FormField.Input as={InputGroup} width={280}>
-      <InputGroup.InnerStart pointerEvents="none">
-        <SystemIcon icon={mailIcon} size="small" />
-      </InputGroup.InnerStart>
-      <InputGroup.Input {...props} />
-      <InputGroup.InnerEnd>
-        <InputGroup.ClearButton />
-      </InputGroup.InnerEnd>
-    </FormField.Input>
-  );
-};

From 9f8051d6326b0f9faa152c5c0fab3d45883a377f Mon Sep 17 00:00:00 2001
From: William Stanton <william.stanton@workday.com>
Date: Wed, 26 Nov 2025 17:42:21 -0500
Subject: [PATCH 07/10] docs: Fixing Cypress test errors

---
 cypress/component/TextArea.spec.tsx  | 42 +++++++++++++---------------
 cypress/component/TextInput.spec.tsx | 42 +++++++++++++---------------
 2 files changed, 38 insertions(+), 46 deletions(-)

diff --git a/cypress/component/TextArea.spec.tsx b/cypress/component/TextArea.spec.tsx
index 71ba71aa68..2cee35ac5f 100644
--- a/cypress/component/TextArea.spec.tsx
+++ b/cypress/component/TextArea.spec.tsx
@@ -1,6 +1,4 @@
 import {Basic} from '../../modules/react/text-area/stories/examples/Basic';
-import {Caution} from '../../modules/react/text-area/stories/examples/Caution';
-import {Error} from '../../modules/react/text-area/stories/examples/Error';
 import {Disabled} from '../../modules/react/text-area/stories/examples/Disabled';
 import {Placeholder} from '../../modules/react/text-area/stories/examples/Placeholder';
 
@@ -9,34 +7,32 @@ const getTextArea = () => {
 };
 
 describe('Text Area', () => {
-  [Basic, Caution, Error].forEach(Example => {
-    context(`given the '${Example.name}' story is rendered`, () => {
+  context(`given the 'Basic' story is rendered`, () => {
+    beforeEach(() => {
+      cy.mount(<Basic />);
+    });
+
+    it('should not have any axe errors', () => {
+      cy.checkA11y();
+    });
+
+    context('when clicked', () => {
       beforeEach(() => {
-        cy.mount(<Example />);
+        getTextArea().click();
       });
 
-      it('should not have any axe errors', () => {
-        cy.checkA11y();
+      it('should be focused', () => {
+        getTextArea().should('be.focused');
       });
+    });
 
-      context('when clicked', () => {
-        beforeEach(() => {
-          getTextArea().click();
-        });
-
-        it('should be focused', () => {
-          getTextArea().should('be.focused');
-        });
+    context('when text is entered', () => {
+      beforeEach(() => {
+        getTextArea().clear().type('Test');
       });
 
-      context('when text is entered', () => {
-        beforeEach(() => {
-          getTextArea().clear().type('Test');
-        });
-
-        it('should reflect the text typed', () => {
-          getTextArea().should('have.value', 'Test');
-        });
+      it('should reflect the text typed', () => {
+        getTextArea().should('have.value', 'Test');
       });
     });
   });
diff --git a/cypress/component/TextInput.spec.tsx b/cypress/component/TextInput.spec.tsx
index c6f3620b5e..32cf9c113b 100644
--- a/cypress/component/TextInput.spec.tsx
+++ b/cypress/component/TextInput.spec.tsx
@@ -1,6 +1,4 @@
 import {Basic} from '../../modules/react/text-input/stories/examples/Basic';
-import {Caution} from '../../modules/react/text-input/stories/examples/Caution';
-import {Error} from '../../modules/react/text-input/stories/examples/Error';
 import {Disabled} from '../../modules/react/text-input/stories/examples/Disabled';
 import {Placeholder} from '../../modules/react/text-input/stories/examples/Placeholder';
 
@@ -9,34 +7,32 @@ const getTextInput = () => {
 };
 
 describe('TextInput', () => {
-  [Basic, Caution, Error].forEach(Example => {
-    context(`given the '${Example.name}' story is rendered`, () => {
+  context(`given the 'Basic' story is rendered`, () => {
+    beforeEach(() => {
+      cy.mount(<Basic />);
+    });
+
+    it('should not have any axe errors', () => {
+      cy.checkA11y();
+    });
+
+    context('when clicked', () => {
       beforeEach(() => {
-        cy.mount(<Example />);
+        getTextInput().click();
       });
 
-      it('should not have any axe errors', () => {
-        cy.checkA11y();
+      it('should be focused', () => {
+        getTextInput().should('be.focused');
       });
+    });
 
-      context('when clicked', () => {
-        beforeEach(() => {
-          getTextInput().click();
-        });
-
-        it('should be focused', () => {
-          getTextInput().should('be.focused');
-        });
+    context('when text is entered', () => {
+      beforeEach(() => {
+        getTextInput().clear().type('Test');
       });
 
-      context('when text is entered', () => {
-        beforeEach(() => {
-          getTextInput().clear().type('Test');
-        });
-
-        it('should reflect the text typed', () => {
-          getTextInput().should('have.value', 'Test');
-        });
+      it('should reflect the text typed', () => {
+        getTextInput().should('have.value', 'Test');
       });
     });
   });

From 3c48cf85a7fc7632cff03e0b9dd842769fe8798a Mon Sep 17 00:00:00 2001
From: William Stanton <40372497+williamjstanton@users.noreply.github.com>
Date: Tue, 9 Dec 2025 15:17:21 -0500
Subject: [PATCH 08/10] Apply suggestions from code review

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
---
 .../examples/AriaLiveRegions/CommentBoxWithCharLimit.tsx      | 4 ++--
 modules/react/form-field/stories/FormField.mdx                | 2 +-
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/modules/docs/mdx/accessibility/examples/AriaLiveRegions/CommentBoxWithCharLimit.tsx b/modules/docs/mdx/accessibility/examples/AriaLiveRegions/CommentBoxWithCharLimit.tsx
index 52d2d81657..65efd12ba0 100644
--- a/modules/docs/mdx/accessibility/examples/AriaLiveRegions/CommentBoxWithCharLimit.tsx
+++ b/modules/docs/mdx/accessibility/examples/AriaLiveRegions/CommentBoxWithCharLimit.tsx
@@ -28,10 +28,10 @@ export const CommentBoxWithCharLimit = () => {
 
     // Otherwise, debounce the updates
     const timer = setTimeout(() => {
-      setLiveUpdateStr(hintTextStr);
+      setLiveUpdateStr(`${value.length} of ${MAX_CHARACTERS} characters`);
     }, DEBOUNCE_DELAY);
     return () => clearTimeout(timer);
-  }, [hintTextStr]);
+  }, [value.length]);
 
   return (
     <FormField>
diff --git a/modules/react/form-field/stories/FormField.mdx b/modules/react/form-field/stories/FormField.mdx
index 1844b95c92..e696998933 100644
--- a/modules/react/form-field/stories/FormField.mdx
+++ b/modules/react/form-field/stories/FormField.mdx
@@ -185,7 +185,7 @@ In cases where you want to hide the label while still meeting accessibility stan
 <ExampleCodeBlock code={HiddenLabel} />
 
 > **Accessibility Note**: Hidden labels are typically not recommended. In this example, a
-> universally recognizable icon like a magnifying glass signaling "search"may be a suitable
+> universally recognizable icon like a magnifying glass signaling "search" may be a suitable
 > alternative to visible text labels.
 
 ### Themed Errors

From 5cacee58d9164eed52b2a1fcbb4da7ab00aaa421 Mon Sep 17 00:00:00 2001
From: William Stanton <william.stanton@workday.com>
Date: Tue, 9 Dec 2025 15:47:19 -0500
Subject: [PATCH 09/10] docs: Fixing Storybook links

---
 modules/react/text-area/stories/TextArea.mdx   |  8 ++++----
 modules/react/text-input/stories/TextInput.mdx | 12 ++++++------
 2 files changed, 10 insertions(+), 10 deletions(-)

diff --git a/modules/react/text-area/stories/TextArea.mdx b/modules/react/text-area/stories/TextArea.mdx
index 910cee13b1..9ceae3b78d 100644
--- a/modules/react/text-area/stories/TextArea.mdx
+++ b/modules/react/text-area/stories/TextArea.mdx
@@ -103,14 +103,14 @@ Labels for required fields are suffixed by a red asterisk.
 
 Form Field provides error and caution states for Text Area. Set the `error` prop on Form Field to
 `"error"` or `"caution"` and use `FormField.Hint` to provide error messages. See
-[Form Field's Error documentation](?path=/docs/components-inputs-form-field--docs#error-states) for
+[Form Field's Error documentation](/components/inputs/form-field/#error-states) for
 examples and accessibility guidance.
 
 ## Accessibility
 
-`TextArea` should be used with [Form Field](?path=/docs/components-inputs-form-field--docs) to
+`TextArea` should be used with [Form Field](/components/inputs/form-field/) to
 ensure proper labeling, error handling, and help text association. See
-[FormField's accessibility documentation](?path=/docs/components-inputs-form-field--docs#accessibility)
+[FormField's accessibility documentation](/components/inputs/form-field/#accessibility)
 for comprehensive guidance on form accessibility best practices.
 
 ### Character Limits
@@ -122,7 +122,7 @@ When limiting text area length:
   `FormField.Hint`.
 - Avoid announcing character counts after every keystroke, as this disrupts screen reader users.
   Check out
-  [Debouncing an AriaLiveRegion: TextArea with character limit](?path=/docs/guides-accessibility-aria-live-regions--docs#debouncing-an-arialiveregion-textarea-with-character-limit)
+  [Debouncing an AriaLiveRegion: TextArea with character limit](https://workday.github.io/canvas-kit/?path=/docs/guides-accessibility-aria-live-regions--docs#debouncing-an-arialiveregion-textarea-with-character-limit)
   for an example of how to wait for users to stop typing before announcing the character count to
   screen readers.
 
diff --git a/modules/react/text-input/stories/TextInput.mdx b/modules/react/text-input/stories/TextInput.mdx
index 31d5994133..7864a5e786 100644
--- a/modules/react/text-input/stories/TextInput.mdx
+++ b/modules/react/text-input/stories/TextInput.mdx
@@ -111,15 +111,15 @@ method to change width. The `width` prop is used to correctly position other inn
 
 Form Field provides error and caution states for Text Input. Set the `error` prop on Form Field to
 `"error"` or `"caution"` and use `FormField.Hint` to provide error messages. See
-[Form Field's Error documentation](?path=/docs/components-inputs-form-field--docs#error-states) for
-examples and accessibility guidance.
+[Form Field's Error documentation](/components/inputs/form-field/#error-states) for examples and
+accessibility guidance.
 
 ## Accessibility
 
-`TextInput` should be used with [Form Field](?path=/docs/components-inputs-form-field--docs) to
-ensure proper labeling, error handling, and help text association. See
-[FormField's accessibility documentation](?path=/docs/components-inputs-form-field--docs#accessibility)
-for comprehensive guidance on form accessibility best practices.
+`TextInput` should be used with [Form Field](/components/inputs/form-field/) to ensure proper
+labeling, error handling, and help text association. See
+[FormField's accessibility documentation](/components/inputs/form-field/#accessibility) for
+comprehensive guidance on form accessibility best practices.
 
 ### Autocomplete Attribute
 

From 68bf901e7db3b6fe6bc3246484983b85cc19b9be Mon Sep 17 00:00:00 2001
From: "manuel.carrera" <manuel.carrera@workday.com>
Date: Tue, 23 Dec 2025 09:02:20 -0700
Subject: [PATCH 10/10] test: Update check for test

---
 cypress/component/FormField.spec.tsx | 12 +++++++++---
 1 file changed, 9 insertions(+), 3 deletions(-)

diff --git a/cypress/component/FormField.spec.tsx b/cypress/component/FormField.spec.tsx
index 47f05c44e4..c3a78339cf 100644
--- a/cypress/component/FormField.spec.tsx
+++ b/cypress/component/FormField.spec.tsx
@@ -52,7 +52,7 @@ describe('Form Field', () => {
     });
   });
 
-  context(`given the 'Alert' story is rendered`, () => {
+  context(`given the 'Caution' story is rendered`, () => {
     beforeEach(() => {
       cy.mount(<Caution />);
     });
@@ -63,7 +63,10 @@ describe('Form Field', () => {
 
     it('should connect the input with the hint text', () => {
       cy.get('input').should('have.attr', 'aria-describedby');
-      cy.get('input').should('have.ariaDescription', 'Cannot contain numbers');
+      cy.get('input').should(
+        'have.ariaDescription',
+        'Alert: Password strength is weak, using more characters is recommended.'
+      );
     });
   });
 
@@ -78,7 +81,10 @@ describe('Form Field', () => {
 
     it('should connect the input with the hint text', () => {
       cy.get('input').should('have.attr', 'aria-describedby');
-      cy.get('input').should('have.ariaDescription', 'Must Contain a number and a capital letter');
+      cy.get('input').should(
+        'have.ariaDescription',
+        'Error: Must Contain a number and a capital letter'
+      );
     });
   });