From f892121d77f554d934cecf862eaf539eb57d764f Mon Sep 17 00:00:00 2001 From: moaan-workday Date: Wed, 17 Jun 2026 16:17:11 -0700 Subject: [PATCH 1/3] replaced a11y section --- modules/react/text-area/stories/TextArea.mdx | 99 ++++++++++++++------ 1 file changed, 71 insertions(+), 28 deletions(-) diff --git a/modules/react/text-area/stories/TextArea.mdx b/modules/react/text-area/stories/TextArea.mdx index d03f4ae0cc..57feed9aae 100644 --- a/modules/react/text-area/stories/TextArea.mdx +++ b/modules/react/text-area/stories/TextArea.mdx @@ -108,35 +108,78 @@ Form Field provides error and caution states for Text Area. Set the `error` prop [Form Field's Error documentation](/components/inputs/form-field/#error-states) for examples and accessibility guidance. -## Accessibility - -`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](/components/inputs/form-field/#accessibility) -for comprehensive guidance on form accessibility best practices. - -### Character Limits - -When limiting text area length: - -- 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. - Check out - [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. - -### Screen Reader Experience - -When properly implemented with `FormField`, screen readers will announce: +## **I. Accessibility Overview** + +`TextArea` allows users to enter and edit multiple lines of text. It must be composed with +[Form Field](/components/inputs/form-field/) so the control has a programmatically determinable name, +relationships, and instructions. The primary accessibility goal is to ensure assistive technology +users can identify the multi-line field, understand how to complete it, and hear hints, errors, +required state, and character limit information when the text area receives focus. + +See [FormField's accessibility documentation](/components/inputs/form-field/#accessibility) for +comprehensive guidance on form accessibility best practices. + +### **1\. Built-in Behaviors** + +Canvas Kit handles the following automatically when you compose `TextArea` inside `FormField`: + +- **Native multi-line control**: `TextArea` renders a ` +

Share any additional feedback.

+ +``` -- 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. +Do not manually add `aria-labelledby`, `aria-describedby`, or `id` on `TextArea` +when `FormField` already wires those relationships. + +### **2\. Accessibility Requirements** + +Developers must provide the following for accessible text areas: + +- **`FormField` + `FormField.Label` + `FormField.Input`**: Wrap every `TextArea` (for example, + ``) so labeling and description wiring is applied. +- **`FormField.Hint`**: Use for instructions, guidance, error messages, and static character count + text. +- **`isRequired`**: Set on `FormField` when the field is mandatory so the `required` attribute is + exposed. +- **`disabled`**: Set on `TextArea` when the field is not interactive. +- **`error` and `FormField.Hint`**: When `error="error"`, prepend the error text with the word + "Error" in `FormField.Hint` so users who cannot perceive color can distinguish error text from + field-level hint text. +- **`maxLength`**: Enforce character limits programmatically on `TextArea`. +- **Character count (100+ characters)**: Add character count information to `FormField.Hint`. Announce + updates via a debounced `AriaLiveRegion` but avoid announcing character counts after every keystroke. Refer to + [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). + +### **3\. Anti-Patterns** + +Do not generate the following: + +- **Unlabeled text areas**: Do not use `TextArea` without `FormField` and `FormField.Label`. +- **Placeholder-only labels**: Do not rely on `placeholder` instead of `FormField.Label`; placeholders + disappear while typing and are poor substitutes for labels. +- **Manual ARIA overrides**: Do not set `aria-labelledby`, `aria-describedby`, or `id` on `TextArea` + when `FormField` already manages those relationships. +- **Color-only errors**: Do not set `error="error"` without descriptive text in `FormField.Hint`. +- **Per-keystroke character announcements**: Do not announce character counts after every keystroke; + debounce live region updates so screen reader users are not interrupted while typing. +- **Disabling resize unnecessarily**: Do not set `resize` to `none` unless there is a strong design or + layout requirement; users lose a visual comfort affordance. ## Component API From 9f5064273c92435874e1c592d751bbb22e88a5f7 Mon Sep 17 00:00:00 2001 From: moaan-workday Date: Mon, 22 Jun 2026 12:32:14 -0700 Subject: [PATCH 2/3] Requirements section needs syntax Review --- modules/react/text-area/stories/TextArea.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/react/text-area/stories/TextArea.mdx b/modules/react/text-area/stories/TextArea.mdx index 57feed9aae..ad5e703bf3 100644 --- a/modules/react/text-area/stories/TextArea.mdx +++ b/modules/react/text-area/stories/TextArea.mdx @@ -152,7 +152,7 @@ when `FormField` already wires those relationships. Developers must provide the following for accessible text areas: - **`FormField` + `FormField.Label` + `FormField.Input`**: Wrap every `TextArea` (for example, - ``) so labeling and description wiring is applied. + ``) so labeling and description wiring is applied. /* REVIEW: Is this valid code? */ - **`FormField.Hint`**: Use for instructions, guidance, error messages, and static character count text. - **`isRequired`**: Set on `FormField` when the field is mandatory so the `required` attribute is From 4dcf4b164101df49115d8c86d64a0d785a49d7eb Mon Sep 17 00:00:00 2001 From: moaan-workday Date: Thu, 9 Jul 2026 17:39:43 -0700 Subject: [PATCH 3/3] Used Purva's updated prompt --- modules/react/text-area/stories/TextArea.mdx | 219 +++++++++++++++---- 1 file changed, 175 insertions(+), 44 deletions(-) diff --git a/modules/react/text-area/stories/TextArea.mdx b/modules/react/text-area/stories/TextArea.mdx index ad5e703bf3..a6ce25ff1a 100644 --- a/modules/react/text-area/stories/TextArea.mdx +++ b/modules/react/text-area/stories/TextArea.mdx @@ -108,34 +108,98 @@ Form Field provides error and caution states for Text Area. Set the `error` prop [Form Field's Error documentation](/components/inputs/form-field/#error-states) for examples and accessibility guidance. -## **I. Accessibility Overview** +## Accessibility -`TextArea` allows users to enter and edit multiple lines of text. It must be composed with -[Form Field](/components/inputs/form-field/) so the control has a programmatically determinable name, -relationships, and instructions. The primary accessibility goal is to ensure assistive technology -users can identify the multi-line field, understand how to complete it, and hear hints, errors, -required state, and character limit information when the text area receives focus. +The primary accessibility goal for `TextArea` is to give every user a visible, persistent label and +clear instructions, and to ensure assistive technology users can identify the multi-line field and +hear hints, errors, required state, and character-limit information when the control receives focus. -See [FormField's accessibility documentation](/components/inputs/form-field/#accessibility) for -comprehensive guidance on form accessibility best practices. +### Minimum accessible structure -### **1\. Built-in Behaviors** +Match the Basic example: label first, then the input inside `FormField.Field`. This order matches the +DOM reading sequence and ensures the label's `htmlFor` targets the ` + +``` + +When hint text is present: + ```html
@@ -144,42 +208,109 @@ For a simple text area field, the DOM looks like:
``` -Do not manually add `aria-labelledby`, `aria-describedby`, or `id` on `TextArea` -when `FormField` already wires those relationships. +For a field in an error state: -### **2\. Accessibility Requirements** +```html +
+ + +

Error: Please enter at least 10 characters.

+
+``` + +### Accessibility Requirements + +Required in application code for an accessible `TextArea`. Rows marked _(conditional)_ apply only when +the situation matches—otherwise omit. -Developers must provide the following for accessible text areas: +**If no design spec is provided:** use a visible `FormField.Label`, wrap the control with +`FormField.Input as={TextArea}`, omit `isHidden`, keep default `resize: both`, and omit a custom `id` +unless testing or composition requires it. -- **`FormField` + `FormField.Label` + `FormField.Input`**: Wrap every `TextArea` (for example, - ``) so labeling and description wiring is applied. /* REVIEW: Is this valid code? */ -- **`FormField.Hint`**: Use for instructions, guidance, error messages, and static character count - text. -- **`isRequired`**: Set on `FormField` when the field is mandatory so the `required` attribute is - exposed. -- **`disabled`**: Set on `TextArea` when the field is not interactive. -- **`error` and `FormField.Hint`**: When `error="error"`, prepend the error text with the word - "Error" in `FormField.Hint` so users who cannot perceive color can distinguish error text from - field-level hint text. -- **`maxLength`**: Enforce character limits programmatically on `TextArea`. -- **Character count (100+ characters)**: Add character count information to `FormField.Hint`. Announce - updates via a debounced `AriaLiveRegion` but avoid announcing character counts after every keystroke. Refer to - [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). +**Character limit with debounced live region** _(conditional — when `maxLength` is set)_: -### **3\. Anti-Patterns** +```tsx +import {AccessibleHide, AriaLiveRegion} from '@workday/canvas-kit-react/common'; +import {FormField} from '@workday/canvas-kit-react/form-field'; +import {TextArea} from '@workday/canvas-kit-react/text-area'; -Do not generate the following: +const MAX_CHARACTERS = 200; + + + Comments + + + {`${value.length} of ${MAX_CHARACTERS} characters`} + {liveUpdateStr} + +; +``` + +Debounce live-region updates (for example, 2 seconds after typing stops). Announce immediately when +the limit is reached. Clear the live region on blur. Do not announce character counts after every +keystroke. See +[Debouncing an AriaLiveRegion: TextArea with character limit](?path=/docs/guides-accessibility-aria-live-regions--docs#debouncing-an-arialiveregion-textarea-with-character-limit) +for a full example. + +**Ref forwarding** _(conditional — when programmatic focus is needed)_: + +```tsx +const ref = React.useRef(null); + +; +``` -- **Unlabeled text areas**: Do not use `TextArea` without `FormField` and `FormField.Label`. +| Requirement | How to satisfy | +| --- | --- | +| Visible label | **`FormField.Label`** with concise, meaningful text | +| Input wiring | **`FormField.Input as={TextArea}`** wrapping every `TextArea` instance | +| Hint or error text _(conditional)_ | **`FormField.Hint`** when there is help or validation copy—required because `aria-describedby` is wired by default (see **Built-in Behaviors**) | +| Error state _(conditional)_ | `error="error"` on **`FormField`** and **`FormField.Hint`** prefixed with "Error:" so users who cannot perceive color can distinguish errors from hints | +| Caution state _(conditional)_ | `error="caution"` on **`FormField`** with descriptive **`FormField.Hint`** (no `aria-invalid`) | +| Required field _(conditional)_ | `isRequired` on **`FormField`**; consider a form-level note that asterisk (\*) marks required fields | +| Disabled field _(conditional)_ | `disabled` on **`FormField.Input`** (passed through to `