@workday/canvas-kit-docs 15.0.0-alpha.1303-next.0 → 15.0.0

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,10 +198,68 @@ 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" />
 
 ## Specifications
 
-<Specifications file="FormField.spec.tsx" name="FormField" />
+<Specifications file="./cypress/component/FormField.spec.tsx" name="FormField" />

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

@@ -1,20 +1,19 @@
-import React from 'react';
-import {FormField, FormFieldGroup} from '@workday/canvas-kit-react/form-field';
-import {Flex} from '@workday/canvas-kit-react/layout';
-import {TextInput} from '@workday/canvas-kit-react/text-input';
 import {RadioGroup} from '@workday/canvas-kit-preview-react/radio';
 import {Checkbox} from '@workday/canvas-kit-react/checkbox';
+import {FormField, FormFieldGroup} from '@workday/canvas-kit-react/form-field';
+import {Flex} from '@workday/canvas-kit-react/layout';
 import {Select} from '@workday/canvas-kit-react/select';
-import {TextArea} from '@workday/canvas-kit-react/text-area';
 import {Switch} from '@workday/canvas-kit-react/switch';
+import {TextArea} from '@workday/canvas-kit-react/text-area';
+import {TextInput} from '@workday/canvas-kit-react/text-input';
 import {calc, createStyles} from '@workday/canvas-kit-styling';
-import {system} from '@workday/canvas-tokens-web';
+import {base, system} from '@workday/canvas-tokens-web';
 
 const parentContainerStyles = createStyles({
   flexDirection: 'column',
-  gap: calc.subtract(system.space.x6, system.space.x1),
-  padding: calc.subtract(system.space.x10, system.space.x1),
-  borderRadius: system.space.x1,
+  gap: calc.subtract(system.gap.lg, system.gap.xs),
+  padding: calc.subtract(base.size500, system.padding.xxs),
+  borderRadius: system.shape.sm,
 });
 
 export default () => {
@@ -53,7 +52,7 @@ export default () => {
       </FormField>
       <FormField as="fieldset" isRequired={true} error={'error'} orientation="horizontalStart" grow>
         <FormField.Label as="legend">Radio Group Legend</FormField.Label>
-        <FormField.Container>
+        <FormField.Field>
           <FormField.Input as={RadioGroup}>
             <RadioGroup.RadioButton value="deep-dish">Deep dish</RadioGroup.RadioButton>
             <RadioGroup.RadioButton value="thin">Thin</RadioGroup.RadioButton>
@@ -64,7 +63,7 @@ export default () => {
             </RadioGroup.RadioButton>
           </FormField.Input>
           <FormField.Hint>Error Message</FormField.Hint>
-        </FormField.Container>
+        </FormField.Field>
       </FormField>
       <FormField as="fieldset" grow>
         <FormField.Label as="legend">Checkbox Legend</FormField.Label>

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

@@ -1,4 +1,5 @@
 import React from 'react';
+
 import {FormField} from '@workday/canvas-kit-react/form-field';
 import {Flex} from '@workday/canvas-kit-react/layout';
 import {TextInput} from '@workday/canvas-kit-react/text-input';

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

@@ -1,10 +1,11 @@
 import React from 'react';
+
 import {FormField} from '@workday/canvas-kit-react/form-field';
-import {TextInput} from '@workday/canvas-kit-react/text-input';
 import {Flex} from '@workday/canvas-kit-react/layout';
+import {TextInput} from '@workday/canvas-kit-react/text-input';
 
 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 +14,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/Custom.tsx

@@ -1,12 +1,13 @@
 import React from 'react';
+
+import {useModelContext} from '@workday/canvas-kit-react/common';
 import {
+  formFieldStencil,
   useFormFieldHint,
   useFormFieldInput,
   useFormFieldLabel,
   useFormFieldModel,
-  formFieldStencil,
 } from '@workday/canvas-kit-react/form-field';
-import {useModelContext} from '@workday/canvas-kit-react/common';
 import {Flex} from '@workday/canvas-kit-react/layout';
 
 const Label = ({model, children}) => {

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

@@ -1,4 +1,5 @@
 import React from 'react';
+
 import {FormField} from '@workday/canvas-kit-react/form-field';
 import {Flex} from '@workday/canvas-kit-react/layout';
 import {TextInput} from '@workday/canvas-kit-react/text-input';

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

@@ -1,8 +1,8 @@
 import React from 'react';
-import {FormField} from '@workday/canvas-kit-react/form-field';
 
-import {TextInput} from '@workday/canvas-kit-react/text-input';
+import {FormField} from '@workday/canvas-kit-react/form-field';
 import {Flex} from '@workday/canvas-kit-react/layout';
+import {TextInput} from '@workday/canvas-kit-react/text-input';
 
 export default () => {
   const [value, setValue] = React.useState('');

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

@@ -1,8 +1,8 @@
 import React from 'react';
-import {FormField} from '@workday/canvas-kit-react/form-field';
 
-import {TextInput} from '@workday/canvas-kit-react/text-input';
+import {FormField} from '@workday/canvas-kit-react/form-field';
 import {Flex} from '@workday/canvas-kit-react/layout';
+import {TextInput} from '@workday/canvas-kit-react/text-input';
 
 export default () => {
   const [value, setValue] = React.useState('');
@@ -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

@@ -1,21 +1,21 @@
 import React from 'react';
-import {FormFieldGroup} from '@workday/canvas-kit-react/form-field';
-import {PrimaryButton, SecondaryButton} from '@workday/canvas-kit-react/button';
-import {system} from '@workday/canvas-tokens-web';
-import {Banner} from '@workday/canvas-kit-react/banner';
 
-import {Checkbox} from '@workday/canvas-kit-react/checkbox';
 import {RadioGroup} from '@workday/canvas-kit-preview-react/radio';
-import {createStyles} from '@workday/canvas-kit-styling';
+import {Banner} from '@workday/canvas-kit-react/banner';
+import {PrimaryButton, SecondaryButton} from '@workday/canvas-kit-react/button';
+import {Checkbox} from '@workday/canvas-kit-react/checkbox';
 import {AriaLiveRegion} from '@workday/canvas-kit-react/common';
+import {FormFieldGroup} from '@workday/canvas-kit-react/form-field';
+import {createStyles, px2rem} from '@workday/canvas-kit-styling';
+import {system} from '@workday/canvas-tokens-web';
 
 const formStyles = createStyles({
-  margin: `${system.space.zero} ${system.space.x3}`,
+  margin: `0 ${px2rem(12)}`,
 });
 
 const formButtonStyles = createStyles({
   display: 'inline-flex',
-  gap: system.space.x2,
+  gap: system.gap.sm,
 });
 
 const toppings = [
@@ -126,10 +126,10 @@ export default () => {
                 {error && radioError
                   ? 'At least one topping and crust selection is required'
                   : error
-                  ? 'You must choose at least one topping'
-                  : radioError
-                  ? 'You must choose a crust'
-                  : ''}
+                    ? 'You must choose at least one topping'
+                    : radioError
+                      ? 'You must choose a crust'
+                      : ''}
               </Banner.Label>
             </Banner>
           ) : null}
@@ -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/Grow.tsx

@@ -1,4 +1,5 @@
 import React from 'react';
+
 import {FormField} from '@workday/canvas-kit-react/form-field';
 import {Flex} from '@workday/canvas-kit-react/layout';
 import {TextInput} from '@workday/canvas-kit-react/text-input';

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

@@ -1,12 +1,25 @@
 import React from 'react';
-import {FormField} 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 {
+  FormField,
+  useFormFieldInput,
+  useFormFieldModel,
+} from '@workday/canvas-kit-react/form-field';
 import {SystemIcon} from '@workday/canvas-kit-react/icon';
+import {Flex} from '@workday/canvas-kit-react/layout';
+import {InputGroup, TextInput} from '@workday/canvas-kit-react/text-input';
 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 +27,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/form-field/examples/Hint.tsx

@@ -1,8 +1,8 @@
 import React from 'react';
-import {FormField} from '@workday/canvas-kit-react/form-field';
 
-import {TextInput} from '@workday/canvas-kit-react/text-input';
+import {FormField} from '@workday/canvas-kit-react/form-field';
 import {Flex} from '@workday/canvas-kit-react/layout';
+import {TextInput} from '@workday/canvas-kit-react/text-input';
 
 export default () => {
   const [value, setValue] = React.useState('');

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

@@ -1,12 +1,13 @@
 import React from 'react';
-import {TextInput} from '@workday/canvas-kit-react/text-input';
+
 import {FormField} from '@workday/canvas-kit-react/form-field';
+import {TextInput} from '@workday/canvas-kit-react/text-input';
 import {createStyles} from '@workday/canvas-kit-styling';
 import {system} from '@workday/canvas-tokens-web';
 
 const formStyles = createStyles({
   display: 'flex',
-  gap: system.space.x2,
+  gap: system.gap.sm,
   flexDirection: 'column',
 });
 

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

@@ -1,12 +1,13 @@
 import React from 'react';
-import {TextInput} from '@workday/canvas-kit-react/text-input';
+
 import {FormField} from '@workday/canvas-kit-react/form-field';
+import {TextInput} from '@workday/canvas-kit-react/text-input';
 import {createStyles} from '@workday/canvas-kit-styling';
 import {system} from '@workday/canvas-tokens-web';
 
 const formStyles = createStyles({
   display: 'flex',
-  gap: system.space.x2,
+  gap: system.gap.sm,
   flexDirection: 'column',
 });
 

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

@@ -1,14 +1,15 @@
 import React from 'react';
+
+import {SecondaryButton} from '@workday/canvas-kit-react/button';
 import {changeFocus} from '@workday/canvas-kit-react/common';
+import {FormField} from '@workday/canvas-kit-react/form-field';
 import {Flex} from '@workday/canvas-kit-react/layout';
-import {SecondaryButton} from '@workday/canvas-kit-react/button';
 import {TextInput} from '@workday/canvas-kit-react/text-input';
-import {FormField} from '@workday/canvas-kit-react/form-field';
 import {createStyles} from '@workday/canvas-kit-styling';
 import {system} from '@workday/canvas-tokens-web';
 
 const parentContainerStyles = createStyles({
-  gap: system.space.x1,
+  gap: system.gap.xs,
   alignItems: 'flex-start',
   flexDirection: 'column',
 });

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

@@ -1,6 +1,7 @@
 import React from 'react';
-import {TextInput} from '@workday/canvas-kit-react/text-input';
+
 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('');

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

@@ -1,13 +1,13 @@
 import React from 'react';
-import {TextInput} from '@workday/canvas-kit-react/text-input';
-import {FormField} from '@workday/canvas-kit-react/form-field';
+
 import {CanvasProvider, PartialEmotionCanvasTheme} from '@workday/canvas-kit-react/common';
-import {colors, space} from '@workday/canvas-kit-react/tokens';
-import {createStyles} from '@workday/canvas-kit-styling';
-import {system} from '@workday/canvas-tokens-web';
+import {FormField} from '@workday/canvas-kit-react/form-field';
+import {TextInput} from '@workday/canvas-kit-react/text-input';
+import {createStyles, cssVar} from '@workday/canvas-kit-styling';
+import {base, system} from '@workday/canvas-tokens-web';
 
 const formFieldHintStyles = createStyles({
-  paddingTop: system.space.x2,
+  paddingTop: system.padding.xs,
 });
 
 export default () => {
@@ -21,10 +21,10 @@ export default () => {
     canvas: {
       palette: {
         common: {
-          focusOutline: colors.grapeSoda300,
+          focusOutline: cssVar(base.green600),
         },
         error: {
-          main: colors.islandPunch400,
+          main: cssVar(base.magenta700),
         },
       },
     },