@workday/canvas-kit-docs 16.0.14 → 16.0.16

package/dist/es6/lib/docs.js

@@ -13367,6 +13367,26 @@ export const docs = (typeof window !== 'undefined' && window.__docs) ||
           "kind": "string",
           "value": "tables"
         },
+        {
+          "kind": "string",
+          "value": "expandable-rows"
+        },
+        {
+          "kind": "string",
+          "value": "nested-rows"
+        },
+        {
+          "kind": "string",
+          "value": "selectable-rows"
+        },
+        {
+          "kind": "string",
+          "value": "filterable-column-headers"
+        },
+        {
+          "kind": "string",
+          "value": "sortable-column-headers"
+        },
         {
           "kind": "string",
           "value": "popups"
@@ -13431,6 +13451,26 @@ export const docs = (typeof window !== 'undefined' && window.__docs) ||
             "kind": "string",
             "value": "tables"
           },
+          {
+            "kind": "string",
+            "value": "expandable-rows"
+          },
+          {
+            "kind": "string",
+            "value": "nested-rows"
+          },
+          {
+            "kind": "string",
+            "value": "selectable-rows"
+          },
+          {
+            "kind": "string",
+            "value": "filterable-column-headers"
+          },
+          {
+            "kind": "string",
+            "value": "sortable-column-headers"
+          },
           {
             "kind": "string",
             "value": "popups"
@@ -13459,6 +13499,23 @@ export const docs = (typeof window !== 'undefined' && window.__docs) ||
       }
     }
   },
+  {
+    "name": "TABLE_PATTERN_SCENARIOS",
+    "fileName": "/home/runner/work/canvas-kit/canvas-kit/modules/mcp/lib/accessibility-enums.ts",
+    "description": "Pattern pages under Guides/Accessibility/Table Patterns, including the overview index.",
+    "declarations": [
+      {
+        "name": "TABLE_PATTERN_SCENARIOS",
+        "filePath": "/home/runner/work/canvas-kit/canvas-kit/modules/mcp/lib/accessibility-enums.ts"
+      }
+    ],
+    "tags": {},
+    "type": {
+      "kind": "unknown",
+      "value": "unknown",
+      "text": "readonly AccessibilityScenario[]"
+    }
+  },
   {
     "name": "ACCESSIBILITY_COMPONENTS",
     "fileName": "/home/runner/work/canvas-kit/canvas-kit/modules/mcp/lib/accessibility-enums.ts",
@@ -13960,7 +14017,7 @@ export const docs = (typeof window !== 'undefined' && window.__docs) ||
         "value": {
           "kind": "symbol",
           "name": "AccessibilityScenario",
-          "value": "\"aria-live\" | \"overview\" | \"page-structure\" | \"tables\" | \"popups\" | \"headers\" | \"side-panel\" | \"windows-high-contrast\" | \"forms\" | \"color-contrast\""
+          "value": "\"aria-live\" | \"overview\" | \"page-structure\" | \"tables\" | \"expandable-rows\" | \"nested-rows\" | \"selectable-rows\" | \"filterable-column-headers\" | \"sortable-column-headers\" | ... 5 more ... | \"color-contrast\""
         }
       }
     }
@@ -14009,7 +14066,7 @@ export const docs = (typeof window !== 'undefined' && window.__docs) ||
                 "type": {
                   "kind": "symbol",
                   "name": "AccessibilityScenario",
-                  "value": "\"aria-live\" | \"overview\" | \"page-structure\" | \"tables\" | \"popups\" | \"headers\" | \"side-panel\" | \"windows-high-contrast\" | \"forms\" | \"color-contrast\""
+                  "value": "\"aria-live\" | \"overview\" | \"page-structure\" | \"tables\" | \"expandable-rows\" | \"nested-rows\" | \"selectable-rows\" | \"filterable-column-headers\" | \"sortable-column-headers\" | ... 5 more ... | \"color-contrast\""
                 },
                 "description": "",
                 "declarations": [
@@ -14040,7 +14097,7 @@ export const docs = (typeof window !== 'undefined' && window.__docs) ||
         "value": {
           "kind": "symbol",
           "name": "AccessibilityScenario",
-          "value": "\"aria-live\" | \"overview\" | \"page-structure\" | \"tables\" | \"popups\" | \"headers\" | \"side-panel\" | \"windows-high-contrast\" | \"forms\" | \"color-contrast\""
+          "value": "\"aria-live\" | \"overview\" | \"page-structure\" | \"tables\" | \"expandable-rows\" | \"nested-rows\" | \"selectable-rows\" | \"filterable-column-headers\" | \"sortable-column-headers\" | ... 5 more ... | \"color-contrast\""
         }
       }
     }

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.14",
-    "@workday/canvas-kit-preview-react": "16.0.14",
-    "@workday/canvas-kit-react": "16.0.14",
-    "@workday/canvas-kit-react-fonts": "^16.0.14",
-    "@workday/canvas-kit-styling": "16.0.14",
+    "@workday/canvas-kit-labs-react": "16.0.16",
+    "@workday/canvas-kit-preview-react": "16.0.16",
+    "@workday/canvas-kit-react": "16.0.16",
+    "@workday/canvas-kit-react-fonts": "^16.0.16",
+    "@workday/canvas-kit-styling": "16.0.16",
     "@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.14",
-    "@workday/canvas-kit-preview-react": "16.0.14",
-    "@workday/canvas-kit-react": "16.0.14",
-    "@workday/canvas-kit-react-fonts": "^16.0.14",
-    "@workday/canvas-kit-styling": "16.0.14",
+    "@workday/canvas-kit-labs-react": "16.0.16",
+    "@workday/canvas-kit-preview-react": "16.0.16",
+    "@workday/canvas-kit-react": "16.0.16",
+    "@workday/canvas-kit-react-fonts": "^16.0.16",
+    "@workday/canvas-kit-styling": "16.0.16",
     "@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/accessibility/Popups.mdx

@@ -44,10 +44,6 @@ hooks. **Tradeoff:** the popup is constrained by ancestor `overflow` and positio
 
 <ExampleCodeBlock code={InlinePopupNoPortal} />
 
-For the same reading-order goal using a **portaled** popup mounted into a sentinel next to the
-trigger (with `PopupStack.pushStackContext`), see
-[**Testing > Inline Portals**](?path=/docs/guides-accessibility-testing-inline-portals--docs).
-
 ## 2. Reading order with `aria-owns`
 
 You can keep the default portal (content at the bottom of `body`) and still try to **re-parent** the
@@ -67,6 +63,6 @@ that card as “owned” by the trigger for browsing and announcements.
 The Canvas Kit [**Dialog**](?path=/docs/components-popups-dialog--docs) builds this pattern in.
 
 Another `aria-owns` example:
-[Advanced Tables > Table With Filterable Column Headers](?path=/docs/guides-accessibility-examples-advanced-tables--docs#filterable-column-headers).
+[Table Patterns > Filterable Column Headers](?path=/docs/guides-accessibility-table-patterns-filterable-column-headers--docs).
 
 <ExampleCodeBlock code={PopupAriaOwns} />

package/dist/mdx/accessibility/tables/ExpandableRows.mdx

@@ -0,0 +1,27 @@
+import {ExampleCodeBlock} from '@workday/canvas-kit-docs';
+
+import {ExpandableRows} from '../examples/Table/WithExpandableRows';
+
+
+## Expandable Rows
+
+Expandable Rows combines the likes of an accordion with tabular data tables. Column 1 renders icon
+buttons with 2 states, a collapsed and expanded state. A new row that spans the entire width of the
+table is added to the table just after the expanded row.
+
+- The `aria-expanded` property is added to the chevron button to communicate this state to screen
+  reader users.
+- A Canvas accessible `Tooltip` component is used to assign names to each icon button based on the
+  most useful value in the row. In this example, we combined the car make (in column 1) and model
+  (in column 2) together. This allows everyone to view the name of the icon buttons by hovering the
+  mouse or focusing with the keyboard.
+- The expanded row uses `colspan` to span the entire width of the table and support screen readers.
+  This space provides flexibility to show headings, lists, and other structured content for the
+  table row above.
+- There is no explicit relationship between a row of cells and the spanned content below it. The
+  spanned content is assumed to belong to the row of cells above it, based on established accordion
+  patterns and logical reading order of content rendered to the screen.
+- Outlining hierarchy with additional nested rows in the table is not supported for screen readers
+  in this example.
+
+<ExampleCodeBlock code={ExpandableRows} />

package/dist/mdx/accessibility/tables/FilterableColumnHeaders.mdx

@@ -0,0 +1,37 @@
+import {ExampleCodeBlock} from '@workday/canvas-kit-docs';
+
+import {FilterableColumnHeaders} from '../examples/Table/WithColumnHeaderFilters';
+
+
+## Filterable Column Headers
+
+In this example, we demonstrate using the `Popup` component in each column header allowing users to
+search and filter the data on the table. The `Popup` component relies on React Portals to render the
+popup elements at the bottom of the browser's DOM presenting 2 key challenges for accessibility:
+
+1. Keyboard focus order of the elements in the popup,
+2. Screen readers' reading order of the content rendered in the browser.
+
+Here's what we did about it:
+
+- Canvas Kit includes a `usePopupModel` hook, with quite a few additional hooks developers can add
+  to their models. In particular, the `useFocusRedirect` hook manages keyboard focus between the
+  `<Popup.Target>` button and the popup content.
+- The `useInitialFocus` hook allows developers to specify which element receives keyboard focus when
+  the popup appears. In this example, we auto-focused the search input field.
+- To address the reading order of content, we set the `aria-owns` property onto the parent
+  `<Table.Header>` component (`<th>` DOM element) with 2 unique `id` values. The first `id` refers
+  to the `<Popup.Target>` button and the second refers to the `<Popup.Card>` container element. This
+  manually reassigns the column header's `<Popup.Target>` button and the `Popup` contents as
+  siblings in the browser's accessibility tree hierarchy. Screen readers **should** read the column
+  header buttons and the popup content in sequential order even though they are not siblings in the
+  DOM.
+- The `type='description'` variant of the Canvas `Tooltip` is used to communicate the filtered state
+  of the column header, and assigned to the accessible description of the column header
+  `<TertiaryButton>` component.
+- The `AriaLiveRegion` component is used to render the "X of Y items" status inside the table
+  caption. This enables screen readers to automatically describe the filter state changes of the
+  table content to users in real time. We recommend validating whether this use of a live region is
+  well supported for your screen reader and browser combinations first.
+
+<ExampleCodeBlock code={FilterableColumnHeaders} />

package/dist/mdx/accessibility/tables/NestedRows.mdx

@@ -0,0 +1,38 @@
+import {ExampleCodeBlock} from '@workday/canvas-kit-docs';
+
+import {NestedRows} from '../examples/Table/WithNestedRows';
+
+
+## Nested Rows
+
+Nested Rows shows a hierarchy of related records in **one table**, using additional `<tr>` elements
+for child rows. Expanding a project reveals its phases; expanding a phase reveals its tasks. The
+chevron and name share the Name cell so they indent together. Collapsing a parent hides its
+descendants even if a child was previously expanded.
+
+This is a different pattern from
+[Expandable Rows](?path=/docs/guides-accessibility-table-patterns-expandable-rows--docs). That
+example inserts a `colspan` panel with extra content for a single parent row. It does **not** add
+nested table rows. Use Nested Rows when the children are themselves tabular records (same columns at
+every level). Use Expandable Rows when the extra content is not a row of the same table.
+
+- Child rows are siblings in the same `<tbody>`, not a nested `<table>` and not extra `<tbody>`
+  elements used to fake a tree.
+- The Name cell is the tree column: it holds the chevron `TertiaryButton` and the row name together
+  so the control stays next to the label it expands. Leaf rows keep an empty slot the same width as
+  the button so names line up with their siblings.
+- The `aria-expanded` property is added to the chevron button to communicate this state to screen
+  reader users.
+- A Canvas Kit `Tooltip` names each chevron **Project**, **Phase**, or **Task** based on the row's
+  depth. The visible name stays in the row header, so the button name describes the _kind_ of row
+  rather than repeating the label.
+- Since those button names are not unique, we added `aria-describedby` to each chevron, referencing
+  the unique `id` on the name text in the same cell. That gives screen readers the specific project
+  or phase the control belongs to, similar to the
+  [Selectable Rows](?path=/docs/guides-accessibility-table-patterns-selectable-rows--docs)
+  checkboxes.
+- `aria-level` is set on each `Table.Row` (`1` = project, `2` = phase, `3` = task) to describe
+  depth. Support for `aria-level` on HTML table rows is uneven across screen readers and browsers.
+  Validate the combinations you support. This is a research example, not a Canvas Kit primitive.
+
+<ExampleCodeBlock code={NestedRows} />

package/dist/mdx/accessibility/tables/Overview.mdx

@@ -0,0 +1,28 @@
+## Advanced Table Examples
+
+Tables should only be used to organize data that has a clear relationship between rows and columns,
+like a calendar or a schedule. Never use a table just for page layout.
+
+When you use the proper HTML table markup, a screen reader can help a user navigate the table. It
+will automatically read the column and row headers as they move through the data, so they always
+know what information they're looking at.
+
+- All tables should have a clear header and a descriptive title.
+- Keep your tables simple. If a table is too complex, it might be better to break it up into several
+  smaller tables or use a different format.
+
+Out of the box, `Table` is a lightweight compound component with a high degree of flexibility, but
+not much functionality outside of providing a basic table layout. This flexibility lets developers
+implement common features, such as selecting rows and sorting columns, on top of `Table` to meet
+their specific application needs.
+
+The Workday Accessibility Team has researched and developed the following examples to demonstrate
+how to build these accessible table patterns. We've listed the specific considerations and decisions
+we've made for each of the examples.
+
+- [Expandable Rows](?path=/docs/guides-accessibility-table-patterns-expandable-rows--docs)
+- [Nested Rows](?path=/docs/guides-accessibility-table-patterns-nested-rows--docs)
+- [Selectable Rows](?path=/docs/guides-accessibility-table-patterns-selectable-rows--docs)
+- [Filterable Column Headers](?path=/docs/guides-accessibility-table-patterns-filterable-column-headers--docs)
+- [Sortable Column Headers](?path=/docs/guides-accessibility-table-patterns-sortable-column-headers--docs)
+- [With Form Fields](?path=/docs/guides-accessibility-table-patterns-with-form-fields--docs)

package/dist/mdx/accessibility/tables/SelectableRows.mdx

@@ -0,0 +1,27 @@
+import {ExampleCodeBlock} from '@workday/canvas-kit-docs';
+
+import {SelectableRows} from '../examples/Table/WithSelectableRows';
+
+
+## Selectable Rows
+
+Using a `Checkbox` labeled "Select All" inside of a column header can be a confusing experience for
+screen reader users. Screen readers will automatically announce the "Select All" label in the column
+header each time users are reading any of the Check boxes in the first column. For instance, the
+`Checkbox` in row 4 is definitely not going to select all of the rows. Here is what we did about it:
+
+- We intentionally rendered row 1, column 1 as a standard `<td>` element so screen readers won't
+  automatically announce the "Select All" label while reading cells in column 1.
+- Our research found that VoiceOver (MacOS v12.7, Safari v17.1) persistently announce "Select All"
+  despite using the `<td>` element because of the optional `<thead>` element in the table. We
+  omitted the optional `<thead>` and `<tbody>` elements from this example for that reason.
+- We used Canvas Kit's `Tooltip` component to assign concise names to each Checkbox, describing
+  their purpose of selecting rows. This allows everyone to view the name of the checkboxes by
+  hovering the mouse or focusing with the keyboard.
+- Since each checkbox is not uniquely labeled, we added `aria-describedby` to the checkbox,
+  referencing the unique `id` of the row header cell. This practice gives screen readers more
+  context about which value each checkbox is refering to.
+- We rendered the cells in column 2 as the row headers for the table, enabling screen readers to
+  automatically announce the topping name even while reading down the Amounts in column 3.
+
+<ExampleCodeBlock code={SelectableRows} />

package/dist/mdx/accessibility/tables/SortableColumnHeaders.mdx

@@ -0,0 +1,23 @@
+import {ExampleCodeBlock} from '@workday/canvas-kit-docs';
+
+import {SortableColumnHeaders} from '../examples/Table/WithSortableColumnHeaders';
+
+
+## Sortable Column Headers
+
+The challenge in this example is to provide all of the necessary information about the interactive
+column headers, the sort state of the column, and instructions about how the table will be sorted
+without giving too much information to users while reading the data cells below.
+
+- The `aria-sort` property has been added to each of the `<Table.Header>` components (`<th>` DOM
+  element) and updated to `ascending` or `descending` to reflect the current sort state. We
+  recommend validating whether this property is well supported for your screen reader and browser
+  combinations first.
+- A `<TertiaryButton>` describing the column name is used inside of the `<Table.Header>` component.
+- The `description` variant of the Canvas `Tooltip` component is applied to the button in the column
+  header and applied to the accessible description of the button with the `aria-description`
+  property. This is used to describe how the column will be sorted when pressed and screen readers
+  will only read this description while focusing on the column headers, not while reading the data
+  cells below.
+
+<ExampleCodeBlock code={SortableColumnHeaders} />

package/dist/mdx/accessibility/{TestingTableWithFormFields.mdx → tables/WithFormFields.mdx}

@@ -1,5 +1,6 @@
 import {ExampleCodeBlock} from '@workday/canvas-kit-docs';
-import WithFormFields from './examples/Table/WithFormFields';
+
+import {WithFormFields} from '../examples/Table/WithFormFields';
 
 
 ## Table with form field components

package/dist/mdx/react/checkbox/Checkbox.mdx

@@ -1,8 +1,4 @@
-import {
-  ExampleCodeBlock,
-  Specifications,
-  SymbolDoc,
-} from '@workday/canvas-kit-docs';
+import {ExampleCodeBlock, Specifications, SymbolDoc} from '@workday/canvas-kit-docs';
 
 import Basic from './examples/Basic';
 import Caution from './examples/Caution';
@@ -34,7 +30,9 @@ yarn add @workday/canvas-kit-react
 
 Checkbox may be used on its own without [Form Field](/components/inputs/form-field/) since it
 includes a `<label>` with a `for` attribute referencing the underlying `<input type="checkbox">`
-element.
+element. For checkboxes grouped with **`FormFieldGroup`**, see
+[FormField accessibility](/components/inputs/form-field/#accessibility) for hint, error, caution,
+and required state wiring.
 
 <ExampleCodeBlock code={Basic} />
 
@@ -61,6 +59,9 @@ not all) of its children are checked.
 
 <ExampleCodeBlock code={Indeterminate} />
 
+> **Accessibility Note**: Use semantic unordered list markup so that screen readers can communicate
+> the nested hierarchy of the components to users.
+
 ### Ref Forwarding
 
 Checkbox supports [ref forwarding](https://reactjs.org/docs/forwarding-refs.html). It will forward
@@ -70,27 +71,32 @@ Checkbox supports [ref forwarding](https://reactjs.org/docs/forwarding-refs.html
 
 ### Label Position Horizontal
 
-Set the `orientation` prop of the Form Field to designate the position of the label relative to the
-input component. By default, the orientation will be set to `vertical`.
+Set the `orientation` prop of the wrapping FormFieldGroup to designate the position of the group
+label relative to the checkboxes. By default, the orientation will be set to `vertical`.
 
 <ExampleCodeBlock code={LabelPosition} />
 
 ### Required
 
-Set the `required` prop of a wrapping Form Field to `true` to indicate that the field is required.
-Labels for required fields are suffixed by a red asterisk.
+Set the `isRequired` prop of a wrapping FormFieldGroup to `true` to indicate that the field is
+required. Labels for required fields are suffixed by a red asterisk.
+
+A standalone checkbox does not need **`FormFieldGroup`**. This example wraps a single checkbox so
+`isRequired` can show the required asterisk on **`FormFieldGroup.Label`**. Use that wrapper only
+when the spec includes a required state (or a group name, hint, error, or caution). See
+[Accessibility](#accessibility).
 
 <ExampleCodeBlock code={Required} />
 
 ### Error States
 
-Set the `error` prop of the wrapping Form Field to `"caution"` or `"error"` to set the Checkbox to
-the Alert or Error state, respectively. You will also need to set the `hintId` and `hintText` props
-on the Form Field to meet accessibility standards. You may wish to omit the `label` prop on the Form
-Field given that Checkbox already includes a label.
+Set the `error` prop of the wrapping FormFieldGroup to `"caution"` or `"error"` to set the Checkbox
+to the Alert or Error state, respectively. Render `FormFieldGroup.Hint` with the message text so
+assistive technology can associate the hint with the group. Keep the Checkbox `label` so each
+control retains its own accessible name; `FormFieldGroup.Label` only provides the group name.
 
 The `error` prop may be applied directly to the Checkbox with a value of `"caution"` or `"error"` if
-Form Field is not being used.
+FormFieldGroup is not being used.
 
 #### Caution
 
@@ -105,6 +111,127 @@ Form Field is not being used.
 Checkbox 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 a checked,
+unchecked, or mixed state that assistive technology can expose. Use **Checkbox** when the user can
+select zero, one, or many independent options. For mutually exclusive choices, use
+[**Radio**](https://workday.github.io/canvas-kit/?path=/docs/preview-inputs-radio--docs) instead.
+When checkboxes answer the same question, or need hint, error, caution, or required association, see
+[FormField's accessibility documentation](/components/inputs/form-field/#accessibility).
+
+### Minimum Accessible Structure
+
+The following matches the [Basic Example](#basic-example): a **`Checkbox`** with a non-empty
+**`label`**. **`FormFieldGroup`** is not required for a single standalone checkbox with no hint,
+error, caution, or required state.
+
+```tsx
+import {Checkbox} from '@workday/canvas-kit-react/checkbox';
+
+<Checkbox label="I agree to the terms" />;
+```
+
+### Built-in Behaviors
+
+Canvas Kit applies these automatically on **`Checkbox`**. When checkboxes that answer the same
+question are composed with **`FormFieldGroup`** subcomponents, that grouping wiring is also applied
+automatically. **Do not duplicate them** in consuming code.
+
+**ARIA and DOM** (_applied by Checkbox_):
+
+- **`Checkbox`**: Renders a native `<input type="checkbox">`. Canvas Kit assigns an `id` with
+  `useUniqueId` unless you pass **`id`**.
+- **`label`**: Renders a visible `<label htmlFor={id}>` so the control has an accessible name and
+  clicking the text activates the input.
+- **`indeterminate`**: Sets `aria-checked="mixed"` and the input's native `indeterminate` property.
+  Otherwise `aria-checked` follows the **`checked`** prop.
+- **`disabled`**: Maps to the native `disabled` attribute.
+- **`ref`**: Forwards to the underlying `<input type="checkbox">`.
+
+**Keyboard** (_native checkbox behavior_):
+
+**`Checkbox`** uses native `<input type="checkbox">` keyboard behavior (tab order, Space to toggle,
+and label activation). 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 Checkbox **`label`** and checked, unchecked, or mixed
+  state
+- Disabled checkboxes 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 Checkbox. Rows marked _(conditional)_ apply only when
+the situation matches—otherwise omit.
+
+**If no design spec is provided:** use a visible, non-empty Checkbox **`label`**. Omit
+**`FormFieldGroup`** unless the spec includes a group name, more than one independent option for the
+same question, or hint, error, caution, or required state. Omit **`FormFieldGroup.Hint`**,
+**`isRequired`**, **`error`**, **`indeterminate`**, **`disabled`**, a custom **`id`**, and a
+**`ref`** unless the spec requires them.
+
+**Choose a composition:**
+
+- Standalone **`Checkbox`** with **`label`** — one control with no hint, error, caution, or required
+  state
+- **`FormFieldGroup`** — one question with two or more independent options, or any checkbox that
+  needs a group name, hint, error, caution, or required state
+- Nested `<ul>` / `<li>` — parent checkbox with nested children and **`indeterminate`**. Do not use
+  **`FormFieldGroup`** for that hierarchy. Checkboxes that answer different questions stay in
+  separate compositions.
+
+**Programmatic focus** _(conditional — omit by default)_:
+
+Attach a `ref` only when the product must move focus to the checkbox after an action (for example,
+**Submit** in [Ref Forwarding](#ref-forwarding)). Do not attach a `ref` or call `focus()` unless the
+design or developer asks for it.
+
+| Requirement                             | How to satisfy                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Accessible name                         | Non-empty **`label`** on every **`Checkbox`**. **`FormFieldGroup.Label`** names the group only (`div` with an `id`); it is not a `<label>` and does not replace **`label`**.                                                                                                                                                                                                                                                         |
+| Group wiring _(conditional)_            | When the spec is one question with two or more independent options, or includes a group name, hint, error, caution, or required state: **`FormFieldGroup`** + **`FormFieldGroup.Label`** + **`FormFieldGroup.Input as={Checkbox}`**. Put hint, error, caution, and required on the group — see [FormField accessibility](/components/inputs/form-field/#accessibility). See [Required](#required) and [Error States](#error-states). |
+| Visual error or caution _(conditional)_ | When **`FormFieldGroup`** has `error="error"` or `error="caution"`, also set **`error`** on **`Checkbox`** to the same state so the visual ring appears. See [Caution](#caution) and [Error](#error).                                                                                                                                                                                                                                |
+| Indeterminate parent _(conditional)_    | When a parent checkbox's value depends on nested children and some (but not all) children are checked: set **`indeterminate`** on the parent **`Checkbox`**; keep a non-empty **`label`** on the parent and on each child; nest the children in a `<ul>` inside the parent's `<li>`. See [Indeterminate](#indeterminate).                                                                                                            |
+| Disabled _(conditional)_                | `disabled` on **`Checkbox`** when the spec marks the option unavailable. See [Disabled](#disabled).                                                                                                                                                                                                                                                                                                                                  |
+| Programmatic focus _(conditional)_      | `ref` on **`Checkbox`** (or **`FormFieldGroup.Input`**) and move focus when the product requires it — omit by default (see **Programmatic focus** above and [Ref Forwarding](#ref-forwarding)).                                                                                                                                                                                                                                      |
+
+**Summary for code generation:**
+
+- **REQUIRED:** non-empty **`label`**
+- **CONDITIONAL:** **`FormFieldGroup`** for one question with two or more independent options, or
+  for hint, error, caution, or required; **`error`** on **`Checkbox`** when the group is in caution
+  or error; nested list + **`indeterminate`** for a parent/child tree; disabled; programmatic focus
+  via `ref`. See [FormField accessibility](/components/inputs/form-field/#accessibility) for group
+  hint, error, caution, and required.
+
+### Anti-Patterns
+
+Do **not** generate code that does the following (see **Accessibility Requirements** above for what
+to supply instead):
+
+- Manually set `aria-checked` or `htmlFor` on **`Checkbox`**, or pass an **`id`** when the spec does
+  not require a known id — Canvas Kit wires `aria-checked` and `htmlFor`, and assigns an `id` with
+  `useUniqueId` unless you pass one (see **If no design spec is provided**)
+- Ignore **Choose a composition** — do not wrap a standalone checkbox with no group name, hint,
+  error, caution, or required state in **`FormFieldGroup`**; do not put different questions in one
+  group; do not use **`FormFieldGroup`** for a parent/child indeterminate tree
+- Wrap **`Checkbox`** with **`FormField.Input`** — **`Checkbox`** already renders its own `<label>`.
+  When a group is required, use **`FormFieldGroup.Input as={Checkbox}`** (see **Group wiring**)
+- Omit **`label`** because **`FormFieldGroup.Label`** is present — the group label does not name the
+  individual control
+- Set `aria-checked="mixed"` without **`indeterminate`**
+- Use **`aria-disabled`** instead of **`disabled`** — **`Checkbox`** maps unavailability to the
+  native **`disabled`** prop
+- Use **`disabled`** when the spec says users must still focus the control to hear why it is
+  unavailable. Only in that case keep the checkbox enabled and put the explanation in
+  **`FormFieldGroup.Hint`** or on an adjacent focusable control
+- Use **Checkbox** for mutually exclusive choices — use
+  [**Radio**](https://workday.github.io/canvas-kit/?path=/docs/preview-inputs-radio--docs) instead
+
 ## Component API
 
 <SymbolDoc name="Checkbox" fileName="/react/" />

package/dist/mdx/react/checkbox/examples/Basic.tsx

@@ -1,7 +1,6 @@
 import React from 'react';
 
 import {Checkbox} from '@workday/canvas-kit-react/checkbox';
-import {FormField} from '@workday/canvas-kit-react/form-field';
 
 export default () => {
   const [checked, setChecked] = React.useState(false);
@@ -10,17 +9,5 @@ export default () => {
     setChecked(event.target.checked);
   };
 
-  return (
-    <FormField>
-      <FormField.Label>Confirm</FormField.Label>
-      <FormField.Field>
-        <FormField.Input
-          as={Checkbox}
-          checked={checked}
-          label="I agree to the terms"
-          onChange={handleChange}
-        />
-      </FormField.Field>
-    </FormField>
-  );
+  return <Checkbox checked={checked} label="I agree to the terms" onChange={handleChange} />;
 };

package/dist/mdx/react/checkbox/examples/Caution.tsx

@@ -1,7 +1,7 @@
 import React from 'react';
 
 import {Checkbox} from '@workday/canvas-kit-react/checkbox';
-import {FormField} from '@workday/canvas-kit-react/form-field';
+import {FormFieldGroup} from '@workday/canvas-kit-react/form-field';
 
 export default () => {
   const [checked, setChecked] = React.useState(false);
@@ -11,17 +11,18 @@ export default () => {
   };
 
   return (
-    <FormField error="caution">
-      <FormField.Label>Confirm</FormField.Label>
-      <FormField.Field>
-        <FormField.Input
+    <FormFieldGroup error="caution">
+      <FormFieldGroup.Label>Confirm</FormFieldGroup.Label>
+      <FormFieldGroup.Field>
+        <FormFieldGroup.Input
           as={Checkbox}
           checked={checked}
+          error={Checkbox.ErrorType.Caution}
           label="I agree to the terms"
           onChange={handleChange}
         />
-        <FormField.Hint>You must agree to the terms before proceeding</FormField.Hint>
-      </FormField.Field>
-    </FormField>
+        <FormFieldGroup.Hint>You must agree to the terms before proceeding</FormFieldGroup.Hint>
+      </FormFieldGroup.Field>
+    </FormFieldGroup>
   );
 };