@workday/canvas-kit-docs 17.0.0-alpha.0605-next.0 → 17.0.0-alpha.0616-next.0

package/dist/es6/lib/specs.js

@@ -1491,6 +1491,26 @@ module.exports = {specifications: [
               {
                 "type": "it",
                 "name": "should not have any axe errors"
+              },
+              {
+                "type": "describe",
+                "name": "when the form is submitted with an empty required select",
+                "children": [
+                  {
+                    "type": "it",
+                    "name": "should focus the first invalid field"
+                  }
+                ]
+              },
+              {
+                "type": "describe",
+                "name": "when a later required field is empty",
+                "children": [
+                  {
+                    "type": "it",
+                    "name": "should focus the first invalid field"
+                  }
+                ]
               }
             ]
           }

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.1.1",
-    "@workday/canvas-kit-preview-react": "16.1.1",
-    "@workday/canvas-kit-react": "16.1.1",
-    "@workday/canvas-kit-react-fonts": "^16.1.1",
-    "@workday/canvas-kit-styling": "16.1.1",
+    "@workday/canvas-kit-labs-react": "16.1.3",
+    "@workday/canvas-kit-preview-react": "16.1.3",
+    "@workday/canvas-kit-react": "16.1.3",
+    "@workday/canvas-kit-react-fonts": "^16.1.3",
+    "@workday/canvas-kit-styling": "16.1.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.1.1",
-    "@workday/canvas-kit-preview-react": "16.1.1",
-    "@workday/canvas-kit-react": "16.1.1",
-    "@workday/canvas-kit-react-fonts": "^16.1.1",
-    "@workday/canvas-kit-styling": "16.1.1",
+    "@workday/canvas-kit-labs-react": "16.1.3",
+    "@workday/canvas-kit-preview-react": "16.1.3",
+    "@workday/canvas-kit-react": "16.1.3",
+    "@workday/canvas-kit-react-fonts": "^16.1.3",
+    "@workday/canvas-kit-styling": "16.1.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/accessibility/AccessibilityOverview.mdx

@@ -86,7 +86,9 @@ Further reading:
 ```
 
 Check out our [Aria Live Region Examples](?path=/docs/guides-accessibility-aria-live-regions--docs)
-for more detailed information about this topic.
+for more detailed information about this topic. For labels, error text, `aria-invalid`, and focus
+after a failed submit, see
+[Form Validation](?path=/docs/guides-accessibility-form-validation--docs).
 
 Sometimes, things change on a webpage without the whole page reloading. Think of a live sports score
 that updates every few seconds or a search result that appears as you type. For users of screen

package/dist/mdx/preview-react/_examples/mdx/FormLibraryExample.mdx

@@ -1,7 +1,39 @@
 import {ExampleCodeBlock} from '@workday/canvas-kit-docs';
+
 import TextInputWithReactHookForm from './examples/TextInputWithReactHookForm';
 
 
-## Uncontrolled Text Inputs Using React Hook Form
+# Form Validation with React Hook Form and Yup
+
+Accessible form validation is not a library feature. It is a composition of **labels**, **error text
+tied to the field**, **`aria-invalid`**, and **keyboard focus**. Canvas Kit
+[`FormField`](?path=/docs/components-inputs-form-field--docs#accessibility) owns the first three
+when you use its subcomponents. The application owns when validation runs and where focus goes after
+submit.
+
+1. **Identify every field, including required ones** Set `autoComplete` with a
+   [standard token](https://html.spec.whatwg.org/multipage/form-control-infrastructure.html#autofill)
+   when the field collects a known personal data type (`username`, `current-password`, `email`,
+   `name`). That supports
+   [WCAG 1.3.5 Identify Input Purpose](https://www.w3.org/WAI/WCAG22/Understanding/identify-input-purpose.html).
+2. **Move focus to the first invalid field after submit** Failed submit must not leave focus on the
+   submit button. Keyboard and screen-reader users need to land on the first field that is still
+   invalid, in **DOM order**.
+3. **Choose when to validate** Prefer validating **on submit**, then on **blur / touched** for
+   fields the user has already visited (`mode: 'onTouched'` in this example). Validating on every
+   keystroke while the field is still incomplete is noisy and can announce `aria-invalid` too early.
+   (Relevant criteria:
+   [3.3.1 Error Identification](https://www.w3.org/WAI/WCAG22/Understanding/error-identification.html),
+   [3.3.3 Error Suggestion](https://www.w3.org/WAI/WCAG22/Understanding/error-suggestion.html).)
+4. **Do not use a live region for every field error** Field errors belong on the field
+   (`aria-invalid` + `aria-describedby`). They are announced when the field **receives focus**. A
+   page-level live region that restates every invalid field on submit is easy to overdo. Live
+   announcements cannot be replayed, can interrupt, and have uneven support. If you add a form-level
+   summary, keep it short, do not duplicate every message, and read
+   [ARIA Live Regions](?path=/docs/guides-accessibility-aria-live-regions--docs) first.
+
+This example wires `FormField`, `TextInput`, `Select`, and `InputGroup` to
+[React Hook Form](https://www.react-hook-form.com/) with [Yup](https://github.com/jquense/yup). The
+same practices apply if you use Formik, a server round-trip, or hand-rolled state.
 
 <ExampleCodeBlock code={TextInputWithReactHookForm} />

package/dist/mdx/preview-react/_examples/mdx/examples/TextInputWithReactHookForm.tsx

@@ -1,13 +1,18 @@
 import React from 'react';
-import {FieldErrorsImpl, useForm} from 'react-hook-form';
-import {SchemaOf, object, string} from 'yup';
+import {FieldErrors, Resolver, useForm} from 'react-hook-form';
+import {SchemaOf, ValidationError, object, string} from 'yup';
 
 import {PrimaryButton, TertiaryButton} from '@workday/canvas-kit-react/button';
-import {useUniqueId} from '@workday/canvas-kit-react/common';
-import {FormField} from '@workday/canvas-kit-react/form-field';
+import {ErrorType, useUniqueId} from '@workday/canvas-kit-react/common';
+import {
+  FormField,
+  useFormFieldInput,
+  useFormFieldModel,
+} from '@workday/canvas-kit-react/form-field';
 import {Flex} from '@workday/canvas-kit-react/layout';
 import {Select} from '@workday/canvas-kit-react/select';
-import {TextInput} from '@workday/canvas-kit-react/text-input';
+import {InputGroup, TextInput} from '@workday/canvas-kit-react/text-input';
+import {Tooltip} from '@workday/canvas-kit-react/tooltip';
 import {createStyles, px2rem} from '@workday/canvas-kit-styling';
 import {visibleIcon, visibleStrikethroughIcon} from '@workday/canvas-system-icons-web';
 import {system} from '@workday/canvas-tokens-web';
@@ -18,31 +23,30 @@ const styles = createStyles({
   alignItems: 'flex-start',
 });
 
-type YupValidationResolver = <T extends {}>(
-  validationSchema: SchemaOf<T>
-) => (data: T) => Promise<{values: T; errors: {}} | {values: {}; errors: FieldErrorsImpl<T>}>;
-
-const useYupValidationResolver: YupValidationResolver = validationSchema => {
-  return React.useCallback(
+const useYupValidationResolver = <T extends {}>(validationSchema: SchemaOf<T>): Resolver<T> => {
+  return React.useCallback<Resolver<T>>(
     async data => {
       try {
-        const values = await validationSchema.validate(data, {abortEarly: false});
-        return {values, errors: {}};
-      } catch (errors) {
-        return {
-          values: {},
-          //@ts-ignore
-          errors: errors.inner.reduce(
-            (allErrors, currentError) => ({
-              ...allErrors,
-              [currentError.path]: {
-                type: currentError.type ?? 'validation',
-                message: currentError.message,
-              },
-            }),
-            {}
-          ),
-        };
+        await validationSchema.validate(data, {abortEarly: false});
+        return {values: data, errors: {}};
+      } catch (error) {
+        // Yup throws a `ValidationError` for failed validation. Anything else is a real error.
+        if (!ValidationError.isError(error)) {
+          throw error;
+        }
+
+        const errors = error.inner.reduce<Record<string, {type: string; message: string}>>(
+          (allErrors, currentError) => ({
+            ...allErrors,
+            [currentError.path ?? '']: {
+              type: currentError.type ?? 'validation',
+              message: currentError.message,
+            },
+          }),
+          {}
+        );
+
+        return {values: {}, errors: errors as FieldErrors<T>};
       }
     },
     [validationSchema]
@@ -74,6 +78,9 @@ const options = [
 ];
 
 export default () => {
+  const formRef = React.useRef<HTMLFormElement>(null);
+  const [showPassword, setShowPassword] = React.useState(false);
+  const [submitAttempt, setSubmitAttempt] = React.useState(0);
   const {
     handleSubmit,
     register,
@@ -84,19 +91,36 @@ export default () => {
       password: 'foobarbaz',
       role: '',
     },
-    resolver: useYupValidationResolver(validationSchema),
+    resolver: useYupValidationResolver<LoginSchema>(validationSchema),
     mode: 'onTouched',
+    shouldFocusError: true,
   });
 
-  const onSubmit = handleSubmit(values => {
-    setShowPassword(false);
-    // Send data to server
-    setTimeout(() => {
-      alert(JSON.stringify(values, null, 2));
-    }, 0);
-  });
+  const onSubmit = handleSubmit(
+    values => {
+      setShowPassword(false);
+      // Send data to server
+      setTimeout(() => {
+        alert(JSON.stringify(values, null, 2));
+      }, 0);
+    },
+    () => {
+      // Count failed submits so we can move focus after FormField paints `aria-invalid`.
+      setSubmitAttempt(count => count + 1);
+    }
+  );
+
+  React.useEffect(() => {
+    if (submitAttempt === 0) {
+      return;
+    }
+
+    const firstInvalidField = formRef.current?.querySelector<HTMLElement>(
+      '[aria-invalid="true"]:not([aria-hidden="true"]):not([tabindex="-1"])'
+    );
+    firstInvalidField?.focus();
+  }, [submitAttempt, errors]);
 
-  const [showPassword, setShowPassword] = React.useState(false);
   const passwordId = useUniqueId();
   const passwordRef = React.useRef<HTMLInputElement | null>(null);
   const {ref: passwordCallbackRef, ...passwordRegistration} = register('password');
@@ -104,8 +128,15 @@ export default () => {
     passwordCallbackRef(ref);
     passwordRef.current = ref;
   };
+  // `InputGroup` renders the input, so hoist the model to keep the label, hint, and error wiring.
+  const passwordModel = useFormFieldModel({
+    id: passwordId,
+    isRequired: true,
+    error: errors.password ? 'error' : undefined,
+  });
+  const passwordInputProps = useFormFieldInput(passwordModel);
   return (
-    <form onSubmit={onSubmit} action="." noValidate={true}>
+    <form ref={formRef} onSubmit={onSubmit} action="." noValidate={true}>
       <Flex cs={styles}>
         <FormField
           orientation="vertical"
@@ -143,35 +174,33 @@ export default () => {
           </FormField.Field>
           <FormField.Hint>{errors.email?.message}</FormField.Hint>
         </FormField>
-        <FormField
-          orientation="vertical"
-          id={passwordId}
-          isRequired={true}
-          error={!!errors.password ? 'error' : undefined}
-        >
+        <FormField model={passwordModel} orientation="vertical">
           <FormField.Label>Password</FormField.Label>
-          <Flex cs={{gap: system.gap.md}}>
-            <FormField.Field>
-              <FormField.Input
-                as={TextInput}
-                {...passwordRegistration}
-                type={showPassword ? 'text' : 'password'}
-                autoComplete="current-password"
-                spellCheck={false}
-                ref={combinePasswordRef}
-              />
-            </FormField.Field>
-            <TertiaryButton
-              type="button"
-              icon={showPassword ? visibleStrikethroughIcon : visibleIcon}
-              aria-label={showPassword ? 'Hide Password' : 'Show Password'}
-              aria-controls={`input-${passwordId}`}
-              onClick={() => {
-                setShowPassword(state => !state);
-                passwordRef.current?.focus();
-              }}
+          <FormField.Field as={InputGroup}>
+            <InputGroup.Input
+              {...passwordInputProps}
+              {...passwordRegistration}
+              error={errors.password ? ErrorType.Error : undefined}
+              type={showPassword ? 'text' : 'password'}
+              autoComplete="current-password"
+              spellCheck={false}
+              ref={combinePasswordRef}
             />
-          </Flex>
+            <InputGroup.InnerEnd>
+              <Tooltip title={showPassword ? 'Hide Password' : 'Show Password'}>
+                <TertiaryButton
+                  type="button"
+                  size="small"
+                  icon={showPassword ? visibleStrikethroughIcon : visibleIcon}
+                  aria-controls={`input-${passwordId}`}
+                  onClick={() => {
+                    setShowPassword(state => !state);
+                    passwordRef.current?.focus();
+                  }}
+                />
+              </Tooltip>
+            </InputGroup.InnerEnd>
+          </FormField.Field>
           <FormField.Hint>{errors.password?.message || passwordHint}</FormField.Hint>
         </FormField>
 

package/dist/mdx/react/_examples/mdx/Density.mdx

@@ -4,8 +4,24 @@ import Density from './examples/Density';
 
 # Canvas Kit Density Examples
 
-Although we currently don't support a density system, it's common practice to provide varying
-options to users, especially in the context of forms. Below is an example of how you can style our
-from elements to achieve the desired density.
+Canvas Kit does not ship a density system. Forms often still need compact, default, and
+comfortable spacing. This example shows how to style Canvas Kit form elements with
+`createStencil` to get three densities.
+
+Density in this demo changes:
+
+- **Input height and padding** (`system.size.sm` / `md` / `md + 4px`)
+- **Label and input type** (`subtext.medium` / `subtext.large` / `body.small`)
+- **Space between fields** (`system.gap.md` / `lg` / `xl`)
+- **Space between a label and its input** (tighter when labels are vertical)
+
+| Density | Input height | Field spacing | Type |
+| ------- | ------------ | ------------- | ---- |
+| High    | 32px         | 16px          | `subtext.medium` |
+| Medium  | 40px         | 24px          | `subtext.large` |
+| Low     | 48px         | 32px          | `body.small` |
+
+`Switch` does not expose a size API, so its dimensions stay the same across densities. Only its
+label type and surrounding field spacing change.
 
 <ExampleCodeBlock code={Density} />

package/dist/mdx/react/_examples/mdx/examples/Density.tsx

@@ -1,30 +1,38 @@
 import React from 'react';
 
-import {FormField, FormFieldGroup} from '@workday/canvas-kit-react/form-field';
+import {Switch} from '@workday/canvas-kit-preview-react/switch';
+import {useUniqueId} from '@workday/canvas-kit-react/common';
+import {FormField} from '@workday/canvas-kit-react/form-field';
 import {SegmentedControl} from '@workday/canvas-kit-react/segmented-control';
 import {Select} from '@workday/canvas-kit-react/select';
-import {Switch} from '@workday/canvas-kit-react/switch';
-import {Heading, Text} from '@workday/canvas-kit-react/text';
+import {Heading, Subtext, Text} from '@workday/canvas-kit-react/text';
 import {TextInput} from '@workday/canvas-kit-react/text-input';
 import {calc, createStencil, createStyles, px2rem} from '@workday/canvas-kit-styling';
 import {base, system} from '@workday/canvas-tokens-web';
 
+type DensityLevel = 'high' | 'medium' | 'low';
+type LabelOrientation = 'vertical' | 'horizontalStart' | 'horizontalEnd';
+type ContainerAlignment = 'left' | 'center';
+type DensityTypeLevel = 'subtext.medium' | 'subtext.large' | 'body.small';
+
+const densitySummary: Record<
+  DensityLevel,
+  {inputHeight: string; stackGap: string; typeLevel: DensityTypeLevel}
+> = {
+  high: {inputHeight: '32px', stackGap: '16px', typeLevel: 'subtext.medium'},
+  medium: {inputHeight: '40px', stackGap: '24px', typeLevel: 'subtext.large'},
+  low: {inputHeight: '48px', stackGap: '32px', typeLevel: 'body.small'},
+};
+
 const formStyles = createStyles({
   margin: `${px2rem(12)} ${'0'}`,
   maxWidth: px2rem(600),
   minWidth: '0',
 });
 
-const formFieldGroupListStyles = createStyles({
-  display: 'inline-flex',
-  flexDirection: 'row',
-  flexWrap: 'wrap',
-});
-
 const sideBySideInputs = createStencil({
   base: {
     display: 'inline-flex',
-    gap: system.gap.sm,
     justifyContent: 'space-between',
   },
   modifiers: {
@@ -39,52 +47,21 @@ const sideBySideInputs = createStencil({
       },
       vertical: {
         display: 'inline-flex',
+        flexDirection: 'row',
       },
     },
     density: {
-      high: {},
-      medium: {},
-      low: {},
-    },
-  },
-  compound: [
-    {
-      modifiers: {labelOrientation: 'horizontalStart', density: 'high'},
-      styles: {
-        gap: system.gap.md,
-      },
-    },
-    {
-      modifiers: {labelOrientation: 'horizontalStart', density: 'medium'},
-      styles: {
-        gap: system.gap.lg,
-      },
-    },
-    {
-      modifiers: {labelOrientation: 'horizontalStart', density: 'low'},
-      styles: {
-        gap: system.gap.xl,
-      },
-    },
-    {
-      modifiers: {labelOrientation: 'horizontalEnd', density: 'high'},
-      styles: {
+      high: {
         gap: system.gap.md,
       },
-    },
-    {
-      modifiers: {labelOrientation: 'horizontalEnd', density: 'medium'},
-      styles: {
+      medium: {
         gap: system.gap.lg,
       },
-    },
-    {
-      modifiers: {labelOrientation: 'horizontalEnd', density: 'low'},
-      styles: {
+      low: {
         gap: system.gap.xl,
       },
     },
-  ],
+  },
 });
 
 const zipCodeInput = createStyles({
@@ -96,7 +73,10 @@ const zipCodeContainerStyles = createStyles({
 });
 
 const formFieldStencil = createStencil({
-  base: {},
+  base: {
+    // FormField's built-in margin would double-space with the stack gap below.
+    margin: 0,
+  },
   modifiers: {
     density: {
       high: {
@@ -155,32 +135,6 @@ const formFieldStencil = createStencil({
   ],
 });
 
-const selectStencil = createStencil({
-  base: {},
-  modifiers: {
-    density: {
-      high: {
-        height: system.size.sm,
-        padding: `${system.padding.xxs} ${system.padding.xs}`,
-        '& + div': {
-          height: system.size.sm,
-        },
-      },
-      medium: {
-        height: system.size.md,
-        padding: `${system.padding.xs}`,
-      },
-      low: {
-        height: calc.add(system.size.md, base.size100),
-        padding: `${system.padding.sm} ${system.padding.xs}`,
-        '& + div': {
-          height: calc.add(system.size.md, base.size100),
-        },
-      },
-    },
-  },
-});
-
 const inputStencil = createStencil({
   base: {
     minWidth: px2rem(200),
@@ -190,29 +144,25 @@ const inputStencil = createStencil({
       high: {
         height: system.size.sm,
         padding: `${system.padding.xxs} ${system.padding.xs}`,
+        fontSize: system.legacy.fontSize.subtext.md,
+        lineHeight: system.legacy.lineHeight.subtext.md,
       },
       medium: {
         height: system.size.md,
         padding: `${system.padding.xs}`,
+        fontSize: system.legacy.fontSize.subtext.lg,
+        lineHeight: system.legacy.lineHeight.subtext.lg,
       },
-
       low: {
         height: calc.add(system.size.md, base.size100),
         padding: `${system.padding.sm} ${system.padding.xs}`,
+        fontSize: system.legacy.fontSize.body.sm,
+        lineHeight: system.legacy.lineHeight.body.sm,
       },
     },
   },
 });
 
-const creditCardInputStencil = createStencil({
-  extends: inputStencil,
-  base: {
-    width: calc.add(system.size.md, system.size.md),
-    minWidth: calc.add(system.size.md, system.size.md),
-    textAlign: 'center',
-  },
-});
-
 const flexContainerStencil = createStencil({
   base: {
     display: 'flex',
@@ -263,37 +213,44 @@ const optionItemStyles = createStyles({
   maxWidth: 'fit-content',
 });
 
-// high = 32px height on inputs, space between inputs is 16px
-// medium 40px height on inputs, space between inputs is 24px
-// low = 48px height on inputs, space between inputs is 32px
-
 export default () => {
-  const [density, setDensity] = React.useState<'high' | 'medium' | 'low'>('medium');
-  const [containerAlignment, setContainerAlignment] = React.useState<'left' | 'center'>('left');
-  const [labelOrientation, setLabelOrientation] = React.useState<
-    'vertical' | 'horizontalStart' | 'horizontalEnd'
-  >('vertical');
+  const [density, setDensity] = React.useState<DensityLevel>('medium');
+  const [containerAlignment, setContainerAlignment] = React.useState<ContainerAlignment>('left');
+  const [labelOrientation, setLabelOrientation] = React.useState<LabelOrientation>('vertical');
+  const [fastShipping, setFastShipping] = React.useState(false);
+  const densityLabelId = useUniqueId();
+  const containerAlignmentLabelId = useUniqueId();
+  const labelOrientationLabelId = useUniqueId();
+
+  const handleDensity = (data: {id: string}) => {
+    setDensity(data.id as DensityLevel);
+  };
 
-  const handleDensity = data => {
-    setDensity(data.id);
+  const handleContainerAlignment = (data: {id: string}) => {
+    setContainerAlignment(data.id as ContainerAlignment);
   };
 
-  const handleContainerAlignment = data => {
-    setContainerAlignment(data.id);
+  const handleLabelOrientation = (data: {id: string}) => {
+    setLabelOrientation(data.id as LabelOrientation);
   };
 
-  const handleLabelOrientation = data => {
-    setLabelOrientation(data.id);
+  const handleFastShipping = (event: React.ChangeEvent<HTMLInputElement>) => {
+    setFastShipping(event.target.checked);
   };
 
+  const labelTypeLevel = densitySummary[density].typeLevel;
+  const fieldCs = formFieldStencil({density, labelOrientation});
+  const inputCs = inputStencil({density});
+
   return (
-    <div>
-      <Heading size="small">Choose Your Density and Alignment</Heading>
+    <>
       <div className={optionStyles}>
         <div className={optionItemStyles}>
-          <Text>Density</Text>
-          <SegmentedControl onSelect={data => handleDensity(data)} size="small">
-            <SegmentedControl.List aria-label="choose a density">
+          <Text as="h3" id={densityLabelId}>
+            Density
+          </Text>
+          <SegmentedControl initialValue={density} onSelect={handleDensity} size="small">
+            <SegmentedControl.List aria-label="Density" aria-labelledby={densityLabelId}>
               <SegmentedControl.Item data-id="high">High</SegmentedControl.Item>
               <SegmentedControl.Item data-id="medium">Medium</SegmentedControl.Item>
               <SegmentedControl.Item data-id="low">Low</SegmentedControl.Item>
@@ -301,9 +258,18 @@ export default () => {
           </SegmentedControl>
         </div>
         <div className={optionItemStyles}>
-          <Text>Label Orientation</Text>
-          <SegmentedControl onSelect={data => handleLabelOrientation(data)} size="small">
-            <SegmentedControl.List aria-label="choose a label orientation">
+          <Text as="h3" id={labelOrientationLabelId}>
+            Label Orientation
+          </Text>
+          <SegmentedControl
+            initialValue={labelOrientation}
+            onSelect={handleLabelOrientation}
+            size="small"
+          >
+            <SegmentedControl.List
+              aria-label="Label Orientation"
+              aria-labelledby={labelOrientationLabelId}
+            >
               <SegmentedControl.Item data-id="vertical">Vertical</SegmentedControl.Item>
               <SegmentedControl.Item data-id="horizontalStart">
                 Horizontal Start
@@ -313,131 +279,92 @@ export default () => {
           </SegmentedControl>
         </div>
         <div className={optionItemStyles}>
-          <Text>Container Alignment</Text>
-          <SegmentedControl onSelect={data => handleContainerAlignment(data)} size="small">
-            <SegmentedControl.List aria-label="choose a density">
+          <Text as="h3" id={containerAlignmentLabelId}>
+            Container Alignment
+          </Text>
+          <SegmentedControl
+            initialValue={containerAlignment}
+            onSelect={handleContainerAlignment}
+            size="small"
+          >
+            <SegmentedControl.List
+              aria-label="Container Alignment"
+              aria-labelledby={containerAlignmentLabelId}
+            >
               <SegmentedControl.Item data-id="left">Left</SegmentedControl.Item>
               <SegmentedControl.Item data-id="center">Center</SegmentedControl.Item>
             </SegmentedControl.List>
           </SegmentedControl>
         </div>
+        <Subtext size="large">
+          Input height: {densitySummary[density].inputHeight}. Field spacing:{' '}
+          {densitySummary[density].stackGap}. Type: {densitySummary[density].typeLevel}.
+        </Subtext>
       </div>
 
       <div {...containerAlignmentStencil({alignment: containerAlignment})}>
-        <form action="#" className={formStyles}>
+        <form className={formStyles} autoComplete="off">
+          <Heading size="small">Shipping Address</Heading>
           <div {...flexContainerStencil({density})}>
-            <FormField
-              orientation={labelOrientation}
-              grow
-              cs={formFieldStencil({density, labelOrientation})}
-              id="foo"
-            >
-              <FormField.Label>Choose Country</FormField.Label>
-              <Select items={['Dominican Republic', 'Spain', 'United States']}>
-                <FormField.Input
-                  cs={selectStencil({density})}
-                  placeholder="Choose a country"
-                  as={Select.Input}
-                />
-                <Select.Popper>
-                  <Select.Card>
-                    <Select.List>{item => <Select.Item>{item}</Select.Item>}</Select.List>
-                  </Select.Card>
-                </Select.Popper>
-              </Select>
-            </FormField>
-            <FormField
-              grow
-              orientation={labelOrientation}
-              cs={formFieldStencil({density, labelOrientation})}
-            >
-              <FormField.Label>Full Name</FormField.Label>
-              <FormField.Input as={TextInput} cs={inputStencil({density})} />
+            <FormField grow orientation={labelOrientation} cs={fieldCs}>
+              <FormField.Label typeLevel={labelTypeLevel}>Full Name</FormField.Label>
+              <FormField.Input as={TextInput} autoComplete="name" cs={inputCs} />
             </FormField>
-            <FormField
-              grow
-              orientation={labelOrientation}
-              cs={formFieldStencil({density, labelOrientation})}
-            >
-              <FormField.Label>Phone Number</FormField.Label>
-              <FormField.Input as={TextInput} cs={inputStencil({density})} />
-            </FormField>
-            <FormField
-              grow
-              orientation={labelOrientation}
-              cs={formFieldStencil({density, labelOrientation})}
-            >
-              <FormField.Label>Street Address</FormField.Label>
-              <FormField.Input as={TextInput} cs={inputStencil({density})} />
-            </FormField>
-            <FormField
-              grow
-              orientation={labelOrientation}
-              cs={formFieldStencil({density, labelOrientation})}
-            >
-              <FormField.Label>City</FormField.Label>
-              <FormField.Input as={TextInput} cs={inputStencil({density})} />
+            <div {...sideBySideInputs({labelOrientation, density})}>
+              <FormField grow orientation={labelOrientation} cs={fieldCs}>
+                <FormField.Label typeLevel={labelTypeLevel}>Phone Number</FormField.Label>
+                <FormField.Input as={TextInput} autoComplete="tel" cs={inputCs} />
+              </FormField>
+              <FormField grow orientation={labelOrientation} cs={fieldCs}>
+                <FormField.Label typeLevel={labelTypeLevel}>Email</FormField.Label>
+                <FormField.Input as={TextInput} autoComplete="email" cs={inputCs} />
+              </FormField>
+            </div>
+            <FormField grow orientation={labelOrientation} cs={fieldCs}>
+              <FormField.Label typeLevel={labelTypeLevel}>Street Address</FormField.Label>
+              <FormField.Input as={TextInput} autoComplete="street-address" cs={inputCs} />
             </FormField>
-            <div {...sideBySideInputs({labelOrientation: labelOrientation, density})}>
-              <FormField
-                grow
-                orientation={labelOrientation}
-                cs={formFieldStencil({density, labelOrientation})}
-              >
-                <FormField.Label>State</FormField.Label>
-                <FormField.Input as={TextInput} cs={inputStencil({density})} />
+
+            <div {...sideBySideInputs({labelOrientation, density})}>
+              <FormField grow orientation={labelOrientation} cs={fieldCs}>
+                <FormField.Label typeLevel={labelTypeLevel}>City</FormField.Label>
+                <FormField.Input as={TextInput} autoComplete="address-level2" cs={inputCs} />
               </FormField>
-              <FormField
-                grow
-                orientation={labelOrientation}
-                cs={[formFieldStencil({density, labelOrientation}), zipCodeContainerStyles]}
-              >
-                <FormField.Label>Zip Code</FormField.Label>
-                <FormField.Input cs={[inputStencil({density}), zipCodeInput]} as={TextInput} />
+              <FormField grow orientation={labelOrientation} cs={fieldCs}>
+                <FormField.Label typeLevel={labelTypeLevel}>State</FormField.Label>
+                <FormField.Input as={TextInput} autoComplete="address-level1" cs={inputCs} />
+              </FormField>
+              <FormField grow orientation={labelOrientation} cs={[fieldCs, zipCodeContainerStyles]}>
+                <FormField.Label typeLevel={labelTypeLevel}>Zip Code</FormField.Label>
+                <FormField.Input
+                  cs={[inputCs, zipCodeInput]}
+                  as={TextInput}
+                  autoComplete="postal-code"
+                />
               </FormField>
             </div>
-            <FormField
-              orientation={labelOrientation}
-              cs={formFieldStencil({density, labelOrientation})}
-            >
-              <FormField.Label>Enable Fast Shipping</FormField.Label>
+            <FormField grow orientation={labelOrientation} cs={fieldCs}>
+              <FormField.Label typeLevel={labelTypeLevel}>Country</FormField.Label>
               <FormField.Field>
-                <FormField.Input as={Switch} />
+                <Select items={['Dominican Republic', 'Spain', 'United States']}>
+                  <FormField.Input cs={inputCs} placeholder="Choose a country" as={Select.Input} />
+                  <Select.Popper>
+                    <Select.Card>
+                      <Select.List>{item => <Select.Item>{item}</Select.Item>}</Select.List>
+                    </Select.Card>
+                  </Select.Popper>
+                </Select>
+              </FormField.Field>
+            </FormField>
+            <FormField orientation={labelOrientation} cs={fieldCs}>
+              <FormField.Label typeLevel={labelTypeLevel}>Enable Fast Shipping</FormField.Label>
+              <FormField.Field>
+                <FormField.Input as={Switch} checked={fastShipping} onChange={handleFastShipping} />
               </FormField.Field>
             </FormField>
-            <FormFieldGroup
-              cs={formFieldStencil({density, labelOrientation})}
-              orientation={labelOrientation}
-            >
-              <FormFieldGroup.Label>Credit Card</FormFieldGroup.Label>
-              <FormFieldGroup.Field>
-                <FormFieldGroup.List cs={formFieldGroupListStyles}>
-                  <FormFieldGroup.Input
-                    as={TextInput}
-                    placeholder="XXXX"
-                    cs={creditCardInputStencil({density})}
-                  />
-                  <FormFieldGroup.Input
-                    as={TextInput}
-                    placeholder="XXXX"
-                    cs={creditCardInputStencil({density})}
-                  />
-                  <FormFieldGroup.Input
-                    as={TextInput}
-                    placeholder="XXXX"
-                    cs={creditCardInputStencil({density})}
-                  />
-                  <FormFieldGroup.Input
-                    cs={creditCardInputStencil({density})}
-                    placeholder="XXXX"
-                    as={TextInput}
-                  />
-                </FormFieldGroup.List>
-              </FormFieldGroup.Field>
-            </FormFieldGroup>
           </div>
         </form>
       </div>
-    </div>
+    </>
   );
 };

package/dist/mdx/react/expandable/Expandable.mdx

@@ -1,12 +1,12 @@
 import {ExampleCodeBlock, SymbolDoc} from '@workday/canvas-kit-docs';
 
-import StartIcon from './examples/StartIcon';
-import EndIcon from './examples/EndIcon';
 import Avatar from './examples/Avatar';
 import Depth from './examples/Depth';
-import RTL from './examples/RTL';
-import LongTitle from './examples/LongTitle';
+import EndIcon from './examples/EndIcon';
 import HoistedModel from './examples/HoistedModel';
+import LongTitle from './examples/LongTitle';
+import RTL from './examples/RTL';
+import StartIcon from './examples/StartIcon';
 
 
 # Canvas Kit Expandable
@@ -23,8 +23,8 @@ yarn add @workday/canvas-kit-react
 
 ### Start Icon
 
-For a basic expandable container with a chevron icon before the title, place`Expandable.Icon` before
-`Expandable.Title` as children of `Expandable.Target` and pass the `iconPosition` prop to
+For a basic expandable container with a chevron icon before the title, place `Expandable.Icon`
+before `Expandable.Title` as children of `Expandable.Target` and pass the `iconPosition` prop to
 `Expandable.Icon` with a value of `start`. `Expandable.Icon` will use a right chevron icon when
 collapsed and a down chevron icon when expanded.
 
@@ -46,18 +46,12 @@ To include an avatar image, `Expandable.Avatar` should be placed between `Expand
 to `Expandable.Icon` depending on whether the `Expandable.Icon` is placed before or after
 `Expandable.Title`.
 
-**Note:** If using an avatar image, do not also include an Icon component in addition to the Expandable.Icon.
-This component is meant to have either an avatar image or an icon in addition to the Expandable.Icon, or neither
-an avatar image nor an extra icon.
-
+**Note:** If using an avatar image, do not also include an Icon component in addition to the
+Expandable.Icon. This component is meant to have either an avatar image or an icon in addition to
+the Expandable.Icon, or neither an avatar image nor an extra icon.
 
 <ExampleCodeBlock code={Avatar} />
 
-> **Accessibility Note:** In this situation, the Avatar is decorative and should not be announced to
-> screen readers. The `<Expandable.Avatar>` component has `isDecorative` set to `true` by default to
-> hide it from screen readers, as avatars in expandable headers are typically decorative when paired
-> with adjacent text.
-
 ### Right to Left (RTL)
 
 Expandable container has bidirectional support and should function as expected with RTL languages as
@@ -78,8 +72,6 @@ Long titles will wrap to the next line and increase the height of the container.
 
 <ExampleCodeBlock code={LongTitle} />
 
-You can also have direct access to the model if
-
 ### Hoisted Model
 
 If you need direct access to the model, you can hoist it with the `useExpandableModel` hook. In the
@@ -87,47 +79,161 @@ example below, we're hoisting the models to expand and collapse all three contai
 
 <ExampleCodeBlock code={HoistedModel} />
 
-> **Accessibility Note:** When using multiple Expandable Containers on a page, use the `as` prop to
-> render the `<Expandable.Content>` sub-component as an HTML `<section>` element. Then, use
-> `aria-labelledby` to reference the unique `id` of the `<Expandable.Title>` element. This practice
-> can be useful to screen reader users when multiple Expandable Containers are opened at one time
-> for uniquely describing the boundaries of the expandable content.
+For the accordion composition (named regions on each panel), see
+[Accessibility Requirements](#accessibility-requirements).
 
 ## Accessibility
 
-Our Expandable component renders a semantic HTML `<button>` element to the DOM, with an optional
-parent heading element as defined by the `headingLevel` prop. The `aria-expanded` property is
-included on the button to indicate the state of the content to screen readers.
-
-[Accordion Pattern | APG | WAI | W3C](https://www.w3.org/WAI/ARIA/apg/patterns/accordion/)
-
-- Use the `headingLevel` prop to assign an appropriate heading level based on the context of the
-  page content.
-- When using Expandable Container for navigation elements, then we don't recommend using the
-  `headingLevel` prop. This will render only expandable buttons to the DOM, reserving headings for
-  organizing content in the main body of the page.
-- The `as` prop may also be used on `<Expandable.Content>` to render an HTML `<ul>` element for
-  displaying a list of items. For example, check out
-  [Side Panel with Navigation](https://workday.github.io/canvas-kit/?path=/docs/guides-accessibility-examples-side-panel-navigation--docs).
-
-### Navigation
-
-- **Tab key**: Moves focus to the next expandable button or focusable element
-- **Shift + Tab**: Moves focus to the previous focusable element
-- **Enter or Space**: Toggles the expanded/collapsed state
-
-### Screen Reader Experience
-
-- The expandable button will be announced with its title text followed by the button role
-- The current state will be announced as either "collapsed" or "expanded" (For example: "Usage
-  Guidance, button, collapsed" or "Usage Guidance, button, expanded")
-- **State Changes:** When activating the button to expand content, screen readers will announce the
-  new "expanded" state and vice versa when collapsing content.
-- **Content Regions:** Screen reader users can use landmark navigation to jump between sections and
-  each section will be announced with its associated title (For example: "Usage Guidance, landmark
-  region")
-- **Heading Structure:** Using heading levels with expandable buttons allows screen reader users to
-  navigate by headings, making the document structure and hierarchy easier to understand.
+Ensure users of assistive technology can find the control, understand whether related content is
+shown or hidden, and reveal or hide that content from the keyboard. **`Expandable`** is an inline
+[disclosure (show/hide)](https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/) widget: a button
+toggles content that stays in the document flow.
+
+Use **`Expandable`** for show/hide sections in the page. Compose multiple instances to build an
+[accordion](https://www.w3.org/WAI/ARIA/apg/patterns/accordion/) — see
+[Hoisted Model](#hoisted-model). For a navigation accordion, see
+[Side Panel with Navigation](https://workday.github.io/canvas-kit/?path=/docs/guides-accessibility-examples-side-panel-navigation--docs).
+
+### Minimum Accessible Structure
+
+The following matches the [Start Icon](#start-icon) example layout: **`Expandable.Icon`** before
+**`Expandable.Title`** inside **`Expandable.Target`**, then **`Expandable.Content`**.
+**`headingLevel`** is omitted here on purpose — add it only after asking which level matches the
+page outline (see **Accessibility Requirements**). The Basic Example code uses `headingLevel="h4"`
+as a sample, not a default.
+
+```tsx
+import {Expandable} from '@workday/canvas-kit-react/expandable';
+
+<Expandable>
+  <Expandable.Target>
+    <Expandable.Icon iconPosition="start" />
+    <Expandable.Title>Title</Expandable.Title>
+  </Expandable.Target>
+  <Expandable.Content>Content</Expandable.Content>
+</Expandable>;
+```
+
+### Built-in Behaviors
+
+Canvas Kit applies these automatically via `useExpandableModel` (a `DisclosureModel`) and Expandable
+subcomponents. **Do not duplicate them** in consuming code.
+
+**ARIA and DOM** (_applied by hooks/subcomponents_):
+
+- **`Expandable.Target`**: native `<button>` with `aria-expanded` (`true` when
+  `visibility !== 'hidden'`) and `aria-controls` set to the disclosure `id`. `onClick` toggles
+  `events.show()` / `events.hide()`.
+- **`headingLevel`**: when set (`'h1'`–`'h6'`), wraps the button in **`Heading`** rendered as that
+  heading element. When omitted, the button is not wrapped in a heading.
+- **`Expandable.Content`**: `id` set to the same disclosure `id`. Collapsed content stays in the DOM
+  with `display: none` (not unmounted). Default element is a `<div>`.
+- **`Expandable.Title`**: styled `<div>` for the visible name. It does **not** receive an `id` from
+  the model.
+- **`Expandable.Icon`**: decorative chevron that rotates from `visibility`. Expanded/collapsed state
+  for assistive technology comes from `aria-expanded`, not from the icon.
+- **`Expandable.Avatar`**: `isDecorative={true}` by default so the image is hidden from assistive
+  technology when paired with **`Expandable.Title`**.
+- Disclosure `id`: generated with `useUniqueId` unless you pass `id` to **`useExpandableModel`**.
+  Default `initialVisibility` is `'hidden'`.
+
+**Keyboard** (_native button behavior_):
+
+**`Expandable.Target`** uses native `<button>` keyboard behavior (tab order, <kbd>Enter</kbd> /
+
+<kbd>Space</kbd> to toggle). Collapsed content is not in the tab order (`display: none`). Focus
+stays on the button; Canvas Kit does not move focus into **`Expandable.Content`**.
+
+**Screen reader expectations** (_when built-in behaviors are used as intended_):
+
+- On focus, assistive technology announces the title text, the button role, and expanded/collapsed
+  state from `aria-expanded` (for example, "Title, button, collapsed")
+- Activating the button announces the updated expanded/collapsed state from `aria-expanded`
+- While collapsed, content is removed from the accessibility tree (`display: none`)
+- While expanded, content follows the button in reading order
+- When **`headingLevel`** is set, heading navigation includes the heading that wraps the button
+- When **`Expandable.Content as="section"`** is used with `aria-labelledby` pointing at
+  **`Expandable.Title`**, region/landmark navigation can name each open section
+
+### Accessibility Requirements
+
+Required in application code for an accessible Expandable. Hoist **`useExpandableModel`** when you
+need programmatic show/hide (for example, expand all) or a stable disclosure `id`. Rows marked
+_(conditional)_ apply only when the situation matches—otherwise omit.
+
+**If no design spec is provided:** use the **single disclosure** composition
+([Basic Example](#basic-example)). If the spec is several related headers, use the **accordion**
+composition. Omit **`Expandable.Avatar`**, **`initialVisibility`**, and a custom **`id`**.
+
+**Choose a composition** (pick one; **`Expandable.Content as="section"`** and **`as="ul"`** are
+mutually exclusive):
+
+- **Single disclosure** — one show/hide section. [Basic Example](#basic-example) /
+  [Minimum Accessible Structure](#minimum-accessible-structure). Default Content is a `<div>`.
+- **Accordion** — several related headers. [Hoisted Model](#hoisted-model): unique `id` on
+  **`Expandable.Title`**, **`Expandable.Content as="section"`** with `aria-labelledby`.
+- **Navigation list** — disclosed links.
+  [Side Panel with Navigation](https://workday.github.io/canvas-kit/?path=/docs/guides-accessibility-examples-side-panel-navigation--docs):
+  **`as="ul"`**, omit **`headingLevel`**.
+
+**Heading level:** Ask which heading (`h1`–`h6`) belongs in the document outline before setting
+**`headingLevel`**. Omit **`headingLevel`** for navigation. Do not generate **`headingLevel`** by
+default — the Basic Example code uses `h4` only as a sample.
+
+| Requirement                                     | How to satisfy                                                                                                                                                                                     |
+| ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Accessible name                                 | Non-empty **`Expandable.Title`** inside **`Expandable.Target`**.                                                                                                                                   |
+| Keyboard-operable toggle                        | **`Expandable.Target`** (native `<button>`).                                                                                                                                                       |
+| Visual expanded/collapsed indicator             | **`Expandable.Icon`** with `iconPosition` matching layout (`start` or `end`).                                                                                                                      |
+| Heading in the document outline _(conditional)_ | **`headingLevel`** on **`Expandable.Target`** when the control titles body content (single disclosure or accordion). Omit **`headingLevel`** for the navigation-list composition. Ask which level. |
+| Accordion named regions _(conditional)_         | Accordion composition: **`Expandable.Content as="section"`** plus `aria-labelledby` referencing a unique `id` on **`Expandable.Title`**.                                                           |
+| List markup _(conditional)_                     | Navigation-list composition: **`Expandable.Content as="ul"`** (and list items as children).                                                                                                        |
+| Decorative avatar _(conditional)_               | **`Expandable.Avatar`** when the design includes an avatar. Keep **`isDecorative`** at the default `true`.                                                                                         |
+| Start expanded _(conditional)_                  | `initialVisibility: 'visible'` on **`useExpandableModel`** (or the equivalent model config).                                                                                                       |
+| Programmatic expand/collapse _(conditional)_    | Hoist **`useExpandableModel`** and call `model.events.show()` / `model.events.hide()`.                                                                                                             |
+
+**Summary for code generation:**
+
+- **REQUIRED:** **`Expandable.Target`**, non-empty **`Expandable.Title`**, **`Expandable.Content`**,
+  **`Expandable.Icon`**
+- **CONDITIONAL:** composition (single disclosure vs accordion vs navigation list),
+  **`headingLevel`** (ask which; omit for navigation), accordion **`as="section"`** +
+  `aria-labelledby`, navigation **`as="ul"`**, **`Expandable.Avatar`**, hoisted
+  **`useExpandableModel`**, **`initialVisibility`**
+
+### Anti-Patterns
+
+Do **not** generate code that does the following (see **Accessibility Requirements** above for what
+to supply instead):
+
+- Manually set `aria-expanded`, `aria-controls`, or the disclosure `id` on **`Expandable.Target`**
+  or **`Expandable.Content`** — `useExpandableTarget` and `useExpandableContent` wire these
+- Rely on **`Expandable.Icon`** or **`Expandable.Avatar`** for the accessible name — use
+  **`Expandable.Title`**
+- Override **`Expandable.Target`** with a custom **`as`** — **`Expandable.Target`** already renders
+  a native `<button>`
+- Set `id` on **`Expandable`** to identify the outer wrapper — `id` is model config **and** is
+  forwarded to the container element, while **`Expandable.Content`** also uses `state.id`, which can
+  produce duplicate IDs. For a stable content `id`, hoist **`useExpandableModel({id: '…'})`**.
+  **`Expandable.Title`** still needs its own `id` when you set `aria-labelledby` on
+  **`Expandable.Content`**
+- Wrap **`Expandable.Target`** in your own heading — use **`headingLevel`** instead
+- Default **`headingLevel`** to `h4` (or any level) without asking, or set **`headingLevel`** on
+  navigation disclosures
+- Generate several Basic Example disclosures with default `div` Content when the spec is an
+  accordion — use the **accordion** composition (see **Choose a composition**)
+- Set **`as="section"`** and **`as="ul"`** on the same **`Expandable.Content`** — pick one
+  composition
+- Change **`Expandable.Title`** to encode state (for example "Collapsed" / "Expanded" or "Show" /
+  "Hide") — `aria-expanded` already exposes state
+- Unmount **`Expandable.Content`** when collapsed, or add `aria-hidden` on it — the library uses
+  `display: none`
+- Set **`isDecorative={false}`** on **`Expandable.Avatar`** by default, or pair an avatar with an
+  extra non-chevron icon
+- Use **`open`**, **`expanded`**, or **`onToggle`** props on **`Expandable`** — visibility is
+  `initialVisibility` plus **`useExpandableModel`** events
+- Assume default **`Expandable.Content`** is a landmark region — that is only true with
+  **`as="section"`**
 
 ## Component API
 

package/dist/mdx/styling/mdx/examples/CSProp.tsx

@@ -10,7 +10,7 @@ const myStencil = createStencil({
   },
 });
 
-export const CSProp = () => {
+export default () => {
   return (
     <Card cs={myStencil()}>
       <Card.Heading

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@workday/canvas-kit-docs",
-  "version": "17.0.0-alpha.0605-next.0",
+  "version": "17.0.0-alpha.0616-next.0",
   "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": "^17.0.0-alpha.0605-next.0",
-    "@workday/canvas-kit-preview-react": "^17.0.0-alpha.0605-next.0",
-    "@workday/canvas-kit-react": "^17.0.0-alpha.0605-next.0",
-    "@workday/canvas-kit-styling": "^17.0.0-alpha.0605-next.0",
+    "@workday/canvas-kit-labs-react": "^17.0.0-alpha.0616-next.0",
+    "@workday/canvas-kit-preview-react": "^17.0.0-alpha.0616-next.0",
+    "@workday/canvas-kit-react": "^17.0.0-alpha.0616-next.0",
+    "@workday/canvas-kit-styling": "^17.0.0-alpha.0616-next.0",
     "@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": "58ce933e857e255360611f2330a230b167cead8d"
+  "gitHead": "593c0f1f5ee5047c7bea41027f76716a0f42caee"
 }

package/dist/mdx/react/_examples/mdx/FormsWithFormik.mdx

@@ -1,9 +0,0 @@
-import {ExampleCodeBlock} from '@workday/canvas-kit-docs';
-import SelectWithFormik from './examples/SelectWithFormik';
-
-
-# Canvas Kit Examples
-
-## Select Using Formik
-
-<ExampleCodeBlock code={SelectWithFormik} />

package/dist/mdx/react/_examples/mdx/examples/SelectWithFormik.tsx

@@ -1,84 +0,0 @@
-import {useFormik} from 'formik';
-
-import {PrimaryButton} from '@workday/canvas-kit-react/button';
-import {FormField} from '@workday/canvas-kit-react/form-field';
-import {Flex} from '@workday/canvas-kit-react/layout';
-import {Select, useSelectModel} from '@workday/canvas-kit-react/select';
-import {px2rem} from '@workday/canvas-kit-styling';
-import {cloudArrowUpIcon, cloudIcon, commentIcon, userIcon} from '@workday/canvas-system-icons-web';
-import {system} from '@workday/canvas-tokens-web';
-
-export default [
-  {
-    label: 'Dessert Person by Claire Saffitz',
-    serverId: 1,
-    icon: commentIcon,
-  },
-  {
-    label: 'Elements of Pizza by Ken Forkish',
-    serverId: 2,
-    icon: cloudIcon,
-  },
-  {
-    label: 'Flour Water Salt Yeast by Ken Forkish',
-    serverId: 3,
-    icon: cloudArrowUpIcon,
-  },
-  {label: 'Mastering Pasta by Marc Verti', serverId: 4, icon: userIcon},
-];
-
-export default () => {
-  const formik = useFormik({
-    initialValues: {
-      selectedBook: '',
-    },
-    onSubmit: values => {
-      // Send data to server
-      setTimeout(() => {
-        alert(JSON.stringify(values, null, 2));
-      }, 0);
-    },
-  });
-
-  const selectModel = useSelectModel({
-    items: customOptionsMain,
-    getId: item => {
-      return item.serverId;
-    },
-    getTextValue: item => item.label,
-  });
-
-  return (
-    <form onSubmit={formik.handleSubmit} action=".">
-      <Flex cs={{gap: system.gap.sm, flexDirection: 'column', alignItems: 'flex-start'}}>
-        <FormField orientation="vertical" cs={{alignSelf: 'stretch', alignItems: 'normal'}}>
-          <Select model={selectModel}>
-            <FormField.Label>Choose a book</FormField.Label>
-            <FormField.Input
-              as={Select.Input}
-              name="selectedBook"
-              onChange={event => formik.setFieldValue('selectedBook', event.currentTarget.value)}
-              value={formik.values.selectedBook}
-              grow
-            />
-            <Select.Popper>
-              <Select.Card>
-                <Select.List cs={{maxHeight: px2rem(200)}}>
-                  {item => {
-                    return (
-                      <Select.Item data-id={item.serverId} data-text={item.label}>
-                        <Select.Item.Icon icon={item.icon} />
-                        {item.label}
-                      </Select.Item>
-                    );
-                  }}
-                </Select.List>
-              </Select.Card>
-            </Select.Popper>
-          </Select>
-        </FormField>
-        <PrimaryButton type="submit">Submit</PrimaryButton>
-      </Flex>
-    </form>
-  );
-};