@workday/canvas-kit-docs 16.0.9 → 16.0.11

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": "16.0.9",
-    "@workday/canvas-kit-preview-react": "16.0.9",
-    "@workday/canvas-kit-react": "16.0.9",
-    "@workday/canvas-kit-react-fonts": "^16.0.9",
-    "@workday/canvas-kit-styling": "16.0.9",
+    "@workday/canvas-kit-labs-react": "16.0.11",
+    "@workday/canvas-kit-preview-react": "16.0.11",
+    "@workday/canvas-kit-react": "16.0.11",
+    "@workday/canvas-kit-react-fonts": "^16.0.11",
+    "@workday/canvas-kit-styling": "16.0.11",
     "@workday/canvas-system-icons-web": "^5.0.3",
     "@workday/canvas-expressive-icons-web": "1.0.1",
     "@workday/canvas-tokens-web": "4.4.0-beta.11"

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

@@ -19,11 +19,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": "16.0.9",
-    "@workday/canvas-kit-preview-react": "16.0.9",
-    "@workday/canvas-kit-react": "16.0.9",
-    "@workday/canvas-kit-react-fonts": "^16.0.9",
-    "@workday/canvas-kit-styling": "16.0.9",
+    "@workday/canvas-kit-labs-react": "16.0.11",
+    "@workday/canvas-kit-preview-react": "16.0.11",
+    "@workday/canvas-kit-react": "16.0.11",
+    "@workday/canvas-kit-react-fonts": "^16.0.11",
+    "@workday/canvas-kit-styling": "16.0.11",
     "@workday/canvas-system-icons-web": "^5.0.3",
     "@workday/canvas-expressive-icons-web": "1.0.1",
     "@workday/canvas-tokens-web": "4.4.0-beta.11"

package/dist/mdx/react/dialog/Dialog.mdx

@@ -1,7 +1,8 @@
 import {ExampleCodeBlock, SymbolDoc} from '@workday/canvas-kit-docs';
+import Alt from './examples/Alt';
 import Basic from './examples/Basic';
 import Focus from './examples/Focus';
-import Alt from './examples/Alt';
+
 
 # Canvas Kit Dialog
 
@@ -18,16 +19,17 @@ yarn add @workday/canvas-kit-react
 
 ### Basic Example
 
-Unlike Modal, Dialog **does not** render the rest of the page inert while it is active. Dialog
-should be used in situations where the task does not require immediate attention.
+The following example shows a typical Dialog with heading, close control, and form content.
 
 <ExampleCodeBlock code={Basic} />
 
 ### Focus Redirect
 
-Dialog **does not** trap keyboard focus like the Modal component does. Instead, it allows focus to
-move freely in and out of the dialog, supporting more flexible navigation. The following example
-shows how Dialog manages focus in and out of the component.
+Dialog **does not** trap keyboard focus like the Modal component does. The default `useDialogModel`
+composes `useFocusRedirect`: <kbd>Tab</kbd> / <kbd>Shift</kbd>+<kbd>Tab</kbd> at the last or first
+focusable element inside the dialog closes it and moves focus to the next or previous focusable
+element on the page. Dialog is non-modal and is **not** a focus trap; it does **not** change screen
+reader reading order. The following example shows how Dialog manages focus at those edges.
 
 <ExampleCodeBlock code={Focus} />
 
@@ -36,53 +38,238 @@ shows how Dialog manages focus in and out of the component.
 
 ### Alt Example
 
-The `alt` variant is designed for use on alternative page backgrounds (`system.color.bg.alt.default`). Use this variant to maintain proper visual hierarchy when placing components on colored backgrounds. While the default variant should be used on `system.color.bg.default` backgrounds, the `alt` variant ensures the component remains visually elevated on `system.color.bg.alt.default` backgrounds.
+The `alt` variant is designed for use on alternative page backgrounds
+(`system.color.bg.alt.default`). Use this variant to maintain proper visual hierarchy when placing
+components on colored backgrounds. While the default variant should be used on
+`system.color.bg.default` backgrounds, the `alt` variant ensures the component remains visually
+elevated on `system.color.bg.alt.default` backgrounds.
 
 <ExampleCodeBlock code={Alt} />
 
 ## Accessibility
 
-`Dialog` composes the popup stack with `useInitialFocus`, `useReturnFocus`, `useCloseOnEscape`,
-`useCloseOnOutsideClick`, and `useFocusRedirect`. The card container includes an ARIA
-**`role="dialog"`** that is **non-modal**: the rest of the page stays available. The card also
-includes an **`aria-labelledby`** attribute referencing the `id` on `Dialog.Heading`, so the dialog
-has an accessible name that matches the visible heading.
-
-The Dialog component includes a `<div>` element (sibling to the `Dialog.Target`) with `aria-owns`
-pointing to the `Dialog.Card`. This remaps the hierarchy of the accessibility tree to improve
-sequential reading order in supported browsers. For more information, see
-[Guides > Accessibility > Inline Popups](https://workday.github.io/canvas-kit/?path=/docs/guides-accessibility-inline-popups--docs).
-
-[Dialog Pattern | APG | WAI | W3C](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/)
-
-- Prefer **`Dialog.Heading`** so the dialog is properly labelled; avoid leaving a dialog without an
-  accessible name.
-- Ensure icon-only controls such as **`Dialog.CloseIcon`** include an accessible name. Prefer the
-  `Tooltip` component to provide a visible label, or a translated `aria-label` string is acceptable.
-
-### Navigation
-
-- **Enter** / **Space**: Open the dialog (standard button behavior on the trigger). When it opens,
-  focus moves to the **first focusable element** inside the dialog in DOM order—often the close
-  control—or to the element referenced by **`initialFocusRef`** on the dialog model when set.
-- **Tab** / **Shift + Tab**: Move through focusable elements inside the dialog; leaving the first or
-  last focusable element **closes** the dialog and moves focus to the next or previous focusable
-  element on the page (non-modal focus redirect behavior).
-- **Escape**: Closes the dialog and returns focus to the `Dialog.Target` (or configured return
-  target).
-
-### Screen Reader Experience
-
-- **When the dialog opens:** Screen readers should announce the name and role of the first focused
-  control (often the close button), the dialog's name (`Dialog.Heading`) and role.
-- **Reading order:** The dialog contents should be read in the same order as it appears on screen
-  for browsers and screen readers that support `aria-owns`. Results vary, so always test with your
-  supported browsers and screen reader combinations.
-- **Expanded or collapsed state:** The `Dialog.Target` does not include an expanded or collapsed
-  state by default, but it can be added if the interaction design isn't using an initial focus for
-  the Dialog. See
-  [Guides > Accessibility > Inline Popups](https://workday.github.io/canvas-kit/?path=/docs/guides-accessibility-inline-popups--docs)
-  for more information.
+Ensure users of assistive technology can discover, name, and operate a **non-modal** dialog: the
+rest of the page stays available (no inert background), the dialog has an accessible name that
+matches its visible heading, keyboard users can open and dismiss it predictably, and screen reader
+reading order is improved where `aria-owns` is supported (see
+[Guides > Accessibility > Inline Popups](https://workday.github.io/canvas-kit/?path=/docs/guides-accessibility-inline-popups--docs)).
+For blocking tasks, use
+[**Modal**](https://workday.github.io/canvas-kit/?path=/docs/components-popups-modal--docs) instead.
+Prefer **Dialog** for the standard non-modal dialog; use
+[**Popup**](https://workday.github.io/canvas-kit/?path=/docs/components-popups-popup--docs) with
+composed hooks when you need a custom popup stack or behavior (for example omitting
+**`useInitialFocus`**). The W3C
+[Dialog (Modal) Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/) applies to
+[**Modal**](https://workday.github.io/canvas-kit/?path=/docs/components-popups-modal--docs); Dialog
+is intentionally non-modal.
+
+### Minimum Accessible Structure
+
+The following matches the [Basic Example](#basic-example) layout: **`Dialog.CloseIcon`** before
+**`Dialog.Heading`** so open focus lands on the dismiss control first; primary actions use
+**`Dialog.CloseButton`** (which closes the dialog on activate).
+
+```tsx
+import {PrimaryButton} from '@workday/canvas-kit-react/button';
+import {Dialog} from '@workday/canvas-kit-react/dialog';
+import {FormField} from '@workday/canvas-kit-react/form-field';
+import {TextInput} from '@workday/canvas-kit-react/text-input';
+
+<Dialog>
+  <Dialog.Target as={PrimaryButton}>Open</Dialog.Target>
+  <Dialog.Popper>
+    <Dialog.Card>
+      <Dialog.CloseIcon aria-label="Close" />
+      <Dialog.Heading>Title</Dialog.Heading>
+      <Dialog.Body>
+        <FormField>
+          <FormField.Label>Email</FormField.Label>
+          <FormField.Input as={TextInput} />
+        </FormField>
+      </Dialog.Body>
+      <Dialog.ButtonGroup>
+        <Dialog.CloseButton>Cancel</Dialog.CloseButton>
+        <Dialog.CloseButton as={PrimaryButton}>Submit</Dialog.CloseButton>
+      </Dialog.ButtonGroup>
+    </Dialog.Card>
+  </Dialog.Popper>
+</Dialog>;
+```
+
+Include a dismiss control: **`Dialog.CloseButton`** with visible text (for example "Cancel" or
+"Close"), and/or **`Dialog.CloseIcon`** when the design uses an icon-only dismiss (requires
+**`aria-label`** or **`Tooltip`**). Use **`Dialog.CloseButton`** for actions that should also close
+the dialog (for example "Submit").
+
+### Built-in Behaviors
+
+Canvas Kit applies these automatically via `useDialogModel` and Dialog subcomponents. **Do not
+duplicate them** in consuming code.
+
+**Popup behaviors** (_composed on the default model_):
+
+- `useInitialFocus` — moves focus into the dialog when it opens (default: first focusable element in
+  DOM order; optional override via `initialFocusRef` on the model)
+- `useReturnFocus` — returns focus to `Dialog.Target` (or configured return target) when it closes
+- `useCloseOnEscape` — <kbd>Escape</kbd> closes the dialog
+- `useCloseOnOutsideClick` — pointer interaction outside closes the dialog
+- `useFocusRedirect` — <kbd>Tab</kbd> / <kbd>Shift</kbd>+<kbd>Tab</kbd> at the first or last
+  focusable element inside the dialog closes it and moves focus to the next or previous focusable
+  element on the page (non-modal; **not** a focus trap; does **not** change screen reader reading
+  order)
+
+**ARIA and DOM** (_applied by hooks/subcomponents_):
+
+- `Dialog.Card`: `role="dialog"`, `aria-labelledby` referencing the heading `id` (non-modal; page
+  content is not hidden with `aria-hidden`)
+- `Dialog.Popper`: sibling wrapper rendered when open with `aria-owns` pointing at `Dialog.Card` to
+  remap the accessibility tree for sequential reading order in supported browsers
+- `Dialog.Heading`: `id` wired to `Dialog.Card`'s `aria-labelledby`
+- `Dialog.CloseIcon` / `Dialog.CloseButton`: `onClick` that calls `model.events.hide()`
+- `Dialog.Target`: `ref` and `onClick` to open and to receive return focus
+
+**Keyboard** (_trigger is `Dialog.Target`, default `SecondaryButton`_):
+
+- <kbd>Enter</kbd> / <kbd>Space</kbd> on the trigger opens the dialog (standard button behavior)
+- On open and close, focus is managed by **`useInitialFocus`** and **`useReturnFocus`** (application
+  overrides: see **Focus management** in Accessibility Requirements)
+- <kbd>Tab</kbd> / <kbd>Shift</kbd>+<kbd>Tab</kbd> move focus forward and backward through
+  interactive elements inside the dialog (standard sequential focus behavior)
+- <kbd>Escape</kbd> closes the dialog and returns focus per `useReturnFocus`
+
+**Screen reader expectations** (_when built-in behaviors are used as intended_):
+
+- On open, assistive technology should announce the first focused control (often a dismiss control),
+  the dialog name (`Dialog.Heading`), and `dialog` role
+- Background page content remains available to assistive technology—Dialog does **not** apply
+  **`aria-hidden`** to siblings or render the rest of the page inert (unlike
+  [**Modal**](https://workday.github.io/canvas-kit/?path=/docs/components-popups-modal--docs))
+- Reading order may follow on-screen order where `aria-owns` is honored; support varies by browser
+  and screen reader
+
+### Accessibility Requirements
+
+Required in application code for an accessible Dialog. Hoist **`useDialogModel`** when you need to
+configure focus targets. Rows marked _(conditional)_ apply only when the situation matches—otherwise
+omit.
+
+**If no design spec is provided:** use default focus behavior; omit **`initialFocusRef`**,
+**`returnFocusRef`**, **`aria-describedby`**, **`aria-expanded`**, and **`aria-haspopup`**.
+
+**Focus management — defaults and developer prompts:** Canvas Kit handles open and close focus
+automatically. **State the default to the developer first.** Only set **`initialFocusRef`** or
+**`returnFocusRef`** after the developer (or an explicit design spec) chooses a non-default target.
+**Do not generate focus refs by default.**
+
+| When              | Default behavior                                                                                                                                                                            | Ask the developer before overriding                                                                                                                                                                        |
+| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Dialog **opens**  | **`useInitialFocus`** moves focus to the **first focusable element** in DOM order inside the dialog (often **`Dialog.CloseIcon`** or **`Dialog.CloseButton`**). Omit **`initialFocusRef`**. | _Which element should receive focus when the dialog opens?_ (Only when the default first focusable element is wrong for the design.) Attach **`initialFocusRef`** to that element on **`useDialogModel`**. |
+| Dialog **closes** | **`useReturnFocus`** moves focus to **`Dialog.Target`**. Omit **`returnFocusRef`**.                                                                                                         | _Which element should receive focus when the dialog closes?_ (Only when return focus should land somewhere other than **`Dialog.Target`**.)                                                                |
+
+If close **removes the trigger from the DOM**, **`returnFocusRef`** alone is not enough—move focus
+after the UI updates (for example with **`useLayoutEffect`**). See
+[Modal > Return Focus](https://workday.github.io/canvas-kit/?path=/docs/components-popups-modal--docs#return-focus).
+
+**Custom targets** _(conditional)_: Apply when using a custom **`as`** component on
+**`Dialog.Target`**. **`Dialog.Target`** adds **`onClick`** and **`ref`**. Custom targets must
+forward both to a **keyboard-focusable** element (prefer a native **`<button>`** or
+**`as={SecondaryButton}`** / another Canvas Kit button). Wrap the component in
+**`React.forwardRef`** when it does not forward refs by default (required if the dialog can open
+programmatically before the user clicks the target).
+
+| Requirement                                                   | How to satisfy                                                                                                                                                                                                                                                                                                                                                             |
+| ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Accessible dialog name                                        | Use **`Dialog.Heading`** so `aria-labelledby` on `Dialog.Card` references a visible title. Do not omit the heading: **`Dialog.Card` always sets `aria-labelledby`**, and an `aria-label` fallback is unreliable when that ID does not exist.                                                                                                                                |
+| Dismiss control                                               | Provide a way to close the dialog: **`Dialog.CloseButton`** with visible text (no extra **`aria-label`** needed), and/or **`Dialog.CloseIcon`** for icon-only dismiss (requires **`Tooltip`** or translated **`aria-label`**).                                                                                                                                             |
+| Keyboard-operable trigger                                     | See **Custom targets** above.                                                                                                                                                                                                                                                                                                                                              |
+| Supplementary copy when overriding open focus _(conditional)_ | When **`initialFocusRef`** places open focus **below** **`Dialog.Heading`**, assign a unique `id` to supplementary text and pass **`aria-describedby`** on **`Dialog.Card`**. See **Open focus below the heading** below and [Popup > Initial Focus](https://workday.github.io/canvas-kit/?path=/docs/components-popups-popup--docs#initial-focus) (button-focus variant). |
+| Open/closed state on the trigger _(conditional)_              | See **Wiring aria-expanded** below. **Default:** omit **`aria-expanded`** and **`aria-haspopup`**.                                                                                                                                                                                                                                                                         |
+
+**Open focus below the heading** _(conditional; see supplementary copy row above)_:
+
+When open focus moves past the heading (for example into a form field), wire **`aria-describedby`**
+so assistive technology still announces the supplementary copy. For focusing a primary action
+instead of an input, see
+[Popup > Initial Focus](https://workday.github.io/canvas-kit/?path=/docs/components-popups-popup--docs#initial-focus).
+
+```tsx
+import React from 'react';
+
+import {useUniqueId} from '@workday/canvas-kit-react/common';
+import {Dialog, useDialogModel} from '@workday/canvas-kit-react/dialog';
+import {FormField} from '@workday/canvas-kit-react/form-field';
+import {TextInput} from '@workday/canvas-kit-react/text-input';
+
+const Example = () => {
+  const descriptionId = useUniqueId();
+  const inputRef = React.useRef<HTMLInputElement>(null);
+  const model = useDialogModel({initialFocusRef: inputRef});
+
+  return (
+    <Dialog model={model}>
+      <Dialog.Target>Open</Dialog.Target>
+      <Dialog.Popper>
+        <Dialog.Card aria-describedby={descriptionId}>
+          <Dialog.CloseIcon aria-label="Close" />
+          <Dialog.Heading>Title</Dialog.Heading>
+          <Dialog.Body>
+            <p id={descriptionId}>Enter your email to continue.</p>
+            <FormField>
+              <FormField.Label>Email</FormField.Label>
+              <FormField.Input as={TextInput} ref={inputRef} />
+            </FormField>
+          </Dialog.Body>
+          <Dialog.CloseButton>Cancel</Dialog.CloseButton>
+        </Dialog.Card>
+      </Dialog.Popper>
+    </Dialog>
+  );
+};
+```
+
+**Summary for code generation:**
+
+- **REQUIRED:** accessible name, dismiss control, keyboard-operable trigger
+- **CONDITIONAL:** **`initialFocusRef`**, **`returnFocusRef`**, **`aria-describedby`**,
+  **`aria-expanded`** / **`aria-haspopup`**, **`forwardRef`** on custom **`Dialog.Target`**
+
+**Wiring aria-expanded** _(conditional)_:
+
+The **`aria-expanded`** pattern is **uncommon** for Dialog—omit **`aria-expanded`** and
+**`aria-haspopup`** unless a review deliberately keeps open focus on the trigger (for example
+**`initialFocusRef`** on the trigger per design spec). When required, on **`Dialog.Target`** set
+**`aria-expanded={model.state.visibility !== 'hidden'}`** and **`aria-haspopup="dialog"`**. See
+**Focus management** and the open/closed-state row above. If the design should not move focus into
+the dialog on open, use
+[**Popup**](https://workday.github.io/canvas-kit/?path=/docs/components-popups-popup--docs) with
+composed hooks instead of overriding Dialog defaults.
+
+### Anti-Patterns
+
+Do **not** generate code that does the following (see **Accessibility Requirements** above for what
+to supply instead):
+
+- Manually set `role="dialog"`, `aria-labelledby`, `aria-owns`, or dialog `id` on **`Dialog.Card`**,
+  **`Dialog.Popper`**, or **`Dialog.Heading`** — Canvas Kit hooks wire these
+- Omit **`Dialog.Popper`**, render **`Dialog.Card`** outside it, or add a custom portal/restructure
+  instead of **`Dialog` → `Dialog.Popper` → `Dialog.Card`**
+- Use **`open`** / **`onClose`** props on **`Dialog`** — Dialog has no controlled visibility props;
+  use **`useDialogModel`** and **`model.events.show()`** / **`model.events.hide()`**
+- Add **`useFocusTrap`**, **`aria-modal="true"`**, or **`aria-hidden`** on page siblings expecting
+  modal behavior — Dialog is intentionally non-modal
+- Use **Modal** when the task is non-critical or the rest of the page must stay operable
+- Set **`initialFocusRef`** or **`returnFocusRef`** by default — state the default focus behavior
+  first and ask the developer before overriding (see **Focus management** in Accessibility
+  Requirements)
+- Add **`aria-expanded`** / **`aria-haspopup`** on the default Dialog path, or bind
+  **`aria-expanded`** to a static value (see **Wiring aria-expanded** in Accessibility Requirements)
+- Use a custom **`Dialog.Target`** **`as`** component that does not forward **`ref`** to a focusable
+  element — use **`React.forwardRef`** or a Canvas Kit button component instead
+- Rely on **`returnFocusRef`** alone when close **removes the trigger from the DOM** (see
+  [Modal > Return Focus](https://workday.github.io/canvas-kit/?path=/docs/components-popups-modal--docs#return-focus))
+- Nest multiple **`Dialog`** instances without deliberate initial focus and return-focus planning
+- Assume **`useFocusRedirect`** fixes screen reader reading order, or that **`aria-owns`** remapping
+  works in all browser and screen reader combinations — test your supported combinations
 
 ## Component API
 

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

@@ -1,20 +1,21 @@
 import {ExampleCodeBlock, Specifications, SymbolDoc} from '@workday/canvas-kit-docs';
+
+import AllFields from './examples/AllFields';
 import Basic from './examples/Basic';
 import Caution from './examples/Caution';
-import Error from './examples/Error';
+import Custom from './examples/Custom';
+import CustomId from './examples/CustomId';
 import Disabled from './examples/Disabled';
+import Error from './examples/Error';
+import GroupedInputs from './examples/GroupedInputs';
+import Grow from './examples/Grow';
 import HiddenLabel from './examples/HiddenLabel';
-import LabelPositionHorizontalStart from './examples/LabelPositionHorizontalStart';
+import Hint from './examples/Hint';
 import LabelPositionHorizontalEnd from './examples/LabelPositionHorizontalEnd';
+import LabelPositionHorizontalStart from './examples/LabelPositionHorizontalStart';
 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';
 
 
 # Canvas Kit Form Field
@@ -134,14 +135,16 @@ for required fields are suffixed by a red asterisk.
 ### 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 screen readers to
-automatically announce the legend's context when focusing on the inputs in the group.
+`RadioGroup` or a group of `Checkbox`'s. `FormFieldGroup` renders a `div` with `role="group"` and an
+`aria-labelledby` reference. `FormFieldGroup.Label` renders a `div` with an `id` referenced by the
+`aria-labelledby` of the `FormFieldGroup`. Screen readers announce the group label when focusing
+controls in the group.
 
 `FormFieldGroup` supports the same props of `FormField`:
 
 - `error`: `"caution" | "error"` Defines the error around the whole group of inputs.
-- `orientation`: `"horizontal" | "vertical"` Defines the legend placement.
+- `orientation`: `"vertical" | "horizontalStart" | "horizontalEnd"` Defines the group label
+  placement.
 - `isRequired`: `true` Defines if a group like RadioGroup is required.
 
 <ExampleCodeBlock code={GroupedInputs} />
@@ -149,7 +152,7 @@ automatically announce the legend's context when focusing on the inputs in the g
 > **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.
+> (group label) provides critical context for screen reader users in these situations.
 
 ### Custom
 
@@ -200,21 +203,70 @@ check our
 
 ## 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.
+`FormField` provides essential accessibility features to ensure form inputs have a programmatically
+determinable name, relationships, and instructions. The primary accessibility goal is to ensure
+assistive technology users can identify every field, understand how to complete it, and hear hints,
+errors, and required state when the form input receives focus.
+
+### Minimum Accessible Structure
 
-### Label Association
+```tsx
+import {FormField} from '@workday/canvas-kit-react/form-field';
+import {TextInput} from '@workday/canvas-kit-react/text-input';
 
-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.
+<FormField>
+  <FormField.Label>Email</FormField.Label>
+  <FormField.Field>
+    <FormField.Input as={TextInput} />
+    <FormField.Hint>We'll never share your email.</FormField.Hint>
+  </FormField.Field>
+</FormField>;
+```
+
+Include **`FormField.Hint`** whenever there is hint or error text—the wiring slot for
+`aria-describedby` exists by default (see **Built-in Behaviors**).
+
+### Built-in Behaviors
+
+Canvas Kit applies these automatically when you compose `FormField` with its subcomponents. **Do not
+duplicate them** in consuming code.
+
+**ARIA and DOM** (_applied by subcomponents_):
+
+- `FormField.Label`: `<label>` with `htmlFor` matching the `id` on `FormField.Input` (`input-{id}`).
+  Clicking the label moves focus to the input.
+- `FormField.Input`: `id` (`input-{id}`), `aria-labelledby` (`label-{id}`), `aria-describedby`
+  (`hint-{id}` when an `id` exists), `required` when `isRequired`, and `aria-invalid="true"` when
+  `error="error"`. Caution (`error="caution"`) does **not** set `aria-invalid`.
+- `FormField.Hint`: `id="hint-{id}"` for description association.
+- Generated IDs: `label-{id}`, `input-{id}`, and `hint-{id}` from the `FormField` `id`
+  (auto-generated or custom via the `id` prop).
+- `FormFieldGroup`: `role="group"` with `aria-labelledby` referencing `FormFieldGroup.Label`.
+- Composite controls (for example, `MultiSelect`) forward `aria-labelledby` to related sub-elements
+  (combobox, listbox) so every part shares the same accessible name.
+
+**Implementation note on `aria-describedby`:** `FormField.Input` always sets
+`aria-describedby="hint-{id}"` when an `id` exists, even if `FormField.Hint` is not rendered. Always
+render `FormField.Hint` when there is hint or error text. Omitting `FormField.Hint` leaves a
+dangling `aria-describedby` reference.
+
+**Keyboard** (_standard form control behavior_):
+
+- <kbd>Tab</kbd> / <kbd>Shift</kbd>+<kbd>Tab</kbd> move focus to and from the input (native tab
+  order)
+- Clicking `FormField.Label` moves focus to the associated input (native `<label>` behavior)
+- Checkbox, radio, and composite controls follow the wrapped input component's own keyboard patterns
 
-For example, the DOM will look something like this:
+**Screen reader expectations** (_when built-in behaviors are used as intended_):
+
+- On focus, assistive technology announces the field label and, when applicable: required state,
+  invalid state (`error="error"`), and hint or error text via `aria-describedby`
+- The Caution state is visual only —`aria-invalid` is **not** set for `error="caution"`
+- In a `FormFieldGroup`, the group label is associated via `aria-labelledby`; focusing a control in
+  the group includes the group name in context
+- Disabled inputs are skipped in the tab order and may be announced as unavailable
+
+For a simple field, the DOM looks like:
 
 ```html
 <div>
@@ -223,38 +275,115 @@ For example, the DOM will look something like this:
 </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:
+Some composite controls such as `MultiSelect`, have additional sub-elements that also need to be
+linked to the `FormField.Label`. In the example below, the FormField.Label is applied to both the
+`input[role=combobox]` element and the `ul[role=listbox]` element so that screen reader knows that
+the label for both is the "States you've lived in".
 
 ```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>
+  <input
+    id="input-abc"
+    aria-labelledby="label-abc"
+    role="combobox"
+    aria-expanded="false"
+    aria-autocomplete="list"
+    aria-controls="listbox-abc"
+    type="text"
+  />
+  <ul id="listbox-abc" role="listbox" aria-labelledby="label-abc">
+    <li role="option">Texas</li>
+    <li role="option">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".
+For a field in an error state, the error text is referenced using `aria-describedby`. The rendered
+markup looks like:
 
-### Label Text Best Practices
+```html
+<div>
+  <label id="label-abc" for="input-abc">Password</label>
+  <input
+    id="input-abc"
+    aria-labelledby="label-abc"
+    aria-describedby="hint-abc"
+    required
+    aria-invalid="true"
+  />
+  <p id="hint-abc">Error: Must contain a number and a capital letter</p>
+</div>
+```
 
-- **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.
+For grouped checkbox controls, compose a `FormFieldGroup` with `FormFieldGroup.Label` and
+`FormFieldGroup.Input`. The rendered markup looks like:
 
-### Screen Reader Experience
+```html
+<div role="group" aria-labelledby="label-abc">
+  <div id="label-abc">Pizza toppings:</div>
+  <div>
+    <input type="checkbox" id="checkbox-1" />
+    <label for="checkbox-1">Pepperoni</label>
+  </div>
+  <div>
+    <input type="checkbox" id="checkbox-2" />
+    <label for="checkbox-2">Mushrooms</label>
+  </div>
+  <div>
+    <input type="checkbox" id="checkbox-3" />
+    <label for="checkbox-3">Pineapple</label>
+  </div>
+</div>
+```
 
-- 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.
+### Accessibility Requirements
+
+Required in application code for accessible form fields. Rows marked _(conditional)_ apply only when
+the situation matches—otherwise omit.
+
+**If no design spec is provided:** use a visible `FormField.Label`, wrap the input with
+`FormField.Input`, omit `isHidden`, and omit a custom `id` unless testing or composition requires
+it.
+
+| Requirement                        | How to satisfy                                                                                                                                                                               |
+| ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Visible label                      | **`FormField.Label`** with concise, meaningful text                                                                                                                                          |
+| Input wiring                       | **`FormField.Input as={...}`** wrapping every Canvas Kit input (`TextInput`, `Select`, `TextArea`, etc.)                                                                                     |
+| 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                                                                                         |
+| Group label _(conditional)_        | **`FormFieldGroup`** + **`FormFieldGroup.Label`** for radio buttons, checkbox groups, or related inputs. Alternatively, **`FormField as="fieldset"`** with **`FormField.Label as="legend"`** |
+| Hidden label _(conditional)_       | **`FormField.Label isHidden`** only when an equally clear alternative exists (for example, a universally recognizable search icon)                                                           |
+| Stable IDs _(conditional)_         | `id` prop on **`FormField`** when multiple fields share a page or predictable `label-`, `input-`, and `hint-` IDs are needed for testing or custom composition                               |
+
+**Summary for code generation:**
+
+- **REQUIRED:** visible label, input wiring
+- **CONDITIONAL:** hint/error text, required state, group label, hidden label, stable `id`
+
+### Anti-Patterns
+
+Do **not** generate code that does the following (see **Accessibility Requirements** above for what
+to supply instead):
+
+- Manually set `id`, `htmlFor`, `aria-labelledby`, `aria-describedby`, `aria-invalid`, or `required`
+  on **`FormField.Input`** or **`FormField.Label`** — Canvas Kit subcomponents wire these
+  automatically
+- **Unlabeled inputs**: Do not use Canvas Kit inputs 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.
+- **Color-only errors**: Do not set `error="error"` without descriptive text in `FormField.Hint`.
+- **Caution for invalid values**: Do not use `error="caution"` when a value is invalid; use
+  `error="error"` so `aria-invalid` is exposed.
+- **Broken ID references**: Do not point `aria-labelledby` or `aria-describedby` at missing or empty
+  elements; ensure `FormField.Label` and `FormField.Hint` render meaningful content.
+- **Skipping group labels**: Do not render `RadioGroup` or multiple related checkboxes without
+  `FormFieldGroup` and `FormFieldGroup.Label` (or `FormField` with `as="fieldset"` and
+  `FormField.Label as="legend"`).
+- **Disabled when read-only fits**: Avoid `disabled` on `FormField.Input` when users only need to
+  view data; disabled fields are harder to perceive and are removed from the tab order.
 
 ## Component API