@workday/canvas-kit-docs/dist/mdx/11.0-UPGRADE-GUIDE.mdx

Documentation components of Canvas Kit components

import { Table } from '@workday/canvas-kit-react/table';
import { base, brand, system } from '@workday/canvas-tokens-web';
import { StatusIndicator } from '@workday/canvas-kit-preview-react/status-indicator';
import { cssVar } from '@workday/canvas-kit-styling';
import { Box } from '@workday/canvas-kit-react/layout';


# 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
import {LabelText} from '@workday/canvas-kit-react/text';

<form>
  <LabelText>Pizza</LabelText>
  <input type="text" />
</form>;

//v11
import {FormField} from '@workday/canvas-kit-preview-react/form-field';
import {TextInput} from '@workday/canvas-kit-react/text-input';

<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 cs={{backgroundColor: cssVar(base.soap600)}}>soap600</Table.Cell>
      <Table.Cell cs={{color: cssVar(base.frenchVanilla100), backgroundColor: cssVar(base.licorice100)}}>
        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 cs={{backgroundColor: cssVar(base.soap600)}}>soap600</Table.Cell>
      <Table.Cell cs={{color: cssVar(base.frenchVanilla100), backgroundColor: cssVar(base.licorice100)}}>
        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 cs={{backgroundColor: cssVar(brand.error.light)}}>error.light</Table.Cell>
      <Table.Cell cs={{backgroundColor: 'rgba(222,46,33,0.4)'}}>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 cs={{backgroundColor: cssVar(base.soap600)}}>soap600</Table.Cell>
      <Table.Cell cs={{color: cssVar(base.frenchVanilla100), backgroundColor: cssVar(base.licorice100)}}>
        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 cs={{color: cssVar(base.blackPepper400), backgroundColor: cssVar(base.soap400)}}>
        soap400
      </Table.Cell>
      <Table.Cell cs={{color: cssVar(base.blackPepper400), backgroundColor: 'transparent'}}>
        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 cs={{color: cssVar(base.frenchVanilla100), backgroundColor: cssVar(base.blackPepper500)}}>
        blackPepper500
      </Table.Cell>
      <Table.Cell cs={{color: cssVar(base.frenchVanilla100), backgroundColor: cssVar(base.blackPepper400)}}>
        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 cs={{color: cssVar(base.frenchVanilla100), backgroundColor: cssVar(base.blackPepper500)}}>
        blackPepper500
      </Table.Cell>
      <Table.Cell cs={{color: cssVar(base.frenchVanilla100), backgroundColor: cssVar(base.blackPepper400)}}>
        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 cs={{color: cssVar(base.frenchVanilla100), backgroundColor: cssVar(base.blackPepper500)}}>
        blackPepper500
      </Table.Cell>
      <Table.Cell cs={{color: cssVar(base.frenchVanilla100), backgroundColor: cssVar(base.blackPepper400)}}>
        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 cs={{color: cssVar(base.frenchVanilla100), backgroundColor: cssVar(base.blackPepper500)}}>
        blackPepper600
      </Table.Cell>
      <Table.Cell cs={{backgroundColor: cssVar(system.color.bg.translucent), color: cssVar(base.frenchVanilla100)}}>
        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 cs={{backgroundColor: cssVar(base.blueberry200)}}>blueberry200</Table.Cell>
      <Table.Cell cs={{backgroundColor: 'rgba(8,117,225,.3)'}}>
        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 cs={{backgroundColor: cssVar(base.soap400)}}>soap400</Table.Cell>
      <Table.Cell cs={{backgroundColor: cssVar(base.soap500)}}>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 cs={{backgroundColor: cssVar(base.soap200)}}>soap200</Table.Cell>
      <Table.Cell cs={{backgroundColor: cssVar(base.soap300)}}>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 cs={{backgroundColor: cssVar(base.soap300)}}>soap300</Table.Cell>
      <Table.Cell cs={{backgroundColor: cssVar(base.soap400)}}>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 cs={{color: cssVar(base.frenchVanilla100), backgroundColor: cssVar(brand.primary.dark)}}>
        primary.dark
      </Table.Cell>
      <Table.Cell cs={{color: cssVar(base.frenchVanilla100), backgroundColor: cssVar(brand.primary.darkest)}}>
        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 cs={{color: cssVar(base.frenchVanilla100), backgroundColor: cssVar(base.blackPepper500)}}>
        blackPepper500
      </Table.Cell>
      <Table.Cell cs={{color: cssVar(base.frenchVanilla100), backgroundColor: cssVar(base.blackPepper400)}}>
        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 cs={{color: cssVar(base.frenchVanilla100), backgroundColor: cssVar(base.blackPepper500)}}>
        blackPepper500
      </Table.Cell>
      <Table.Cell cs={{color: cssVar(base.frenchVanilla100), backgroundColor: cssVar(base.blackPepper400)}}>
        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 cs={{backgroundColor: cssVar(base.soap600)}}>soap600</Table.Cell>
      <Table.Cell cs={{color: cssVar(base.frenchVanilla100), backgroundColor: cssVar(base.licorice100)}}>
        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 cs={{backgroundColor: cssVar(base.soap600)}}>soap600</Table.Cell>
      <Table.Cell cs={{color: cssVar(base.frenchVanilla100), backgroundColor: cssVar(base.licorice100)}}>
        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
import {FormField} from '@workday/canvas-kit-preview-react/form-field';
import {TextInput} from '@workday/canvas-kit-react/text-input';

<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
import {FormField} from '@workday/canvas-kit-preview-react/form-field';
import {TextInput} from '@workday/canvas-kit-react/text-input';

<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.
import {base} from '@workday/canvas-tokens-web';
<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
import {accentIconStencil} from '@workday/canvas-kit-react/icon';

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
import {appletIconStencil} from '@workday/canvas-kit-react/icon';

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
import {systemIconStencil} from '@workday/canvas-kit-react/icon';

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
import {Table, TableRow} from '@workday/canvas-kit-react/table';

<Table>
  <thead>
    <TableRow header={true}>
      <th>Header Text</th>
    </TableRow>
  </thead>
  <tbody>
    <TableRow>
      <td>Cell Text</td>
    </TableRow>
  </tbody>
</Table>;

// v11
import {Table} from '@workday/canvas-kit-react/table';

<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).