@workday/canvas-kit-docs 14.2.25 → 14.2.27

package/dist/es6/lib/stackblitzFiles/packageJSONFile.js

@@ -18,11 +18,11 @@ export const packageJSONFile = `{
     "@emotion/react": "11.11.4",
     "@types/react": "18.2.60",
     "@types/react-dom": "18.2.19",
-    "@workday/canvas-kit-labs-react": "14.2.25",
-    "@workday/canvas-kit-preview-react": "14.2.25",
-    "@workday/canvas-kit-react": "14.2.25",
-    "@workday/canvas-kit-react-fonts": "^14.2.25",
-    "@workday/canvas-kit-styling": "14.2.25",
+    "@workday/canvas-kit-labs-react": "14.2.27",
+    "@workday/canvas-kit-preview-react": "14.2.27",
+    "@workday/canvas-kit-react": "14.2.27",
+    "@workday/canvas-kit-react-fonts": "^14.2.27",
+    "@workday/canvas-kit-styling": "14.2.27",
     "@workday/canvas-system-icons-web": "3.0.36",
     "@workday/canvas-tokens-web": "3.1.2"
   },

package/dist/es6/lib/stackblitzFiles/packageJSONFile.ts

@@ -18,11 +18,11 @@ export const packageJSONFile = `{
     "@emotion/react": "11.11.4",
     "@types/react": "18.2.60",
     "@types/react-dom": "18.2.19",
-    "@workday/canvas-kit-labs-react": "14.2.25",
-    "@workday/canvas-kit-preview-react": "14.2.25",
-    "@workday/canvas-kit-react": "14.2.25",
-    "@workday/canvas-kit-react-fonts": "^14.2.25",
-    "@workday/canvas-kit-styling": "14.2.25",
+    "@workday/canvas-kit-labs-react": "14.2.27",
+    "@workday/canvas-kit-preview-react": "14.2.27",
+    "@workday/canvas-kit-react": "14.2.27",
+    "@workday/canvas-kit-react-fonts": "^14.2.27",
+    "@workday/canvas-kit-styling": "14.2.27",
     "@workday/canvas-system-icons-web": "3.0.36",
     "@workday/canvas-tokens-web": "3.1.2"
   },

package/dist/es6/mdx/accessibility/examples/AriaLiveRegions/CommentBoxWithCharLimit.d.ts

@@ -0,0 +1,2 @@
+export declare const CommentBoxWithCharLimit: () => import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=CommentBoxWithCharLimit.d.ts.map

package/dist/es6/mdx/accessibility/examples/AriaLiveRegions/CommentBoxWithCharLimit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CommentBoxWithCharLimit.d.ts","sourceRoot":"","sources":["../../../../../../mdx/accessibility/examples/AriaLiveRegions/CommentBoxWithCharLimit.tsx"],"names":[],"mappings":"AAQA,eAAO,MAAM,uBAAuB,+CA2CnC,CAAC"}

package/dist/es6/mdx/accessibility/examples/AriaLiveRegions/CommentBoxWithCharLimit.js

@@ -0,0 +1,31 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+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 const CommentBoxWithCharLimit = () => {
+    const [value, setValue] = React.useState('');
+    const [liveUpdateStr, setLiveUpdateStr] = React.useState('');
+    const hintTextStr = `${value.length} of ${MAX_CHARACTERS} characters`;
+    const handleChange = (event) => {
+        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(`${value.length} of ${MAX_CHARACTERS} characters`);
+        }, DEBOUNCE_DELAY);
+        return () => clearTimeout(timer);
+    }, [value.length]);
+    return (_jsxs(FormField, { children: [_jsx(FormField.Label, { children: "Comments" }), _jsxs(FormField.Field, { children: [_jsx(FormField.Input, { as: TextArea, onChange: handleChange, onBlur: handleBlur, value: value, maxLength: MAX_CHARACTERS }), _jsx(FormField.Hint, { children: hintTextStr }), _jsx(AriaLiveRegion, { as: AccessibleHide, children: liveUpdateStr })] })] }));
+};

package/dist/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';
 
 
 # ARIA Live Regions
@@ -60,21 +60,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} />

package/dist/mdx/react/form-field/FormField.mdx

@@ -28,43 +28,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
@@ -87,17 +50,19 @@ 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} />
 
-### Disabled
-
-Set the `disabled` prop of `FormField.Input` to prevent users from interacting with it.
-
-<ExampleCodeBlock code={Disabled} />
+> **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)
 
 ### Hint
 
@@ -106,6 +71,22 @@ 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.
+
+<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.
+
 ### Label Position
 
 Set the `orientation` prop of the Form Field to designate the position of the label relative to the
@@ -146,12 +127,16 @@ for required fields are suffixed by a red asterisk.
 
 <ExampleCodeBlock code={Required} />
 
+> **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
 
 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`:
 
@@ -161,6 +146,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
@@ -191,6 +181,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
@@ -204,6 +198,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" />

package/dist/mdx/react/form-field/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 default () => {
-  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 default () => {
   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>

package/dist/mdx/react/form-field/examples/Error.tsx

@@ -17,7 +17,7 @@ export default () => {
         <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>

package/dist/mdx/react/form-field/examples/GroupedInputs.tsx

@@ -160,7 +160,7 @@ export default () => {
             })}
           </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 default () => {
               </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>

package/dist/mdx/react/form-field/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 default () => {
   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 default () => {
 
   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>

package/dist/mdx/react/text-area/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';
@@ -31,8 +29,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} />
 
@@ -44,11 +42,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
@@ -68,6 +71,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
@@ -91,21 +98,40 @@ 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](/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
 
-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.
+  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.
 
-<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
 

package/dist/mdx/react/text-input/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';
@@ -32,8 +30,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} />
 
@@ -50,6 +48,11 @@ 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. 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
@@ -97,23 +100,46 @@ 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.
+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](/components/inputs/form-field/#error-states) for examples and
+accessibility guidance.
+
+## Accessibility
+
+`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
+
+- 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.
 
-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.
+### Input Type for Mobile Keyboards
 
-#### Caution
+`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.
 
-<ExampleCodeBlock code={Caution} />
+### Screen Reader Experience
 
-#### Error
+When properly implemented with `FormField`, screen readers will announce:
 
-<ExampleCodeBlock code={Error} />
+- 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
 

package/dist/mdx/react/text-input/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 default () => {
+  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>
-  );
-};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@workday/canvas-kit-docs",
-  "version": "14.2.25",
+  "version": "14.2.27",
   "description": "Documentation components of Canvas Kit components",
   "author": "Workday, Inc. (https://www.workday.com)",
   "license": "Apache-2.0",
@@ -45,10 +45,10 @@
     "@emotion/styled": "^11.6.0",
     "@stackblitz/sdk": "^1.11.0",
     "@storybook/csf": "0.0.1",
-    "@workday/canvas-kit-labs-react": "^14.2.25",
-    "@workday/canvas-kit-preview-react": "^14.2.25",
-    "@workday/canvas-kit-react": "^14.2.25",
-    "@workday/canvas-kit-styling": "^14.2.25",
+    "@workday/canvas-kit-labs-react": "^14.2.27",
+    "@workday/canvas-kit-preview-react": "^14.2.27",
+    "@workday/canvas-kit-react": "^14.2.27",
+    "@workday/canvas-kit-styling": "^14.2.27",
     "@workday/canvas-system-icons-web": "^3.0.36",
     "@workday/canvas-tokens-web": "^3.1.6",
     "markdown-to-jsx": "^7.2.0",
@@ -61,5 +61,5 @@
     "mkdirp": "^1.0.3",
     "typescript": "5.0"
   },
-  "gitHead": "4dfa021c4798122cacd6b18b660de072701863e4"
+  "gitHead": "c01ab812eade9574a72bf84c008b2a62b51e2649"
 }

package/dist/mdx/react/text-area/examples/Caution.tsx

@@ -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 default () => {
-  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>
-  );
-};

package/dist/mdx/react/text-area/examples/Error.tsx

@@ -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 default () => {
-  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>
-  );
-};

package/dist/mdx/react/text-input/examples/Caution.tsx

@@ -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 default () => {
-  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>
-  );
-};

package/dist/mdx/react/text-input/examples/Error.tsx

@@ -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 default () => {
-  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>
-  );
-};