@workday/canvas-kit-docs 16.2.1 → 16.2.3

package/dist/es6/lib/docs.js

@@ -94223,7 +94223,7 @@ export const docs = (typeof window !== 'undefined' && window.__docs) ||
             ]
           },
           "required": false,
-          "description": "Use this attribute when you have a `FormField` that is in an `Alert` | `Error` or `Required` state. This will add attach an `aria-describedby` to each radio input so that screen readers can read out the message attached to the form field.\nThe value of this attribute needs to match the value passed to `hintId` on the `FormField`.\n\n```tsx\n<FormField\n   error=\"caution\"\n   hintId=\"hint-alert\"\n   hintText=\"Deep dish is an extra $2.99\"\n   label=\"Choose Your Pizza Crust\"\n   useFieldset={true}\n >\n   <RadioGroup\n     name=\"crust\"\n     onChange={handleChange}\n     initialValue={value}\n     aria-describedby=\"hint-alert\"\n   >\n     <RadioGroup.RadioButton value=\"deep-dish\">Deep dish</RadioGroup.RadioButton>\n     <RadioGroup.RadioButton value=\"thin\">Thin</RadioGroup.RadioButton>\n     <RadioGroup.RadioButton value=\"gluten-free\">Gluten free</RadioGroup.RadioButton>\n     <RadioGroup.RadioButton value=\"cauliflower\">Cauliflower</RadioGroup.RadioButton>\n   </RadioGroup>\n</FormField>\n```",
+          "description": "The id of hint or error text associated with each radio.\n\nDo not set this when radios are wrapped in `FormFieldGroup.Input`. `FormFieldGroup.Input`\nwrites `aria-describedby=\"hint-{id}\"` on each radio, and that value overrides\n`aria-describedby` set on `RadioGroup`. Put the message in `FormFieldGroup.Hint`.\n\n```tsx\n<FormFieldGroup error=\"caution\">\n  <FormFieldGroup.Label>Choose Your Pizza Crust</FormFieldGroup.Label>\n  <FormFieldGroup.Field>\n    <FormFieldGroup.List as={RadioGroup} name=\"crust\" value={value} onChange={handleChange}>\n      <FormFieldGroup.Input as={RadioGroup.RadioButton} value=\"deep-dish\">\n        Deep dish\n      </FormFieldGroup.Input>\n      <FormFieldGroup.Input as={RadioGroup.RadioButton} value=\"thin\">\n        Thin\n      </FormFieldGroup.Input>\n    </FormFieldGroup.List>\n    <FormFieldGroup.Hint>Deep dish is an extra $2.99.</FormFieldGroup.Hint>\n  </FormFieldGroup.Field>\n</FormFieldGroup>\n```",
           "declarations": [
             {
               "name": "aria-describedby",
@@ -94574,7 +94574,7 @@ export const docs = (typeof window !== 'undefined' && window.__docs) ||
             ]
           },
           "required": false,
-          "description": "Use this attribute when you have a `FormField` that is in an `Alert` | `Error` or `Required` state. This will add attach an `aria-describedby` to each radio input so that screen readers can read out the message attached to the form field.\nThe value of this attribute needs to match the value passed to `hintId` on the `FormField`.\n\n```tsx\n<FormField\n   error=\"caution\"\n   hintId=\"hint-alert\"\n   hintText=\"Deep dish is an extra $2.99\"\n   label=\"Choose Your Pizza Crust\"\n   useFieldset={true}\n >\n   <RadioGroup\n     name=\"crust\"\n     onChange={handleChange}\n     initialValue={value}\n     aria-describedby=\"hint-alert\"\n   >\n     <RadioGroup.RadioButton value=\"deep-dish\">Deep dish</RadioGroup.RadioButton>\n     <RadioGroup.RadioButton value=\"thin\">Thin</RadioGroup.RadioButton>\n     <RadioGroup.RadioButton value=\"gluten-free\">Gluten free</RadioGroup.RadioButton>\n     <RadioGroup.RadioButton value=\"cauliflower\">Cauliflower</RadioGroup.RadioButton>\n   </RadioGroup>\n</FormField>\n```",
+          "description": "The id of hint or error text associated with each radio.\n\nDo not set this when radios are wrapped in `FormFieldGroup.Input`. `FormFieldGroup.Input`\nwrites `aria-describedby=\"hint-{id}\"` on each radio, and that value overrides\n`aria-describedby` set on `RadioGroup`. Put the message in `FormFieldGroup.Hint`.\n\n```tsx\n<FormFieldGroup error=\"caution\">\n  <FormFieldGroup.Label>Choose Your Pizza Crust</FormFieldGroup.Label>\n  <FormFieldGroup.Field>\n    <FormFieldGroup.List as={RadioGroup} name=\"crust\" value={value} onChange={handleChange}>\n      <FormFieldGroup.Input as={RadioGroup.RadioButton} value=\"deep-dish\">\n        Deep dish\n      </FormFieldGroup.Input>\n      <FormFieldGroup.Input as={RadioGroup.RadioButton} value=\"thin\">\n        Thin\n      </FormFieldGroup.Input>\n    </FormFieldGroup.List>\n    <FormFieldGroup.Hint>Deep dish is an extra $2.99.</FormFieldGroup.Hint>\n  </FormFieldGroup.Field>\n</FormFieldGroup>\n```",
           "declarations": [
             {
               "name": "aria-describedby",

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.2.1",
-    "@workday/canvas-kit-preview-react": "16.2.1",
-    "@workday/canvas-kit-react": "16.2.1",
-    "@workday/canvas-kit-react-fonts": "^16.2.1",
-    "@workday/canvas-kit-styling": "16.2.1",
+    "@workday/canvas-kit-labs-react": "16.2.3",
+    "@workday/canvas-kit-preview-react": "16.2.3",
+    "@workday/canvas-kit-react": "16.2.3",
+    "@workday/canvas-kit-react-fonts": "^16.2.3",
+    "@workday/canvas-kit-styling": "16.2.3",
     "@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.2.1",
-    "@workday/canvas-kit-preview-react": "16.2.1",
-    "@workday/canvas-kit-react": "16.2.1",
-    "@workday/canvas-kit-react-fonts": "^16.2.1",
-    "@workday/canvas-kit-styling": "16.2.1",
+    "@workday/canvas-kit-labs-react": "16.2.3",
+    "@workday/canvas-kit-preview-react": "16.2.3",
+    "@workday/canvas-kit-react": "16.2.3",
+    "@workday/canvas-kit-react-fonts": "^16.2.3",
+    "@workday/canvas-kit-styling": "16.2.3",
     "@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/preview-react/radio/Radio.mdx

@@ -2,14 +2,14 @@ import {ExampleCodeBlock, SymbolDoc} from '@workday/canvas-kit-docs';
 
 import Basic from './examples/Basic';
 import Caution from './examples/Caution';
+import Custom from './examples/Custom';
+import Disabled from './examples/Disabled';
 import Error from './examples/Error';
 import Inverse from './examples/Inverse';
 import LabelPosition from './examples/LabelPosition';
 import NoValue from './examples/NoValue';
 import RefForwarding from './examples/RefForwarding';
-import Disabled from './examples/Disabled';
 import Required from './examples/Required';
-import Custom from './examples/Custom';
 import StandaloneRadio from './examples/StandaloneRadio';
 
 
@@ -32,22 +32,20 @@ yarn add @workday/canvas-kit-preview-react
 Our radio component includes a `RadioGroup` container and `RadioGroup.RadioButton`, which renders an
 individual radio button. Nest related `RadioGroup.RadioButton` buttons within a `RadioGroup` and
 provide a `name` prop to the `RadioGroup` to group the radio buttons together. Each
-`RadioGroup.Radio` must have a unique `value`. This value is used in conjunction with the `value`
-prop set on the `RadioGroup` to determine which radio button is selected. To tie it all together,
-provide an `onChange` handler to the `RadioGroup` to track the selected value as it changes.
+`RadioGroup.RadioButton` must have a unique `value`. This value is used in conjunction with the
+`value` prop set on the `RadioGroup` to determine which radio button is selected. To tie it all
+together, provide an `onChange` handler to the `RadioGroup` to track the selected value as it
+changes.
 
-`RadioGroup` should be used in tandem with [Form Field](/components/inputs/form-field/) where the
-`useFieldset` prop is set to `true` to meet accessibility standards. This ensures the `label` text
-from `FormField` is attached to the `RadioGroup` and read out as a group for voiceover.
+`RadioGroup` should be used in tandem with
+[FormFieldGroup](/components/inputs/form-field/#accessibility). `FormFieldGroup.Label` names the
+group, and `FormFieldGroup.Input` associates hint, error, and required state with each radio.
 
 <ExampleCodeBlock code={Basic} />
 
 Our example uses [React state](<(https://react.dev/learn/state-a-components-memory)>) to track the
 value of the `RadioGroup`.
 
-`RadioGroup` and `RadioGroup.Radio` support keyboard navigation through the proper use of WAI-ARIA
-[properties](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/radiogroup_role#associated_wai-aria_roles_states_and_properties).
-
 ### Inverse
 
 Set the `variant` prop of `RadioGroup.RadioButton` to `inverse` to ensure proper contrast on dark
@@ -78,7 +76,7 @@ input component. By default, the orientation will be set to `vertical`.
 
 ### Required
 
-Set the `required` prop of the wrapping `FormField` to `true` to indicate that the field is
+Set the `isRequired` prop of the wrapping `FormFieldGroup` to `true` to indicate that the field is
 required. Labels for required fields are suffixed by a red asterisk.
 
 <ExampleCodeBlock code={Required} />
@@ -110,12 +108,9 @@ some behavior handled for you.
 
 ### Error States
 
-Set the `error` prop of the wrapping `FormField` to `"caution"` or
-`"error"` to set the `RadioGroup` to the alert or error state, respectively. You
-will also need to set the `hintId` and `hintText` props on the `FormField` to meet accessibility
-standards. You must set an `aria-describedby` attribute on the `RadioGroup` element that matches the
-value of `hintId` set on the `FormField` element. These attributes ensure that the alert message is
-associated to the `RadioGroup` and read out by voiceover.
+Set the `error` prop of the wrapping `FormFieldGroup` to `"caution"` or `"error"` to set the group
+to the alert or error state. Put the message in `FormFieldGroup.Hint`. `FormFieldGroup.Input`
+associates that text with each radio.
 
 #### Caution
 
@@ -141,6 +136,126 @@ Radio and its subcomponents support custom styling via the `cs` prop. For more i
 our
 ["How To Customize Styles"](https://workday.github.io/canvas-kit/?path=/docs/styling-guides-customizing-styles--docs).
 
+## Accessibility
+
+The primary accessibility goal is to ensure users can identify the radio group and each option,
+determine which option is selected, and hear associated hints, errors, and required state when a
+radio receives focus. Use **Radio** when the user must choose one option from a list. For
+independent options, use
+[**Checkbox**](https://workday.github.io/canvas-kit/?path=/docs/components-inputs-checkbox--docs)
+instead.
+
+### Minimum Accessible Structure
+
+The following matches the [Basic Example](#basic-example): a **`FormFieldGroup`** with
+**`FormFieldGroup.List as={RadioGroup}`**, and two or more
+**`FormFieldGroup.Input as={RadioGroup.RadioButton}`** options.
+
+```tsx
+import {RadioGroup} from '@workday/canvas-kit-preview-react/radio';
+import {FormFieldGroup} from '@workday/canvas-kit-react/form-field';
+
+<FormFieldGroup>
+  <FormFieldGroup.Label>Choose Your Pizza Crust</FormFieldGroup.Label>
+  <FormFieldGroup.Field>
+    <FormFieldGroup.List as={RadioGroup}>
+      <FormFieldGroup.Input as={RadioGroup.RadioButton}>Deep dish</FormFieldGroup.Input>
+      <FormFieldGroup.Input as={RadioGroup.RadioButton}>Thin</FormFieldGroup.Input>
+    </FormFieldGroup.List>
+  </FormFieldGroup.Field>
+</FormFieldGroup>;
+```
+
+Each option needs visible text. See the [Basic Example](#basic-example) for selection behavior.
+
+### Built-in Behaviors
+
+Canvas Kit applies these automatically when you compose **`FormFieldGroup`** with **`RadioGroup`**.
+**Do not duplicate them** in consuming code.
+
+**ARIA and DOM** (_applied by `RadioGroup` and `FormFieldGroup`_):
+
+- **`RadioGroup`**: Renders a `div`. It does not set `role="radiogroup"`.
+- **`RadioGroup.RadioButton`**: Renders a `<label>` around `<input type="radio">` and the visible
+  text. The wrapping `<label>` is the association, so an `htmlFor` pairing is not needed. That text
+  is the option's accessible name, and clicking it selects the radio.
+
+**Keyboard** (_native radio behavior_):
+
+**`RadioGroup`** uses native radio keyboard behavior. <kbd>Tab</kbd> moves to the selected radio, or
+to the first radio when none is selected, and then leaves the group. Arrow keys move and select
+within the group.
+
+**Screen reader expectations** (_when built-in behaviors are used as intended_):
+
+- On focus, assistive technology announces the group name from **`FormFieldGroup.Label`**, along
+  with the option name, radio role, and checked state.
+- When applicable, it also announces required state, invalid state (`error="error"`), and hint or
+  error text. Caution does not set `aria-invalid`.
+- Disabled radios are announced as unavailable.
+
+For group, hint, error, and required association, see
+[FormField's Built-in Behaviors](/components/inputs/form-field/#built-in-behaviors).
+
+### Accessibility Requirements
+
+Required in application code for an accessible Radio group. Rows marked _(conditional)_ apply only
+when the situation matches—otherwise omit.
+
+**If no design spec is provided:** use a visible **`FormFieldGroup.Label`**. On
+**`FormFieldGroup.List as={RadioGroup}`**, set a shared **`name`** and render two or more
+**`RadioGroup.RadioButton`** options with visible text and their own **`value`**. Omit **`error`**,
+**`isRequired`**, **`FormFieldGroup.Hint`**, **`disabled`**, **`aria-describedby`** on
+**`RadioGroup`**, **`error`** on **`RadioGroup`**, a **`ref`**, and **`StyledRadioButton`** unless
+the spec requires them.
+
+**Programmatic focus** _(conditional — omit by default)_:
+
+Attach a **`ref`** only when the product must move focus to a radio after an action. Do not attach a
+**`ref`** or call `focus()` unless the design or developer asks for it. See
+[Ref Forwarding](#ref-forwarding).
+
+| Requirement                                | How to satisfy                                                                                                                                                                                                                                                                                                                                                                                           |
+| ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Group and option names                     | Use **`FormFieldGroup`** with a visible **`FormFieldGroup.Label`**. Render **`FormFieldGroup.List as={RadioGroup}`** with a shared **`name`**, and give every **`FormFieldGroup.Input as={RadioGroup.RadioButton}`** visible text and its own **`value`**. The shared **`name`** groups the inputs, and each option **`value`** is what the selected state matches. See [Basic Example](#basic-example). |
+| Error state _(conditional)_                | When the selection is invalid, set `error="error"` on **`FormFieldGroup`** and prefix **`FormFieldGroup.Hint`** with "Error:". See [Error States](#error-states).                                                                                                                                                                                                                                        |
+| Hint, caution, or required _(conditional)_ | On **`FormFieldGroup`**, use **`FormFieldGroup.Hint`** for hint text, `error="caution"` for caution, and **`isRequired`** for required state, only when the spec includes that state. See [Required](#required) and [FormField accessibility](/components/inputs/form-field/#accessibility).                                                                                                             |
+| Disabled _(conditional)_                   | Set **`disabled`** on an unavailable **`RadioGroup.RadioButton`**. Never disable the selected radio. See [Disabled](#disabled).                                                                                                                                                                                                                                                                          |
+
+**Summary for code generation:**
+
+- **REQUIRED:** **`FormFieldGroup`**, visible **`FormFieldGroup.Label`**,
+  **`FormFieldGroup.List as={RadioGroup}`** with a shared **`name`**, and two or more
+  **`RadioGroup.RadioButton`** options, each with visible text and its own **`value`**
+- **CONDITIONAL:** when the selection is invalid, `error="error"` on **`FormFieldGroup`** and
+  **`FormFieldGroup.Hint`** prefixed with "Error:". Hint text, `error="caution"`, and
+  **`isRequired`** only when the spec includes that state. Also **`disabled`** (not on the selected
+  radio). See [FormField accessibility](/components/inputs/form-field/#accessibility) for group
+  hint, caution, and required.
+
+### Anti-Patterns
+
+Do **not** generate code that does the following (see **Accessibility Requirements** above for what
+to supply instead):
+
+- Add `role="radiogroup"` to **`RadioGroup`** — **`FormFieldGroup`** provides the group semantics
+- Manually set `aria-checked`, `aria-invalid`, `aria-required`, or `aria-describedby` —
+  **`RadioGroup`** and **`FormFieldGroup.Input`** wire these attributes
+- Use **`FormField`** with `useFieldset`, or set `hintId` and `hintText` — group radios with
+  **`FormFieldGroup`** and put the message in **`FormFieldGroup.Hint`**
+- Wrap radios in **`FormField.Input`** — use **`FormFieldGroup.Input as={RadioGroup.RadioButton}`**
+- Use **`StyledRadioButton`** unless the spec requires a radio outside **`RadioGroup`**. In that
+  case supply accessible option and group names and the necessary behavior. See
+  [Standalone Radio Button](#standalone-radio-button)
+- Intercept <kbd>Tab</kbd> or arrow keys — native radio behavior moves and selects within the group
+- Set **`disabled`** on the selected radio — that removes the group's tab stop, so keyboard users
+  cannot move within the group. See [Disabled](#disabled)
+- Set **`error`** on **`RadioGroup`** — set it on **`FormFieldGroup`** so Canvas Kit provides both
+  the visual and accessible error state. See [Error States](#error-states)
+- Rely on color alone for an error or caution — include **`FormFieldGroup.Hint`**. Use
+  `error="error"` when the selection is invalid so `aria-invalid` is set. See
+  [Error States](#error-states)
+
 ## Component API
 
 <SymbolDoc name="RadioGroup" fileName="/preview-react/" />

package/dist/mdx/preview-react/radio/examples/Required.tsx

@@ -20,7 +20,6 @@ export default () => {
         name="crust-required"
         onChange={handleChange}
         value={value}
-        aria-describedby="choose-crust"
       >
         <FormFieldGroup.Input as={RadioGroup.RadioButton} value="deep-dish">
           Deep dish

package/dist/mdx/preview-react/switch/Switch.mdx

@@ -75,6 +75,125 @@ Switch supports right-to-left languages when specified in the CanvasProvider the
 Switch supports custom styling via the `cs` prop. For more information, check our
 ["How To Customize Styles"](https://workday.github.io/canvas-kit/?path=/docs/styling-guides-customizing-styles--docs).
 
+## Accessibility
+
+The primary accessibility goal is a visible, programmatically determinable name and an on or off
+state that assistive technology can expose. Use **Switch** for a single setting that takes effect
+immediately when toggled (for example, "Dark Mode"). When the user selects one or more options that
+are applied on form submission, use [**Checkbox**](/components/inputs/checkbox/) instead. **Switch**
+does not render its own `<label>`, so it relies on **`FormField`** for its name, hint, error, and
+required wiring — see [FormField's accessibility documentation](/components/inputs/form-field/#accessibility).
+
+### Minimum Accessible Structure
+
+The following matches the [Basic Example](#basic-example). Every **Switch** needs **`FormField`**, a
+visible **`FormField.Label`**, and **`FormField.Input as={Switch}`** inside **`FormField.Field`**.
+
+```tsx
+import React from 'react';
+
+import {Switch} from '@workday/canvas-kit-preview-react/switch';
+import {FormField} from '@workday/canvas-kit-react/form-field';
+
+const Example = () => {
+  
+  return (
+    <FormField>
+      <FormField.Label>Dark Mode</FormField.Label>
+      <FormField.Field>
+        <FormField.Input as={Switch} />
+      </FormField.Field>
+    </FormField>
+  );
+};
+```
+
+### Built-in Behaviors
+
+Canvas Kit applies these automatically when you compose **Switch** with **`FormField`**
+subcomponents. **Do not duplicate them** in consuming code.
+
+**ARIA and DOM** (_applied by Switch and FormField_):
+
+- **`Switch`**: Renders a native `<input type="checkbox">` with `role="switch"`. The native `checked`
+  state is exposed to assistive technology as on or off, so no `aria-checked` is needed. Canvas Kit
+  assigns an `id` with `useUniqueId` unless you pass **`id`**.
+- **Track, thumb, and check/x icon**: Purely visual. The icon is a Canvas Kit **`SystemIcon`**, whose
+  SVG markup sets `role="presentation"` and `focusable="false"`, so it is not announced.
+- **`disabled`**: Maps to the native `disabled` attribute.
+
+**Keyboard** (_native checkbox behavior_):
+
+**`Switch`** uses native `<input type="checkbox">` keyboard behavior (tab order and Space to
+toggle). Do not intercept <kbd>Space</kbd> or otherwise prevent the native toggle.
+
+**Screen reader expectations** (_when built-in behaviors are used as intended_):
+
+- On focus, assistive technology announces the **`FormField.Label`** text, the "switch" role, and
+  the on or off state; when applicable, required state, invalid state (`error="error"`), and
+  **`FormField.Hint`** text via `aria-describedby`
+- Toggling announces the new on or off state
+- The Caution state is visual only — `aria-invalid` is **not** set for `error="caution"`
+- Disabled switches are skipped in the tab order and may be announced as unavailable
+
+For label, hint, and error association details, see
+[FormField's Built-in Behaviors](/components/inputs/form-field/#built-in-behaviors).
+
+### Accessibility Requirements
+
+Required in application code for an accessible **Switch**. Rows marked _(conditional)_ apply only
+when the situation matches—otherwise omit.
+
+**If no design spec is provided:** use a visible **`FormField.Label`**, wrap the control with
+**`FormField.Input as={Switch}`** inside **`FormField.Field`**, and control it with **`checked`** and
+**`onChange`**. Omit **`isRequired`**, **`error`**, **`FormField.Hint`**, **`disabled`**,
+**`isHidden`**, a custom **`id`**, and a **`ref`** unless the spec requires them.
+
+**Programmatic focus** _(conditional — omit by default)_:
+
+Attach a `ref` only when the product must move focus to the Switch after an action. Do not attach a
+`ref` or call `focus()` unless the design or developer asks for it. See
+[Ref Forwarding](#ref-forwarding) under Usage for a complete Storybook example.
+
+| Requirement                             | How to satisfy                                                                                                                                                                                                                  |
+| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Accessible name                         | Visible, non-empty **`FormField.Label`** describing the setting (for example, "Dark Mode"), not the state ("On"/"Off"). Use **`FormField.Label isHidden`** only when an equally clear visible alternative exists               |
+| Input wiring                            | **`FormField.Input as={Switch}`** inside **`FormField.Field`**. See [FormField accessibility](/components/inputs/form-field/#accessibility) for label, hint, error, and required wiring                                         |
+| Required state _(conditional)_          | `isRequired` on **`FormField`** only when the form cannot be submitted unless the Switch is on — native `required` on a checkbox means it must be checked                                                                      |
+| Disabled _(conditional)_                | `disabled` on **`FormField.Input`** when the spec marks the setting unavailable. See [Disabled](#disabled)                                                                                                                      |
+| Programmatic focus _(conditional)_      | `ref` on **`FormField.Input`** and call `focus()` when the product requires it — omit by default (see **Programmatic focus** above and [Ref Forwarding](#ref-forwarding))                                                       |
+
+**Summary for code generation:**
+
+- **REQUIRED:** **`FormField`** + visible **`FormField.Label`** + **`FormField.Input as={Switch}`**
+  inside **`FormField.Field`**
+- **CONDITIONAL:** `isRequired` only when the Switch must be on; `disabled`; programmatic focus via
+  `ref`. See [FormField accessibility](/components/inputs/form-field/#accessibility) for shared
+  FormField conditionals (hint, error, and caution).
+
+### Anti-Patterns
+
+Do **not** generate code that does the following (see **Accessibility Requirements** above for what
+to supply instead):
+
+- Render **Switch** without **`FormField`** and **`FormField.Label`** — **Switch** has no built-in
+  label. For shared FormField anti-patterns (manual ARIA wiring, color-only errors, broken ID
+  references), see [FormField Anti-Patterns](/components/inputs/form-field/#anti-patterns)
+- Manually set `role`, `aria-checked`, `aria-labelledby`, `aria-describedby`, `aria-invalid`, or
+  `id` on **Switch** — Canvas Kit wires these from the native checkbox and **`FormField`**
+- Nest **`FormField`** inside **`FormField`** instead of using **`FormField.Field`** — the inner
+  **`FormField`** breaks the label association
+- Put the state in the label (for example, "Dark Mode: On") or add a visually hidden "on"/"off"
+  string — the state is already announced from `role="switch"` and `checked`
+- Set **`error`** directly on **Switch** inside **`FormField`** — set it on **`FormField`** so
+  `aria-invalid` and the visual ring stay in sync. Setting **`error`** on a Switch outside
+  **`FormField`** is visual only and does not set `aria-invalid`
+- Use **`isRequired`** for a setting that can validly be off
+- Use **Switch** for selections that only apply on form submission, or for multiple related
+  options — use [**Checkbox**](/components/inputs/checkbox/) instead
+- Use **`aria-disabled`** instead of **`disabled`** — **Switch** maps unavailability to the native
+  **`disabled`** attribute
+
 ## Component API
 
 <SymbolDoc name="Switch" fileName="/react/" />

package/dist/mdx/preview-react/switch/examples/Basic.tsx

@@ -11,7 +11,7 @@ export default () => {
   };
 
   return (
-    <FormField isRequired>
+    <FormField>
       <FormField.Label>Dark Mode</FormField.Label>
       <FormField.Field>
         <FormField.Input as={Switch} checked={checked} onChange={handleChange} />

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@workday/canvas-kit-docs",
-  "version": "16.2.1",
+  "version": "16.2.3",
   "description": "Documentation components of Canvas Kit components",
   "author": "Workday, Inc. (https://www.workday.com)",
   "license": "Apache-2.0",
@@ -47,10 +47,10 @@
     "@stackblitz/sdk": "^1.11.0",
     "@storybook/csf": "0.0.1",
     "@workday/canvas-expressive-icons-web": "1.0.2",
-    "@workday/canvas-kit-labs-react": "^16.2.1",
-    "@workday/canvas-kit-preview-react": "^16.2.1",
-    "@workday/canvas-kit-react": "^16.2.1",
-    "@workday/canvas-kit-styling": "^16.2.1",
+    "@workday/canvas-kit-labs-react": "^16.2.3",
+    "@workday/canvas-kit-preview-react": "^16.2.3",
+    "@workday/canvas-kit-react": "^16.2.3",
+    "@workday/canvas-kit-styling": "^16.2.3",
     "@workday/canvas-system-icons-web": "^5.0.3",
     "@workday/canvas-tokens-web": "^4.4.0",
     "markdown-to-jsx": "^7.2.0",
@@ -63,5 +63,5 @@
     "mkdirp": "^1.0.3",
     "typescript": "5.0"
   },
-  "gitHead": "24223441c4c032707012c80f81aa445981c5042d"
+  "gitHead": "dd5a27ab062642ac115722808e063150f7866115"
 }