docs: Reformat TextArea Accessibility by moaan-workday · Pull Request #4058 · Workday/canvas-kit

moaan-workday · 2026-07-10T00:52:58Z

Summary

This PR rewrites the TextArea Storybook accessibility section to match the newer AI-codegen documentation template (the same pattern used for Dialog and FormField). It turns a short paragraph into a comprehensive accessibility guide.

Documents the generated ID convention: label-{id}, input-{id}, hint-{id}.
Clarifies that FormField.Input wires aria-labelledby, aria-describedby, aria-invalid, and required automatically.
Notes that error="caution" is visual-only and does not set aria-invalid.
Warns that FormField.Input always sets aria-describedby="hint-{id}" when an id exists, so omitting FormField.Hint creates a dangling reference.
Provides a debounced AriaLiveRegion example for character counts and links to the existing guide.
Adds a requirements table covering visible labels, wiring, hints/errors, required/disabled states, character limits, placeholders, stable IDs, and resize constraints.

Release Category

Documentation

Checklist

MDX documentation adheres to Canvas Kit's Documentation Guidelines
Label ready for review has been added to PR

For the Reviewer

PR title is short and descriptive
PR summary describes the change (Fixes/Resolves linked correctly)
PR Release Notes describes additional information useful to call out in a release message or removed if not applicable
Breaking Changes provides useful information to upgrade to this code or removed if not applicable

Where Should the Reviewer Start?

Areas for Feedback? (optional)

Code
Documentation
Testing
Codemods

Testing Manually

Screenshots or GIFs (if applicable)

Thank You Gif (optional)

coderabbitai · 2026-07-10T00:53:52Z

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 36a310fe-edf7-458f-b202-8a8447c62edc

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

cypress · 2026-07-27T17:04:42Z

Workday/canvas-kit Run #11456

Run Properties: Passed #11456 • 91390af3f4 ℹ️: Merge e35064fe24b66e60b9d0890903f57c6fa3021d57 into 1043c2ab55c5a6e4ceb9343e29be...

Project	`Workday/canvas-kit`
Branch Review	`text-area-reformat`
Run status	`Passed #11456`
Run duration	`02m 27s`
Commit	`91390af3f4 ℹ️: Merge e35064fe24b66e60b9d0890903f57c6fa3021d57 into 1043c2ab55c5a6e4ceb9343e29be...`
Committer	`moaan-workday`
View all properties for this run ↗︎

Test results
Failures	`0`
Flaky	`0`
Pending	`17`
Skipped	`0`
Passing	`809`
View all changes introduced in this branch ↗︎

UI Coverage `19.52%`
Untested elements	`1540`
Tested elements	`371`

Accessibility `99.44%`
Failed rules	`5 critical` `5 serious` `0 moderate` `2 minor`
Failed elements	`68`

Co-authored-by: Cursor <cursoragent@cursor.com>

williamjstanton

Putting in some feedback of my own to help move this along. I think we have a couple of big questions to work through:

Should we be focusing on React TSX code, or DOM renders for AI code-gen? What's more deterministic?
How do we avoid duplicating docs? How are we splitting concerns between what TextArea does and what FormField is doing?

williamjstanton · 2026-07-29T14:04:21Z

+```html
+<div>
+  <label id="label-abc" for="input-abc">Leave a Review</label>
+  <textarea id="input-abc" aria-labelledby="label-abc"></textarea>


DOM example contradicts your own implementation note
You document that FormField.Input always sets aria-describedby="hint-{id}", but the first HTML sample has no aria-describedby. Dialog never shows a simplified DOM that contradicts built-ins. For codegen, that first snippet will win over the prose. Either show the always-on attribute (and a missing #hint-abc as the bug case), or drop the “simple” example.

Attempted fix in commit:
docs(text-area): Show aria-describedby in simple DOM example without hint
26fc83469

williamjstanton · 2026-07-29T14:08:54Z

- Help text and error messages (via `aria-describedby`).
- The current value or "blank" if empty.
- That it's a multi-line text input field.
+| Requirement                        | How to satisfy                                                                                                                                          |


Too much FormField, not enough TextArea
Dialog points at FormField for labeled inputs in one row; it doesn’t re-spec FormField’s whole table. Your requirements table (label, hint, error, caution, required, stable IDs) largely duplicates FormField Accessibility. Dialog’s benchmark is: own what’s unique, link what’s shared. TextArea-unique rows should dominate: multi-line choice, resize, native <textarea> semantics, etc.

I agree. I would recommend keeping Input wiring with a reference link to form field docs, character limit as those are the only ones specific to text area.

Attempted a fix in following commit. How does it look now?
docs(text-area): Remove excessive formfield mention in the accessibility requirement and how to satisfy table

e35064fe2

williamjstanton · 2026-07-29T14:20:19Z

+- Set **`error`** on **`FormField`**, not on `TextArea` directly, so `aria-invalid` and error
+  styling stay in sync.
+
+**Keyboard** (_standard multi-line text control behavior_):


Most of your keyboard bullets are native <textarea> / behavior. Keep a short “native multi-line control” note; spend the budget on anything Canvas Kit changes.

I'm concerned we might be using up too much context re-iterating native behaviors?

williamjstanton · 2026-07-29T14:23:51Z

+- **User-resizable dimensions**: Defaults to `resize: both` so users can adjust the control for
+  visual comfort.
+
+**Implementation notes**:


I don't think I've seen this implementation notes section before in our other drafts.

All of the bullet points either duplicate what's in FormField, or duplicate anti-patterns below.

IMO, we should consider removing this set of bullets altogether.

williamjstanton · 2026-07-29T14:33:27Z

+| Character limit _(conditional)_    | `maxLength` on **`FormField.Input`**, visible count in **`FormField.Hint`**, and debounced **`AriaLiveRegion`** for screen reader updates               |
+| Placeholder _(conditional)_        | Short format example on **`FormField.Input`** only—never as the sole label                                                                              |
+| Stable IDs _(conditional)_         | `id` prop on **`FormField`** when predictable `label-`, `input-`, and `hint-` IDs are needed for testing                                                |
+| Resize constraints _(conditional)_ | `resize` prop on **`TextArea`**; default to `Both` unless layout requires otherwise                                                                     |


Referring to my other comment, I think we should remove this since it is just a CSS property.

williamjstanton · 2026-07-29T14:34:39Z

+| Disabled field _(conditional)_     | `disabled` on **`FormField.Input`** (passed through to `<textarea>`)                                                                                    |
+| Character limit _(conditional)_    | `maxLength` on **`FormField.Input`**, visible count in **`FormField.Hint`**, and debounced **`AriaLiveRegion`** for screen reader updates               |
+| Placeholder _(conditional)_        | Short format example on **`FormField.Input`** only—never as the sole label                                                                              |
+| Stable IDs _(conditional)_         | `id` prop on **`FormField`** when predictable `label-`, `input-`, and `hint-` IDs are needed for testing                                                |


I don't understand why stable ID's are listed here as conditional requirements. IMO, I think we should remove.

purvas12 · 2026-07-30T15:05:11Z

- Help text and error messages (via `aria-describedby`).
- The current value or "blank" if empty.
- That it's a multi-line text input field.
+| Requirement                        | How to satisfy                                                                                                                                          |


I agree. I would recommend keeping Input wiring with a reference link to form field docs, character limit as those are the only ones specific to text area.

purvas12 · 2026-07-30T16:18:16Z

+- **CONDITIONAL:** hint/error text, required state, disabled state, character limit with live
+  region, placeholder, stable `id`, resize constraints
+
+### Anti-Patterns


Let's trim this section down as well. Only keep the ones that are unique to Text area: Single-line input for multi-line content, Per-keystroke character announcements and Disabling resize unnecessarily. Add a reference to the Anti-patterns section for Form Field to avoid duplicating content.

…hint

…ity requirement and how to satisfy table

moaan-workday added 4 commits June 17, 2026 16:17

replaced a11y section

f892121

Requirements section needs syntax Review

9f50642

Used Purva's updated prompt

4dcf4b1

Merge branch 'Workday:master' into text-area-reformat

e5abb8c

Merge branch 'a11y' into text-area-reformat

15b4e8e

moaan-workday changed the title ~~Text area reformat~~ docs: text area a11y reformat Jul 10, 2026

moaan-workday changed the title ~~docs: text area a11y reformat~~ docs: Reformat TextArea Accessibility Jul 10, 2026

purvas12 reviewed Jul 13, 2026

View reviewed changes

Comment thread modules/react/text-area/stories/TextArea.mdx

purvas12 reviewed Jul 13, 2026

View reviewed changes

Comment thread modules/react/text-area/stories/TextArea.mdx

purvas12 reviewed Jul 13, 2026

View reviewed changes

Comment thread modules/react/text-area/stories/TextArea.mdx Outdated

Merge branch 'a11y' into text-area-reformat

417c08c

docs(text-area): clarify TextArea vs TextInput in accessibility intro

3cff9c6

Co-authored-by: Cursor <cursoragent@cursor.com>

williamjstanton requested changes Jul 29, 2026

View reviewed changes

williamjstanton requested a review from purvas12 July 29, 2026 14:55

purvas12 reviewed Jul 30, 2026

View reviewed changes

purvas12 requested changes Jul 30, 2026

View reviewed changes

moaan-workday added 2 commits July 31, 2026 15:59

docs(text-area): Show aria-describedby in simple DOM example without …

26fc834

…hint

docs(text-area): Remove excessive formfield mention in the accessibil…

e35064f

…ity requirement and how to satisfy table

Uh oh!

Conversation

moaan-workday commented Jul 10, 2026 • edited by williamjstanton Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Release Category

Checklist

For the Reviewer

Where Should the Reviewer Start?

Areas for Feedback? (optional)

Testing Manually

Screenshots or GIFs (if applicable)

Thank You Gif (optional)

Uh oh!

coderabbitai Bot commented Jul 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review skipped

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cypress Bot commented Jul 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

williamjstanton left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

purvas12 Jul 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

purvas12 Jul 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

moaan-workday commented Jul 10, 2026 •

edited by williamjstanton

Loading

coderabbitai Bot commented Jul 10, 2026 •

edited

Loading

cypress Bot commented Jul 27, 2026 •

edited

Loading

purvas12 Jul 30, 2026 •

edited

Loading

purvas12 Jul 30, 2026 •

edited

Loading