@workday/canvas-kit-mcp 15.0.0-alpha.0056-next.0 → 15.0.0-alpha.0060-next.0

package/dist/lib/upgrade-guides/11.0-UPGRADE-GUIDE.md

@@ -0,0 +1,960 @@
+---
+source_file: docs/mdx/11.0-UPGRADE-GUIDE.mdx
+live_url: https://workday.github.io/canvas-kit/docs/mdx/11.0-UPGRADE-GUIDE
+---
+
+<Meta title="Guides/Upgrade Guides/v11.0" />
+
+# Canvas Kit 11.0 Upgrade Guide
+
+This guide contains an overview of the changes in Canvas Kit v11. Please
+[reach out](https://github.com/Workday/canvas-kit/issues/new?labels=bug&template=bug.md) if you have
+any questions.
+
+## Why You Should Upgrade
+
+Canvas Kit v11 is transitioning into a
+[new way of styling](https://github.com/Workday/canvas-kit/discussions/2265). Theming and building
+an in sync Canvas Kit CSS has been at the top of our minds. We've started using our new
+[Canvas Tokens Web](https://workday.github.io/canvas-tokens/?path=/docs/docs-getting-started--docs)
+package to take advantage of
+[CSS variables](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties) and
+provide semantic tokens that can translate to theming components.
+
+A note to the reader:
+
+- While we still support our old tokens from `@workday/canvas-kit-react/tokens` in v11, you must
+  install our new tokens from `@workday/canvas-tokens-web`. You can find more info in our
+  [docs](https://workday.github.io/canvas-tokens/?path=/docs/docs-getting-started--docs).
+- In this release, we've introduced a
+  [new styling API](https://workday.github.io/canvas-kit/?path=/docs/styling-basics--create-stencil).
+  This shouldn't effect the way you currently style your components. Because we're moving away from
+  Emotion, support for style props will eventually be removed, however, this API provide backwards
+  compatability. If you want to slowly move off of Emotion as well, you can start styling components
+  via the `cs` prop or our new styling utilities.
+
+## Table of contents
+
+- [Canvas Tokens](#canvas-tokens)
+- [Codemod](#codemod)
+- [Deprecations](#deprecations)
+  - [Form Field (Main)](#form-field-main)
+  - [Label Text](#label-text)
+  - [Text Area (Preview)](#text-area-preview)
+  - [Text Input (Preview)](#text-input-preview)
+- [Removals](#removals)
+  - [Status Indicator (Preview) Utilities](#status-indicator-preview-utilities)
+- [Component Style Updates](#component-style-updates)
+- [Component Updates](#component-updates)
+  - [Styling API and CSS Tokens](#styling-api-and-css-tokens)
+  - [CountBadge](#count-badge)
+  - [Form Field Preview](#form-field-preview)
+  - [Icons](#icons)
+  - [Status Indicator (Preview)](#status-indicator-preview)
+  - [Table](#table)
+  - [Text](#text)
+- [Style Utility Updates](#style-utility-updates)
+  - [createStencil](#createstencil)
+- [Troubleshooting](#troubleshooting)
+- [Glossary](#glossary)
+  - [Main](#main)
+  - [Preview](#preview)
+  - [Labs](#labs)
+
+## Canvas Tokens
+
+In v11, all the components listed in this guide have started using our new
+[Canvas Tokens Web](https://workday.github.io/canvas-tokens/?path=/docs/docs-getting-started--docs).
+In v10, we provided token fallbacks so that a component would not be missing a token/value if the
+tokens were not defined. In v11 you must add `@workday/canvas-tokens-web` to ensure our components
+are properly styled and the variables are defined. For more information on installing and using,
+please reference our tokens
+[docs](https://workday.github.io/canvas-tokens/?path=/docs/docs-getting-started--docs).
+
+## Codemod
+
+We've provided a [codemod](https://github.com/Workday/canvas-kit/tree/master/modules/codemod) to
+automatically update your code to work with most of the breaking changes in v11. **Breaking changes
+handled by the codemod are marked with 🤖 in the Upgrade Guide.**
+
+A codemod is a script that makes programmatic transformations on your codebase by traversing the
+[AST](https://www.hypermod.io/docs/guides/understanding-asts), identifying patterns, and making
+prescribed changes. This greatly decreases opportunities for error and reduces the number of manual
+updates, which allows you to focus on changes that need your attention. **We highly recommend you
+use the codemod for these reasons.**
+
+If you're new to running codemods or if it's been a minute since you've used one, there are a few
+things you'll want to keep in mind.
+
+- Our codemods are meant to be run sequentially. For example, if you're using v8 of Canvas Kit,
+  you'll need to run the v9 codemod before you run v11.
+- The codemod will update your code to be compatible with the specified version, but it will **not**
+  remove outdated dependencies or upgrade dependencies to the latest version. You'll need to upgrade
+  dependencies on your own.
+  - We recommend upgrading dependencies before running the codemod.
+  - Always review your `package.json` files to make sure your dependency versions look correct.
+- The codemod will not handle every breaking change in v11. You will likely need to make some manual
+  changes to be compatible. Use our Upgrade Guide as a checklist.
+- Codemods are not bulletproof.
+  - Conduct a thorough PR and QA review of all changes to ensure no regressions were introduced.
+  - As a safety precaution, we recommend committing the changes from the codemod as a single
+    isolated commit (separate from other changes) so you can roll back more easily if necessary.
+
+We're here to help! Automatic changes to your codebase can feel scary. You can always reach out to
+our team. We'd be very happy to walk you through the process to set you up for success.
+
+### Instructions
+
+The easiest way to run our codemod is to use `npx` in your terminal.
+
+```sh
+npx @workday/canvas-kit-codemod v11 [path]
+```
+
+Be sure to provide specific directories that need to be updated via the `[path]` argument. This
+decreases the amount of AST the codemod needs to traverse and reduces the chances of the script
+having an error. For example, if your source code lives in `src/`, use `src/` as your `[path]`. Or,
+if you have a monorepo with three packages using Canvas Kit, provide those specific packages as your
+`[path]`.
+
+Alternatively, if you're unable to run the codemod successfully using `npx`, you can install the
+codemod package as a dev dependency, run it with `yarn`, and then remove the package after you're
+finished.
+
+```sh
+yarn add @workday/canvas-kit-codemod --dev
+yarn canvas-kit-codemod v11 [path]
+yarn remove @workday/canvas-kit-codemod
+```
+
+> **Note**: The codemod only works on `.js`, `.jsx`, `.ts`, and `.tsx` files. You'll need to
+> manually edit other file types (`.json`, `.mdx`, `.md`, etc.). You may need to run your linter
+> after executing the codemod, as its resulting formatting (spacing, quotes, etc.) may not match
+> your project conventions.
+
+## Deprecations
+
+We add the [@deprecated](https://jsdoc.app/tags-deprecated.html) JSDoc tag to code we plan to remove
+in a future major release. This signals consumers to migrate to a more stable alternative before the
+deprecated code is removed.
+
+### Form Field Main
+
+**PR:** [#2472](https://github.com/Workday/canvas-kit/pull/2472)
+
+We've deprecated `FormField` in [Main](#main). Please use
+[`FormField`](https://workday.github.io/canvas-kit/?path=//docs/preview-inputs-form-field--basic) in
+[Preivew](#preview) instead.
+
+---
+
+### Label Text
+
+**PR:** [#2455](https://github.com/Workday/canvas-kit/pull/2455)
+
+We've deprecated `LabelText` in [Main](#main). Please use
+[`FormField.Label`](https://workday.github.io/canvas-kit/?path=//docs/preview-inputs-form-field--basic)
+in [Preview](#preview) in context of a `FormField` instead.
+
+```tsx
+//v10
+
+<form>
+  <LabelText>Pizza</LabelText>
+  <input type="text" />
+</form>;
+
+//v11
+
+<FormField>
+  <FormField.Label>First Name</FormField.Label>
+  <FormField.Input as={TextInput} value={value} onChange={e => console.log(e)} />
+</FormField>;
+```
+
+If you still want to use a `label` element outside of the context of a form, you can use our `Text`
+component instead.
+
+---
+
+### Text Area Preview
+
+**PR:** [#2472](https://github.com/Workday/canvas-kit/pull/2472)
+
+We've deprecated `TextArea` from [Preview](#preview). Please use
+[`FormField`](https://workday.github.io/canvas-kit/?path=//docs/preview-inputs-form-field--basic) in
+[Preview](#preview) with `TextArea` in [Main](#main) instead.
+
+---
+
+### Text Input Preview
+
+**PR:** [#2472](https://github.com/Workday/canvas-kit/pull/2472)
+
+We've deprecated `TextInput` from [Preview](#preview). Please use
+[`FormField`](https://workday.github.io/canvas-kit/?path=//docs/preview-inputs-form-field--basic) in
+[Preview](#preview) with `TextInput` in [Main](#main) instead.
+
+The following model hooks have also been deprecated:
+
+- `useTextInputModel`
+- `useTextInputField`
+
+## Removals
+
+### Status Indicator (Preview) Utilities
+
+**PR:** [#2472](https://github.com/Workday/canvas-kit/pull/2700)
+
+As part of the styling refactor, we've removed the following exports that were primarily used to
+style the component:
+
+- `useStatusIndicatorModel`
+- `useStatusIndicator`
+- `statusIndicatorColors`
+- `useStatusIndicatorIcon`.
+
+**There should be no developer impact.**
+
+---
+
+## Component Style Updates
+
+<StatusIndicator variant="red" emphasis="low">
+  <StatusIndicator.Label>Visual Breaking Change</StatusIndicator.Label>
+</StatusIndicator>
+
+**PR:** [#2485](https://github.com/Workday/canvas-kit/pull/2485)
+
+The following changes address visual discrepancies between our design spec files and code. These
+changes **should not** impact the layout or behavior of a component.
+
+Components affected:
+
+- `Checkbox`
+- `DeleteButton`
+- `Radio`
+- `SecondaryButton`
+- `StatusIndicator`
+- `Switch`
+- `Table`
+- `TertiaryButton`
+- `TextArea`
+- `TextInput`
+
+<Table>
+  <Table.Head>
+    <Table.Row>
+      <Table.Header scope="col">Component</Table.Header>
+      <Table.Header scope="col">Variant</Table.Header>
+      <Table.Header scope="col">psuedo Class</Table.Header>
+      <Table.Header scope="col">Property</Table.Header>
+      <Table.Header scope="col">v10 Value</Table.Header>
+      <Table.Header scope="col">v11 Value</Table.Header>
+    </Table.Row>
+  </Table.Head>
+  <Table.Body>
+    <Table.Row>
+      <Table.Cell>Checkbox</Table.Cell>
+      <Table.Cell />
+      <Table.Cell>disabled</Table.Cell>
+      <Table.Cell>borderColor</Table.Cell>
+      <Table.Cell>soap600</Table.Cell>
+      <Table.Cell	>
+        licorice100
+      </Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>Checkbox</Table.Cell>
+      <Table.Cell>Inverse</Table.Cell>
+      <Table.Cell>disabled</Table.Cell>
+      <Table.Cell>borderColor</Table.Cell>
+      <Table.Cell>soap600</Table.Cell>
+      <Table.Cell>
+        licorice100
+      </Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>DeleteButton</Table.Cell>
+      <Table.Cell />
+      <Table.Cell>disabled</Table.Cell>
+      <Table.Cell>backgroundColor</Table.Cell>
+      <Table.Cell>error.light</Table.Cell>
+      <Table.Cell>error.base</Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>DeleteButton</Table.Cell>
+      <Table.Cell />
+      <Table.Cell>disabled</Table.Cell>
+      <Table.Cell>opacity</Table.Cell>
+      <Table.Cell>1</Table.Cell>
+      <Table.Cell>0.4</Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>Radio</Table.Cell>
+      <Table.Cell />
+      <Table.Cell>disabled</Table.Cell>
+      <Table.Cell>borderColor</Table.Cell>
+      <Table.Cell>soap600</Table.Cell>
+      <Table.Cell>
+        licorice100
+      </Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>SecondaryButton</Table.Cell>
+      <Table.Cell>Inverse</Table.Cell>
+      <Table.Cell>focus</Table.Cell>
+      <Table.Cell>border</Table.Cell>
+      <Table.Cell>soap400</Table.Cell>
+      <Table.Cell>
+        transparent
+      </Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>SecondaryButton</Table.Cell>
+      <Table.Cell>Inverse</Table.Cell>
+      <Table.Cell>focus</Table.Cell>
+      <Table.Cell>boxShdaow (Inner Color)</Table.Cell>
+      <Table.Cell>blackPepper500</Table.Cell>
+      <Table.Cell>
+        blackPepper400
+      </Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>SecondaryButton</Table.Cell>
+      <Table.Cell>Inverse</Table.Cell>
+      <Table.Cell>focus</Table.Cell>
+      <Table.Cell>color</Table.Cell>
+      <Table.Cell>blackPepper500</Table.Cell>
+      <Table.Cell>
+        blackPepper400
+      </Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>SecondaryButton (Icon)</Table.Cell>
+      <Table.Cell>Inverse</Table.Cell>
+      <Table.Cell>focus</Table.Cell>
+      <Table.Cell>fill</Table.Cell>
+      <Table.Cell>blackPepper500</Table.Cell>
+      <Table.Cell>
+        blackPepper400
+      </Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>StatusIndicator (Preview)</Table.Cell>
+      <Table.Cell>transparent</Table.Cell>
+      <Table.Cell/>
+      <Table.Cell>backgroundColor</Table.Cell>
+      <Table.Cell>blackPepper600</Table.Cell>
+      <Table.Cell>
+        rgba(0,0,0,.84)
+      </Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>StatusIndicator (Preview)</Table.Cell>
+      <Table.Cell>transparent</Table.Cell>
+      <Table.Cell/>
+      <Table.Cell>opacity</Table.Cell>
+      <Table.Cell >0.85</Table.Cell>
+      <Table.Cell>
+        Removed
+      </Table.Cell>
+    </Table.Row>
+		<Table.Row>
+      <Table.Cell>Switch</Table.Cell>
+      <Table.Cell>Checked and Disabled</Table.Cell>
+      <Table.Cell/>
+      <Table.Cell>backgroundColor, opacity</Table.Cell>
+      <Table.Cell>blueberry200</Table.Cell>
+      <Table.Cell>
+        backgroundColor: brand.primary.base
+				opacity: system.opacity.disabled
+      </Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>Table (Header)</Table.Cell>
+      <Table.Cell />
+      <Table.Cell />
+      <Table.Cell>borderColor</Table.Cell>
+      <Table.Cell>soap400</Table.Cell>
+      <Table.Cell>soap500</Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>TertiaryButton</Table.Cell>
+      <Table.Cell />
+      <Table.Cell>hover</Table.Cell>
+      <Table.Cell>backgroundColor</Table.Cell>
+      <Table.Cell>soap200</Table.Cell>
+      <Table.Cell>soap300</Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>TertiaryButton</Table.Cell>
+      <Table.Cell />
+      <Table.Cell>active</Table.Cell>
+      <Table.Cell>backgroundColor</Table.Cell>
+      <Table.Cell>soap300</Table.Cell>
+      <Table.Cell>soap400</Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>TertiaryButton</Table.Cell>
+      <Table.Cell />
+      <Table.Cell>active</Table.Cell>
+      <Table.Cell>color</Table.Cell>
+      <Table.Cell>primary.dark</Table.Cell>
+      <Table.Cell>primary.darkest</Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>TertiaryButton</Table.Cell>
+      <Table.Cell />
+      <Table.Cell>disabled</Table.Cell>
+      <Table.Cell>borderColor</Table.Cell>
+      <Table.Cell backgroundColor="frenchVanilla100">frenchVanilla100</Table.Cell>
+      <Table.Cell cs={{backgroundColor: 'transparent'}}>transparent</Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>TertiaryButton (Icon Only)</Table.Cell>
+      <Table.Cell />
+      <Table.Cell>focus</Table.Cell>
+      <Table.Cell>fill</Table.Cell>
+      <Table.Cell>blackPepper500</Table.Cell>
+      <Table.Cell>blackPepper400</Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>TertiaryButton (Icon Only)</Table.Cell>
+      <Table.Cell />
+      <Table.Cell>hover</Table.Cell>
+      <Table.Cell>fill</Table.Cell>
+      <Table.Cell>blackPepper500</Table.Cell>
+      <Table.Cell>blackPepper400</Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>TextArea</Table.Cell>
+      <Table.Cell />
+      <Table.Cell>disabled</Table.Cell>
+      <Table.Cell>borderColor</Table.Cell>
+      <Table.Cell>soap600</Table.Cell>
+      <Table.Cell>licorice100</Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>TextInput</Table.Cell>
+      <Table.Cell />
+      <Table.Cell>disabled</Table.Cell>
+      <Table.Cell>borderColor</Table.Cell>
+      <Table.Cell>soap600</Table.Cell>
+      <Table.Cell>
+        licorice100
+      </Table.Cell>
+    </Table.Row>
+
+</Table.Body>
+
+</Table>
+
+> **Note:** If you use a visual regression tool, you'll need to update your tests to match the new
+> visual changes.
+
+## Component Updates
+
+### Styling API and CSS Tokens
+
+**PRs:** [#2666](https://github.com/Workday/canvas-kit/pull/2666),
+[#2471](https://github.com/Workday/canvas-kit/pull/2471),
+[#2542](https://github.com/Workday/canvas-kit/pull/2542),
+[#2570](https://github.com/Workday/canvas-kit/pull/2570),
+[#2442](https://github.com/Workday/canvas-kit/pull/2442),
+[#2472](https://github.com/Workday/canvas-kit/pull/2472),
+[#2685](https://github.com/Workday/canvas-kit/pull/2685),
+[#2615](https://github.com/Workday/canvas-kit/pull/2615),
+[#2699](https://github.com/Workday/canvas-kit/pull/2699),
+[#2546](https://github.com/Workday/canvas-kit/pull/2546),
+[#2570](https://github.com/Workday/canvas-kit/pull/2570),
+[#2620](https://github.com/Workday/canvas-kit/pull/2620),
+[#2583](https://github.com/Workday/canvas-kit/pull/2583),
+[#2567](https://github.com/Workday/canvas-kit/pull/2567),
+[#2455](https://github.com/Workday/canvas-kit/pull/2455),
+[#2709](https://github.com/Workday/canvas-kit/pull/2709)
+
+Several components have been refactored to use our new
+[Canvas Tokens](https://workday.github.io/canvas-tokens/?path=/docs/docs-getting-started--docs) and
+[styling API](https://workday.github.io/canvas-kit/?path=/docs/styling-basics--create-modifiers#createstyles-api).
+The React interface **has not changed**, but CSS variables are now used for dynamic properties.
+
+The following components are affected:
+
+- `AccentIcon`
+- `AppletIcon`
+- `Card`
+- `CheckBox`
+- `Combobox`
+- `CountBadge`
+- `FormField (Preview)`
+- `DeleteButton`
+- `Graphic`
+- `LoadingDots`
+- `PrimaryButton`
+- `SecondaryButton`
+- `Radio (Preview)`
+- `Select`
+- `StatusIndicator`
+- `Svg`
+- `Switch`
+- `SystemIconCircle`
+- `SystemIcon`
+- `Table`
+- `TertiaryButton`
+- `Text`
+
+> **Note:** These components also support our new `cs` prop for styling. Learn more about styling
+> with `cs` in our
+> [documentation](https://workday.github.io/canvas-kit/?path=/docs/styling-basics--cs-prop).
+
+### Count Badge
+
+<StatusIndicator variant="red" emphasis="low">
+  <StatusIndicator.Label>Breaking Change</StatusIndicator.Label>
+</StatusIndicator>
+
+**PR:** [#2709](https://github.com/Workday/canvas-kit/pull/2709)
+
+- `default` has been removed from the `variant` type and is now the default for styles.
+
+We also removed the `default` variant and consolidated those styles into the badge's base styles.
+This will not be a breaking change for most users. However, if you have a `CountBadge` with an
+explicit `default` variant, you'll see a TypeScript error. To resolve this, simply remove the
+variant prop.
+
+```tsx
+// Before (v10)
+<CountBadge variant="default" count={10} />
+
+// After (v11)
+<CountBadge count={10} />
+```
+
+### Form Field (Preview)
+
+<div style={{display: 'inline-flex', gap: '.5rem'}}>
+  <StatusIndicator variant="red" emphasis="low">
+    <StatusIndicator.Label>Breaking Change</StatusIndicator.Label>
+  </StatusIndicator>
+  <StatusIndicator variant="green" emphasis="low">
+    <StatusIndicator.Label>🤖 Codemod Available</StatusIndicator.Label>
+  </StatusIndicator>
+</div>
+
+**PR:** [#2472](https://github.com/Workday/canvas-kit/pull/2472)
+[#2746](https://github.com/Workday/canvas-kit/pull/274)
+
+`FormField` in [Preview](#preview) is a compound component and we intend to promote it in a future
+version to replace the `FormField` in [Main](#main). Because of this, we've refactored how errors
+are applied to `FormField` in [Preview](#preview) in order to match the API from the `FormField` in
+[Main](#main).
+
+- `hasError` prop has been renamed to `error`. **This is a breaking change**
+- `error` accepts `"error" | "alert" | ""` instead of a boolean value.
+- `orientation` prop defaults to `vertical` and is no longer required.
+- `FormField.Input` can be used by any of our inputs including `Select`, `TextInput`, `TextArea`,
+  `RadioGroup`, `Switch` and `Checkbox`.
+- `FormField` does **not** support the `useFieldSet` prop that the `FormField` in [Main](#main)
+  does. In order to achieve the same behavior, set the `as` prop on the `FormField` element to
+  `fieldset` and the `as` prop of `FormField.Label` to `legend`.
+- The required asterisk is now a pseudo element. While the asterisk was never read out loud by
+  screen readers, Testing Library required it in the `*ByLabelText` query. `*ByRole` uses the w3c
+  [accessible name calculation specification](https://www.w3.org/TR/accname-1.2/), but
+  `*ByLabelText` uses
+  [textContent](https://developer.mozilla.org/en-US/docs/Web/API/Node/textContent). Additional
+  information: https://github.com/testing-library/dom-testing-library/issues/929
+
+  v10:
+
+  ```ts
+  screen.getByLabelText('Email*'); // Email is a required field and asterisk is included in name
+  screen.getByRole('textbox', {name: 'Email'}); // correctly ignores the `*`
+  ```
+
+  v11:
+
+  ```ts
+  screen.getByLabelText('Email');
+  screen.getByRole('textbox', {name: 'Email'});
+  ```
+
+```tsx
+// v10 FormField in Preview
+
+<FormField orientation="vertical" hasError={true}>
+  <FormField.Label>Password</FormField.Label>
+  <FormField.Input as={TextInput} type="password" value={value} onChange={handleChange} />
+  <FormField.Hint>Must Contain a number and a capital letter</FormField.Hint>
+</FormField>;
+
+// v11
+
+<FormField error="error">
+  <FormField.Label>Password</FormField.Label>
+  <FormField.Container>
+    <FormField.Input as={TextInput} type="password" value={value} onChange={handleChange} />
+    <FormField.Hint>Must Contain a number and a capital letter</FormField.Hint>
+  </FormField.Container>
+</FormField>;
+```
+
+🤖 The codemod will handle the change of `hasError` to `error` for you automatically. You may need
+to check your logic to make sure it sets the appropaite value to the prop.
+
+> **Note:** If you use your own custom `input` you will need to handle the styling for error and
+> alert states.
+
+### Icons
+
+<div style={{display: 'inline-flex', gap: '.5rem'}}>
+  <StatusIndicator variant="red" emphasis="low">
+    <StatusIndicator.Label>Breaking Change</StatusIndicator.Label>
+  </StatusIndicator>
+  <StatusIndicator variant="green" emphasis="low">
+    <StatusIndicator.Label>🤖 Codemod Available</StatusIndicator.Label>
+  </StatusIndicator>
+</div>
+
+`styles` prop has been removed. If you still need to style an Icon component, please use the `cs`
+prop.
+
+> **Note:** Passing a token name to a style prop will not be supported in a future major version.
+> Please use our
+> [Canvas Tokens](https://workday.github.io/canvas-tokens/?path=/docs/docs-getting-started--docs)
+> instead.
+
+```tsx
+// This will no longer be supported in a future major version
+<SystemIcon color="blueberry400" />;
+
+// Use new tokens instead.
+
+<SystemIcon color={base.blueberry400} />;
+```
+
+🤖 The codemod will handle the change of renaming `styles` to `cs` for you automatically.
+
+#### AccentIcon
+
+- `AccentIconStyles` prop has been deprecated and will be merged with `AccentIconProps` in a future
+  version.
+- `accentIconStyles` has been deprecated and will be removed in a future version as a part of
+  implementation of stencils and new tokens. Consider using `accentIconStencil` to get styles or
+  class name.
+- `AccentIcon` supports `size` and `color` css variables, along with `size` and `color` props. Both
+  ways are supported:
+
+```tsx
+// set size or color by props
+<AccentIcon color={base.blueberry100} size={24} />;
+
+// set size or color by css vars
+
+const MyComponent = StyledRadioButton('div')({
+  [accentIconStencil.vars.color]: base.berrySmoothie100,
+  [accentIconStencil.vars.size]: '2rem',
+});
+
+<MyComponent>
+  <AccentIcon icon={myIcon} />
+</MyComponent>;
+```
+
+#### AppletIcon
+
+- `AppletIconStyles` prop has been deprecated and will be merged with `AppletIconProps` in a future
+  version.
+- `appletIconStyles` has been deprecated and will be removed in a future version as a part of
+  implementation of stencils and new tokens. Consider using `appletIconStencil` to get styles or
+  class name.
+- `AppletIcon` supports `size`, `color200`, `color300`, `color400` and `color500` css variables,
+  along with `size` and `color` props. Both ways are supported:
+
+```tsx
+// set size or color by props
+<AppletIcon color="blueberry" size={240} />;
+
+// set size or color by css vars
+
+const MyComponent = StyledRadioButton('div')({
+  [appletIconStencil.vars.size]: '2rem',
+  [appletIconStencil.vars.color200]: base.berrySmoothie200,
+  [appletIconStencil.vars.color300]: base.berrySmoothie300,
+  [appletIconStencil.vars.color400]: base.berrySmoothie400,
+  [appletIconStencil.vars.color500]: base.berrySmoothie500,
+});
+
+<MyComponent>
+  <AppletIcon icon={myIcon} />
+</MyComponent>;
+```
+
+#### Graphic
+
+- `GraphicStyles` prop has been deprecated and will be merged with `GraphicProps` in a future
+  version.
+- `graphicStyles` has been deprecated and will be removed in a future version as a part of
+  implementation of stencils and new tokens. Consider using `graphicStencil` to get styles or class
+  name.
+
+#### Icon
+
+This change only impacts internal Canvas Kit code. `Icon` component has been removed and is no
+longer used to build our icons. It has been replaced by our `Svg` component. Most of our icons now
+extend styles from `svgStencil`.
+
+#### SystemIcon
+
+- `SystemIconStyles` has been deprecated and will be removed in a future version as a part of
+  implementation of stencils and new tokens. Consider using `systemIconStencil` to get styles or
+  class name.
+
+- `accentHover` is deprecated and will be removed in a future version. Please use the following when
+  overriding styles:
+
+```tsx
+'&:hover': {
+  [systemIconStencil.vars.accent]: desiredAccentHoverColor
+}
+```
+
+- `backgroundHover` is deprecated and will be removed in a future version. Please use the following
+  when overriding styles:
+
+```tsx
+'&:hover': {
+  [systemIconStencil.vars.background]: desiredBackgroundHoverColor
+}
+```
+
+- `fillHover` is deprecated and will be removed in a future version. Please use the following when
+  overriding styles:
+
+```tsx
+'&:hover': {
+  [systemIconStencil.vars.fill]: desiredFillHoverColor
+}
+```
+
+- `fill` is deprecated and will be removed in a future version. Please use `color` and specify
+  `accent` color if you want `accent` to be different from `color`.
+
+```tsx
+'&:hover': {
+  [systemIconStencil.vars.fill]: desiredFillHoverColor
+}
+```
+
+- `systemIconStyles` has been deprecated and will be removed in a future version as a part of
+  implementation of stencils and new tokens. Consider using `systemIconStencil` to get styles or
+  class name.
+
+- `SystemIcon` supports `size`, `color`, `accentColor` and `background` css variables, along with
+  props. Both ways are supported:
+
+```tsx
+// set size or color by props
+<SystemIcon color={base.blueberry100} size={24} />;
+
+// set size or color by css vars
+
+const MyComponent = StyledRadioButton('div')({
+  [accentIconStencil.vars.size]: '2rem',
+  [systemIconStencil.vars.color]: base.berrySmoothie400,
+  [systemIconStencil.vars.background]: base.frenchVanilla100,
+  // on hover:
+  '&:hover': {
+    [systemIconStencil.vars.color]: base.berrySmoothie500,
+    [systemIconStencil.vars.background]: 'transparent',
+  },
+});
+
+<MyComponent>
+  <SystemIcon icon={myIcon} />
+</MyComponent>;
+```
+
+### Status Indicator (Preview)
+
+<StatusIndicator variant="red" emphasis="low">
+  <StatusIndicator.Label>Visual Breaking Change</StatusIndicator.Label>
+</StatusIndicator>
+
+**PR:** [#2620](https://github.com/Workday/canvas-kit/pull/2620)
+
+The `transparent` variant now uses `system.color.bg.translucent` which is a background color of
+black with an opacity of `0.84`.
+
+**There should be no developer impact and the visual changes are safe to accept**.
+
+### Switch
+
+<StatusIndicator variant="red" emphasis="low">
+  <StatusIndicator.Label>Visual Breaking Change</StatusIndicator.Label>
+</StatusIndicator>
+
+**PR:** [#2583](https://github.com/Workday/canvas-kit/pull/2583)
+
+Switch no longer uses `blueberry200` which was part of our theme object
+`theme.palette.primary.light` for the background color to indicate a Switch that is checked and
+disabled. Now, it uses `blueberry400` or `brand.base.primary` with an opacity of `0.4` for checked
+and disabled.
+
+**There should be no developer impact and the visual changes are safe to accept**.
+
+### Table
+
+**PR:** [#2600](https://github.com/Workday/canvas-kit/pull/2600)
+
+<StatusIndicator variant="red" emphasis="low">
+  <StatusIndicator.Label>Breaking Change</StatusIndicator.Label>
+</StatusIndicator>
+
+We've promoted `Table` from [Preview](#preview) to [Main](#main). It replaces the `Table` that was
+previously in [Main](#main) (for reference, see
+[`Table`](https://d2krrudi3mmzzw.cloudfront.net/v9/?path=/story/components-containers-table--basic)
+in [Main](#main) from v9).
+
+`Table` is a
+[compound component](https://workday.github.io/canvas-kit/?path=/docs/guides-compound-components--docs)
+which provides a flexible API and access to its internals via its subcomponents.
+
+> **Note**: `rowState` prop is no longer a part of the `Table` component.
+
+In v10, the `Table` component in [Main](#main) only exposed a `Table` and `TableRow` component to
+build tables.
+
+In v11, `Table` now exposes every subcomponent of a semantic HTML
+[Table](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/table). While more verbose, it
+provides more flexibility for customization.
+
+```tsx
+// v10
+
+<Table>
+  <thead>
+    <TableRow header={true}>
+      <th>Header Text</th>
+    </TableRow>
+  </thead>
+  <tbody>
+    <TableRow>
+      <td>Cell Text</td>
+    </TableRow>
+  </tbody>
+</Table>;
+
+// v11
+
+<Table>
+  <Table.Head>
+    <Table.Row>
+      <Table.Header>Header Text</Table.Header>
+    </Table.Row>
+  </Table.Head>
+  <Table.Body>
+    <Table.Row>
+      <Table.Cell>Cell Text</Table.Cell>
+    </Table.Row>
+  </Table.Body>
+</Table>;
+```
+
+Please refer to the
+[Table examples](https://workday.github.io/canvas-kit/?path=/story/components-containers-table--basic)
+for how to implement new tables.
+
+> **Note:** If you were using the [Preview](#preview) `Table` compound component, then you will need
+> to update your import from `@workday/canvas-kit-preview-react/table` to
+> `@workday/canvas-kit-react/table`. This change is **not** handled by the codemod.
+
+### Text
+
+**PR:** [#2455](https://github.com/Workday/canvas-kit/pull/2455)
+
+- `Text` no longer extends the `Box` component, however, it still supports Emotion `styled` and
+  style props.
+- Type level components: `Title`, `Heading`, `BodyText` and `Subtext` remain unchanged.
+
+## Style Utility Updates
+
+### `createStencil`
+
+**PR:** [#2697](https://github.com/Workday/canvas-kit/pull/2697)
+
+<StatusIndicator variant="red" emphasis="low">
+  <StatusIndicator.Label>Breaking Change</StatusIndicator.Label>
+</StatusIndicator>
+
+Stencils were updated to automatically add `box-sizing: border-box` to all stencils. If your stencil
+did not add this style already, it may change the way `width` works for the component. Our intent is
+to make all elements use border box layouts to make width calculations more predictable. This change
+may change the way your component works if you use the `width` style property.
+
+> **Note:** This is only a breaking change if you were using `createStencil` to apply margin and
+> padding without box-sizing. For reference, view box-sizing
+> [documentation](https://developer.mozilla.org/en-US/docs/Web/CSS/box-sizing).
+
+## Troubleshooting
+
+### My Styles Seem Broken?
+
+Our components are reliant on our new Canvas Tokens Web package. Be sure you install
+`@workday/canvas-tokens-web`. For more information, reference our
+[Getting Started docs](https://workday.github.io/canvas-tokens/?path=/docs/docs-getting-started--docs)
+for this package.
+
+### Did You Upgrade All Canvas Kit Related Packages?
+
+In order for all the packages to work in harmony, you must upgrade all Canvas Kit packages to the
+same version that you're using, including:
+
+- `@workday/canvas-kit-react`
+- `@workday/canvas-kit-preview-react`
+- `@workday/canvas-kit-labs-react`
+- `@workday/canvas-kit-styling`
+- `@workday/canvas-kit-react-fonts`
+- `@workday/canvas-kit-docs`
+
+## Glossary
+
+### Main
+
+Our Main package of Canvas Kit tokens, components, and utilities at `@workday/canvas-kit-react` has
+undergone a full design and a11y review and is approved for use in product.
+
+Breaking changes to code in Main will only occur during major version updates and will always be
+communicated in advance and accompanied by migration strategies.
+
+---
+
+### Preview
+
+Our Preview package of Canvas Kit tokens, components, and utilities at
+`@workday/canvas-kit-preview-react` has undergone a full design and a11y review and is approved for
+use in product, but may not be up to the high code standards upheld in the [Main](#main) package.
+Preview is analagous to code in beta.
+
+Breaking changes are unlikely, but possible, and can be deployed to Preview at any time without
+triggering a major version update, though such changes will be communicated in advance and
+accompanied by migration strategies.
+
+Generally speaking, our goal is to eventually promote code from Preview to [Main](#main).
+Occasionally, a component with the same name will exist in both [Main](#main) and Preview (for
+example, see Segmented Control in [Preview](/components/buttons/segmented-control/) and
+[Main](https://d2krrudi3mmzzw.cloudfront.net/v8/?path=/docs/components-buttons-segmented-control--basic)).
+In these cases, Preview serves as a staging ground for an improved version of the component with a
+different API. The component in [Main](#main) will eventually be replaced with the one in Preview.
+
+---
+
+### Labs
+
+Our Labs package of Canvas Kit tokens, components, and utilities at `@workday/canvas-kit-labs-react`
+has **not** undergone a full design and a11y review. Labs serves as an incubator space for new and
+experimental code and is analagous to code in alpha.
+
+Breaking changes can be deployed to Labs at any time without triggering a major version update and
+may not be subject to the same rigor in communcation and migration strategies reserved for breaking
+changes in [Preview](#preview) and [Main](#main).