@workday/canvas-kit-docs 5.3.0-next.3 → 5.3.0-next.32

package/dist/mdx/5.0-MIGRATION-GUIDE.mdx

@@ -10,6 +10,7 @@ any questions about the update.
   - [Canvas Kit Preview](#canvas-kit-preview)
   - [Type Deprecations and Hierarchy Updates](#type-deprecations-and-hierarchy-updates)
   - [Canvas Kit CSS Maintenance Mode](#canvas-kit-css-maintenance-mode)
+  - [Prop Interfaces](#prop-interfaces)
 - [Component Changes](#component-changes)
   - [Component Promotions](#component-promotions)
   - [Core](#core)
@@ -423,6 +424,59 @@ provide more focused support and to dedicate our efforts to making bigger and be
 our most used components: Canvas Kit React. If you have questions or concerns, please
 [let us know](https://github.com/Workday/canvas-kit/issues/new?labels=&template=question.md).
 
+### Prop Interfaces
+
+Many components were updated to be polymorphic using the `createComponent` utility function. Most
+components in Canvas Kit extend from an HTML interface and spread extra props onto the HTML element.
+Since these components are now polymorphic, the exported props no longer extend from an HTML
+interface since the HTML interface is now determined by an optional `as` prop. It is common to wrap
+Canvas Kit components with your own component and extend from the Canvas Kit component's prop
+interface. To support this use-case in addition to polymorphic prop interfaces, `ExtractProp` was
+introduced. `ExtractProp` understands these polymorphic components and will return the base props in
+addition to the HTML interface. There is an optional second argument that can override the default
+HTML interface if your wrapper component uses the `as`.
+
+```tsx
+// v4
+import {TextInput, TextInputProps} from '@workday/canvas-kit-react-text-input';
+
+const FancyTextInput: React.FC<TextInputProps> = props => <TextInput {...props} />;
+
+// v5
+import {TextInput} from '@workday/canvas-kit-react/text-input';
+import {ExtractProps} from '@workday/canvas-kit-react/common';
+
+const FancyTextInput: React.FC<ExtractProps<typeof TextInput>> = props => {};
+
+// v5 via createComponent
+import {TextInput} from '@workday/canvas-kit-react/text-input';
+import {createComponent} from '@workday/canvas-kit-react/common';
+
+const FancyTextInput = createComponent(TextInput)({
+  displayName: 'FancyTextInput',
+  Component((props) => <TextInput {...props} />)
+})
+```
+
+Components that made this change:
+
+- Button
+- IconButton
+- Card
+- Hyperlink
+- Select
+- TextArea
+- TextInput
+- Checkbox
+- Radio
+- ColorInput
+- ColorPreview
+- Modal
+- Popup
+- Skeleton
+- Tabs
+- Toast
+
 ## Component Changes
 
 ### Component Promotions
@@ -799,20 +853,25 @@ Button prop interface and accesses properties like `onClick`, you'll need to pro
 attribute yourself in order to avoid TypeScript issues (this doesn't affect runtime). This is not
 code-moddable since intent cannot be pre-determined.
 
+#### Props
+
+The exported props no longer extend from the `HTMLButtonElement` interface. Use
+[ExtractProps](#prop-interfaces) instead.
+
 ```tsx
 interface MyButtonProps extends ButtonProps {}
 
 // onClick no longer exists in `ButtonProps`, so TypeScript will complain about onClick not
 // existing in `MyButtonProps` (`onClick` does exist as a prop on `<Button>`, however)
 const MyButton = ({children, onClick}: MyButtonProps) => (
-  <Button onClick={onClick}>{children}</Button>
+  <SecondaryButton onClick={onClick}>{children}</SecondaryButton>
 );
 
 // After
-interface MyButtonProps extends ButtonProps, React.ButtonHTMLAttributes<HTMLButtonElement> {}
+interface MyButtonProps extends ExtractProps<typeof SecondaryButton> {}
 
 // After (alternate fix)
-interface MyButtonProps extends ButtonProps {
+interface MyButtonProps extends ExtractProps<> {
   onClick?: React.MouseEventHandler<HTMLButtonElement>;
 }
 ```
@@ -881,6 +940,21 @@ const props = {
 import {Card} from './Card' // where `Card` is a re-exported Canvas Kit `Card`
 ```
 
+#### Props
+
+The exported props no longer extend from the `HTMLDivElement` interface. Use
+[ExtractProps](#prop-interfaces) instead.
+
+```tsx
+// NOT handled by the codemod
+
+// v4
+interface MyCard extends CardProps {}
+
+// v5
+interface MyCard extends ExtractProps<typeof Card>
+```
+
 ---
 
 ### Inputs
@@ -924,14 +998,14 @@ element that `inputRef` was applied to previously. Select and Select (Preview) d
 `inputRef` in v4, but now support `ref` in v5. See each component's documentation for information on
 which element `ref` is forwarded to for that particular component.
 
+#### Props
+
 Input component prop interfaces no longer extend directly from their underlying element interface
 (e.g. `TextInputProps` no longer extends from `React.InputHTMLAttributes<HTMLInputElement>`).
 `createComponent` returns a component that determines the element interface via the `as` prop. This
 is why input component props no longer contain an element interface directly. If you extend from an
 input component prop interface, or have code that uses an input component prop interface and
-accesses properties like `onClick`, you'll need to provide the input attribute yourself in order to
-avoid TypeScript issues (this doesn't affect runtime). This is not code-moddable since intent cannot
-be pre-determined.
+accesses properties like `onClick`, you'll need to use [ExtractProps](#prop-interfaces) instead.
 
 ```tsx
 interface MyTextInputProps extends TextInputProps {}
@@ -941,7 +1015,7 @@ interface MyTextInputProps extends TextInputProps {}
 const MyTextInput = ({onClick}: MyTextInputProps) => <TextInput onClick={onClick} />;
 
 // Fix
-interface MyTextInputProps extends TextInputProps, React.InputHTMLAttributes<HTMLInputElement> {}
+interface MyTextInputProps extends ExtractProps<typeof TextInput> {}
 
 // Alternate fix
 interface MyTextInputProps extends TextInputProps {

package/dist/mdx/6.0-MIGRATION-GUIDE.mdx

@@ -0,0 +1,560 @@
+# Canvas Kit 6.0 Migration Guide
+
+Below are the breaking changes made in Canvas Kit v6. Please
+[reach out](https://github.com/Workday/canvas-kit/issues/new?labels=bug&template=bug.md) if you have
+any questions about the update.
+
+- [Codemod](#codemod)
+- [Component Deprecations](#component-deprecations)
+  - [Cookie Banner](#cookie-banner)
+  - [Header & Global Header](#header--global-header)
+  - [Page Header](#page-header)
+- [Component Migrations](#component-migrations)
+  - [Search Bar](#search-bar)
+- [Name Updates](#name-updates)
+  - [Depth Tokens](#depth-tokens)
+- [Theme Breakpoint Updates](#theme-breakpoint-updates)
+  - [Action Bar](#action-bar)
+- [Tabs Component](#tabs-component)
+- [Button Updates](#button-updates)
+  - [Primary Button](#primary-button)
+    - [Primary Disabled](#primary-disabled)
+    - [Primary Large](#primary-large)
+    - [Primary Medium](#primary-medium)
+    - [Primary Small](#primary-small)
+    - [Primary Extra Small](#primary-extra-small)
+  - [Secondary Button](#secondary-button)
+    - [Secondary Disabled](#secondary-disabled)
+    - [Secondary Large](#secondary-large)
+    - [Secondary Medium](#secondary-medium)
+    - [Secondary Small](#secondary-small)
+    - [Secondary Extra Small](#secondary-extra-small)
+  - [Tertiary Button](#tertiary-button)
+    - [Tertiary Default](#tertiary-default)
+    - [Tertiary Disabled](#tertiary-disabled)
+    - [Tertiary Medium](#tertiary-medium)
+    - [Tertiary Small](#tertiary-small)
+    - [Tertiary Extra Small](#tertiary-extra-small)
+
+## Codemod
+
+Please use our [codemod package](https://github.com/Workday/canvas-kit/tree/master/modules/codemod)
+to automatically update your code to work with a majority of the breaking changes in the migration
+from Canvas Kit v5 to v6:
+
+```sh
+> npx @workday/canvas-kit-codemod v6 [path]
+```
+
+> Note: This codemod only works on `.js`, `.jsx`, `.ts`, and `.tsx` extensions. You may need to make
+> some manual changes in other file types (`.json`, `.mdx`, `.md`, etc.).
+
+> Note: You may need to run your linter after executing the codemod, as it's resulting formatting
+> (spacing, quotes, etc.) may not match your project's styling.
+
+**Breaking changes accounted for by this codemod will be marked with a 🤖.**
+
+**Please verify all changes made by the codemod. As a safety precaution, we recommend committing the
+changes from the codemod as a single isolated commit (separate from other changes) so you can
+rollback more easily if necessary.**
+
+[Let us know](https://github.com/Workday/canvas-kit/issues/new?labels=bug&template=bug.md) if you
+encounter any issues or use cases that we've missed. The `@workday/canvas-kit-codemod` package will
+help us maintain additional codemod transforms to make future migrations easier.
+
+## Component Deprecations
+
+### Deprecation Types
+
+There are two types of deprecations: soft and hard.
+
+#### Soft Deprecation
+
+A soft-deprecated component is still available with its full functionality, but it will have been
+renamed with a prefix to indicate its soft-deprecated status. It will also include a console warning
+to announce its deprecation. This warning will only be triggered on the component's initial render.
+
+Soft-deprecated types and utilities will also be renamed but generally will not trigger a console
+warning.
+
+#### Hard Deprecation
+
+A hard-deprecated component or package is no longer available. You will need to follow the method
+prescribed in our migration guide to update your application. Please reach out to our team directly
+if you need additional help.
+
+### Cookie Banner
+
+We are [soft deprecating](#soft-deprecation) `CookieBanner`. It has been renamed to
+`DeprecatedCookieBanner`. Similarly, `CookieBannerProps` has been renamed to
+`DeprecatedCookieBannerProps`. You may continue to use this component exactly as you did in v5, but
+note that we plan to [hard-deprecate](#hard-deprecation) it in Canvas Kit v7.
+
+🤖 The codemod will rename `CookieBanner` and `CookieBannerProps` to their deprecated names:
+
+```tsx
+// v5
+import CookieBanner, {CookieBannerProps} from '@workday/canvas-kit-react/cookie-banner';
+
+export const CustomCookieBanner = (props: CookieBannerProps) => {
+  return <CookieBanner notice={CookieBanner.DefaultNotice} {...props} />;
+};
+
+// v6
+import DeprecatedCookieBanner, {
+  DeprecatedCookieBannerProps,
+} from '@workday/canvas-kit-react/cookie-banner';
+
+export const CustomCookieBanner = (props: DeprecatedCookieBannerProps) => {
+  return <DeprecatedCookieBanner notice={DeprecatedCookieBanner.DefaultNotice} {...props} />;
+};
+```
+
+```tsx
+// v5
+import {CookieBanner, CookieBannerProps} from '@workday/canvas-kit-react';
+
+interface CustomCookieBannerProps extends CookieBannerProps {
+  // custom page header props
+}
+
+export const CustomCookieBanner = (props: CustomCookieBannerProps) => {
+  return <CookieBanner notice={CookieBanner.DefaultNotice} {...props} />;
+};
+
+// v6
+import {DeprecatedCookieBanner, DeprecatedCookieBannerProps} from '@workday/canvas-kit-react';
+
+interface CustomCookieBannerProps extends DeprecatedCookieBannerProps {
+  // custom page header props
+}
+
+export const CustomCookieBanner = (props: CustomCookieBannerProps) => {
+  return <DeprecatedCookieBanner notice={DeprecatedCookieBanner.DefaultNotice} {...props} />;
+};
+```
+
+### Header & Global Header
+
+We are [soft deprecating](#soft-deprecation) `Header` and `GlobalHeader` and their related exports.
+They has been renamed to `DeprecatedHeader` and `DeprecatedGlobalHeader`, respectively. You may
+continue to use these components exactly as you did in v5, but note that we plan to
+[hard-deprecate](#hard-deprecation) this package in Canvas Kit v7.
+
+> Note: `SearchBar` is not being deprecated but will instead move to its own dedictated package. You
+> can read more [here](#search-bar).
+
+🤖 The codemod will handle all these changes automatically:
+
+- Rename import specifiers
+  - `DubLogoTitle` becomes `DeprecatedDubLogoTitle`
+  - `GlobalHeader` becomes `DeprecatedGlobalHeader`
+  - `Header` becomes `DeprecatedHeader`
+  - `HeaderHeight` becomes `DeprecatedHeaderHeight`
+  - `HeaderTheme` becomes `DeprecatedHeaderTheme`
+  - `HeaderVariant` becomes `DeprecatedHeaderVariant`
+  - `ThemeAttributes` becomes `DeprecatedHeaderThemeAttributes`
+  - `Themes` becomes `DeprecatedHeaderThemes`
+  - `WorkdayLogoTitle` becomes `DeprecatedWorkdayLogoTitle`
+  - `themes` becomes `deprecatedHeaderThemes`
+- Rename JSX identifiers
+  - `<DubLogoTitle>` becomes `<DeprecatedDubLogoTitle>`
+  - `<GlobalHeader>` becomes `<DeprecatedGlobalHeader>`
+  - `<Header>` becomes `<DeprecatedHeader>`
+  - `<WorkdayLogoTitle>` becomes `<DeprecatedWorkdayLogoTitle>`
+- Rename type references and interface declarations
+  - `type CustomHeaderHeight = HeaderHeight;` becomes
+    `type CustomHeaderHeight = DeprecatedHeaderHeight;`
+  - `type CustomHeaderTheme = HeaderTheme;` becomes
+    `type CustomHeaderTheme = DeprecatedHeaderTheme;`
+  - `type CustomHeaderVariant = HeaderVariant;` becomes
+    `type CustomHeaderVariant = DeprecatedHeaderVariant;`
+  - `type CustomThemeAttributes = ThemeAttributes;` becomes
+    `type CustomThemeAttributes = DeprecatedHeaderThemeAttributes;`
+  - `type CustomThemes = Themes;` becomes `type CustomThemes = DeprecatedHeaderThemes;`
+- Rename member expressions
+  - `HeaderHeight.Small` becomes `DeprecatedHeaderHeight.Small`
+  - `HeaderTheme.White` becomes `DeprecatedHeaderTheme.White`
+  - `HeaderVariant.Full` becomes `DeprecatedHeaderVariant.Full`
+  - `themes.Blue` becomes `deprecatedHeaderThemes.Blue`
+  - `Header.Variant.Global` becomes `DeprecatedHeader.Variant.Global`
+
+```tsx
+// v5
+import Header, {DubLogoTitle, GlobalHeader} from '@workday/canvas-kit-labs-react/header';
+
+const CustomGlobalHeader = props => {
+  return (
+    <GlobalHeader
+      brand={
+        <a href="#">
+          <DubLogoTitle themeColor={Header.Theme.White} />
+        </a>
+      }
+      {...props}
+    />
+  );
+};
+
+// v6
+import DeprecatedHeader, {
+  DeprecatedDubLogoTitle,
+  DeprecatedGlobalHeader,
+} from '@workday/canvas-kit-labs-react/header';
+
+const CustomGlobalHeader = props => {
+  return (
+    <DeprecatedGlobalHeader
+      brand={
+        <a href="#">
+          <DeprecatedDubLogoTitle themeColor={DeprecatedHeader.Theme.White} />
+        </a>
+      }
+      {...props}
+    />
+  );
+};
+```
+
+You may continue to use this component exactly as you did in v5, but note that we plan to hard-deprecate it in Canvas Kit v7.
+If you would like to migrate away from this deprecated component now, you can reference [this example](https://workday.github.io/canvas-kit/?path=/story/examples-global-header-react--basic) instead.
+
+### Page Header
+
+We are [soft-deprecating](#soft-deprecation) `PageHeader`. It has been renamed to
+`DeprecatedPageHeader`. Similarly, `PageHeaderProps` has been renamed to
+`DeprecatedPageHeaderProps`. You may continue to use this component exactly as you did in v5, but
+note that we plan to [hard-deprecate](#hard-deprecation) it in Canvas Kit v7.
+
+🤖 The codemod will rename `PageHeader` and `PageHeaderProps` to their deprecated names:
+
+```tsx
+// v5
+import PageHeader, {PageHeaderProps} from '@workday/canvas-kit-react/page-header';
+
+export const CustomPageHeader = (props: PageHeaderProps) => {
+  return <PageHeader {...props} />;
+};
+
+// v6
+import DeprecatedPageHeader, {
+  DeprecatedPageHeaderProps,
+} from '@workday/canvas-kit-react/page-header';
+
+export const CustomPageHeader = (props: DeprecatedPageHeaderProps) => {
+  return <DeprecatedPageHeader {...props} />;
+};
+```
+
+```tsx
+// v5
+import {PageHeader, PageHeaderProps} from '@workday/canvas-kit-react';
+
+interface CustomPageHeaderProps extends PageHeaderProps {
+  // custom page header props
+}
+
+export const CustomPageHeader = (props: CustomPageHeaderProps) => {
+  return <PageHeader {...props} />;
+};
+
+// v6
+import {DeprecatedPageHeader, DeprecatedPageHeaderProps} from '@workday/canvas-kit-react';
+
+interface CustomPageHeaderProps extends DeprecatedPageHeaderProps {
+  // custom page header props
+}
+
+export const CustomPageHeader = (props: CustomPageHeaderProps) => {
+  return <DeprecatedPageHeader {...props} />;
+};
+```
+
+You may continue to use this component exactly as you did in v5, but note that we plan to hard-deprecate it in Canvas Kit v7.
+If you would like to migrate away from this deprecated component now, you can reference [this example](https://workday.github.io/canvas-kit/?path=/story/examples-page-header-react--basic) instead.
+
+## Component Migrations
+
+### Search Bar
+
+`SeachBar` is being renamed to `SearchForm` and is moving out of
+`@workday/canvas-kit-labs-react/header` into its own dedicated package,
+`@workday/canvas-kit-labs-react/search-form`. The component has not been modified and you may
+continue to use this component exactly as you did in v5.
+
+🤖 The codemod will handle all these changes automatically:
+
+- Rename import sources
+  - `@workday/canvas-kit-labs-react/header` becomes `@workday/canvas-kit-labs-react/search-form`
+- Rename import specifiers
+  - `SearchBar` becomes `SearchForm`
+  - `SearchBarProps` becomes `SearchFormProps`
+  - `SearchBarState` becomes `SearchFormState`
+- Rename JSX identifiers
+  - `<SearchBar>` becomes `<SearchForm>`
+- Rename type references and interface declarations
+  - `type CustomSearchProps = SearchBarProps;` becomes `type CustomSearchProps = SearchFormProps;`
+  - `interface CustomSearchProps extends SearchBarProps` becomes
+    `interface CustomSearchProps extends SearchFormProps`
+
+```tsx
+// v5
+import {
+  SearchBar,
+  SearchBarProps,
+  SearchBarState,
+  SearchThemeAttributes,
+  SearchTheme,
+} from '@workday/canvas-kit-labs-react/header';
+
+const CustomSearchForm = (props: SearchFormProps) => {
+  return <SearchForm searchTheme={SearchTheme.Dark} {...props} />;
+};
+
+// v6
+import {
+  SearchForm,
+  SearchFormProps,
+  SearchFormState,
+  SearchThemeAttributes,
+  SearchTheme,
+} from '@workday/canvas-kit-labs-react/search-form';
+
+const CustomSearchForm = (props: SearchFormProps) => {
+  return <SearchForm searchTheme={SearchTheme.Dark} {...props} />;
+};
+```
+
+## Name Updates
+
+### Depth Tokens
+
+The `CanvasDepthValue` type has been renamed to `CanvasDepthValues` to be more consistent with our
+other token type names, such as `CanvasBorderRadiusValues`, `CanvasSpaceValues`, and
+`CanvasSpaceNumberValues`.
+
+🤖 The codemod will handle this rename transformation automatically:
+
+```ts
+// v5
+import {CanvasDepthValue} from '@workday/canvas-kit-react/tokens';
+
+type CustomDepthValues = CanvasDepthValue;
+interface OtherCustomDepthValues extends CanvasDepthValue {}
+
+// v6
+import {CanvasDepthValues} from '@workday/canvas-kit-react/tokens';
+
+type CustomDepthValues = CanvasDepthValues;
+interface OtherCustomDepthValues extends CanvasDepthValues {}
+```
+
+## Theme Breakpoint Updates
+
+Our default theme breakpoints have been updated to match the viewport ranges described in our design
+guidelines. We also updated `ActionBar`'s media query to align with this change. Those changes are
+described in [the section below](#action-bar). If you are using these default breakpoints, you will
+need to do visual regression testing to ensure there are no adverse effects to your application's
+layout. If you have questions about this testing, please reach out to our team.
+
+Below is a reference table for the V5 and V6 breakpoint values.
+
+| Breakpoint Name | V5 Value (px) | V6 Value (px) |
+| --------------- | ------------- | ------------- |
+| `zero`          | 0             | 0             |
+| `s`             | 600           | 320           |
+| `m`             | 900           | 768           |
+| `l`             | 1280          | 1024          |
+| `xl`            | 1920          | 1440          |
+
+Also for reference, these are our viewport ranges:
+
+- `small` (`320px` - `767px`) Used for mobile-sized screens
+- `medium` (`768px` - `1023px`) Used for tablet-sized screens
+- `large` - (`1024px` - `1439px`) Used for laptop and small desktop screens
+- `extra-large` (`≥1440px`) Used for very large screens
+
+### Action Bar
+
+`ActionBar` was updated to use the new breakpoint values. It previously had two media queries with
+`max-width: 575px`. They now use `max-width: 767.5px` – the upper limit of the `small` range. This
+will have two effects for this component:
+
+- Container padding will decrease from `s` (`16px`) to `xxs` (`8px`) on all viewports less than `768px` wide
+  - This was previously happening only on viewports less than `576px` wide
+- Button order will be reversed on all viewports less than `768px` wide
+  - This was previously happening only on viewports less than `576px` wide
+
+These changes in behavior are intentional and expected.
+
+## Tabs Component
+
+The Tabs API changed to support a responsive layout
+([#1325](https://github.com/Workday/canvas-kit/pull/1325)). The model API was updated to support
+more generic behaviors to allow for other components to support responsive layouts using the same
+models and behaviors. The most notable changes were concerning the state and events around tab
+selection. The verb "select" was chosen to more accurately reflect selection for more component
+types. Also selection of lists (which Tabs is based on) can support single or multiple selection.
+Selection is now stored on state as an array of selected keys.
+
+```tsx
+// v5
+const model = useTabsModel({
+  shouldActivate,
+  onActivate,
+});
+
+console.log('Selected tab', model.state.activeTab);
+model.events.activate({tab: tabName});
+
+// v6
+const model = useTabsModel({
+  shouldSelect,
+  onSelect,
+});
+
+console.log('Selected tab', model.state.selectedKey[0]);
+model.events.select({id: tabName});
+```
+
+The Tabs component can now handle responsive containers, but the support is not automatic. You must
+use the dynamic API and provide an overflow menu subcomponent. The dynamic API doesn't know the
+shape of your object, so render props must be used to instruct React how to render each item.
+
+```tsx
+// Use `useState` because React will give the same reference each render
+const [items] = React.useState([
+  {id: 'first', text: 'First Tab', contents: 'First Tab Content'},
+  {id: 'second', text: 'Second Tab', contents: 'Second Tab Content'},
+]);
+
+return (
+  <Tabs items={items}>
+    <Tabs.List overflowButton={<Tabs.OverflowButton>More</Tabs.OverflowButton>}>
+      {item => <Tabs.Item name={item.id}>{item.text}</Tabs.Item>}
+    </Tabs.List>
+    <Tabs.Menu.Popper>
+      <Tabs.Menu.Card maxWidth={300} maxHeight={200}>
+        <Tabs.Menu.List>
+          {(item: MyTabItem) => <Tabs.Menu.Item name={item.id}>{item.text}</Tabs.Menu.Item>}
+        </Tabs.Menu.List>
+      </Tabs.Menu.Card>
+    </Tabs.Menu.Popper>
+  </Tabs>
+);
+```
+
+## Button Updates
+
+All button updates for V6 are limited to our Primary, Secondary, and Tertiary buttons. Most of the
+button updates are small visual adjustments:
+
+- We tightened up tighten the spacing for visual balance and added our new type hierarchy.
+- We adjusted icon sizes for uniformity:
+  - `large`: `24px` x `24px`
+  - `medium`: `20px` x `20px`
+  - `small`: `20px` x `20px`
+  - `extraSmall`: `18px` x `18px`
+- We also adjusted the opacity for their disabled state so they behave more appropriately on varied
+  / dark backgrounds.
+
+These changes are automatic when you upgrade and do not require any manual updates in your codebase.
+However, they will likely cause any automated visual regression tests to fail, and you will need to
+update your tests accordingly. We do not expect these minor adjustments to create significant layout
+shifts in your UI. But, as with any visual update, you will want to review your UI to ensure there
+are no adverse effects.
+
+We also added some net-new features:
+
+- All buttons have a new `extraSmall` size.
+- Icons are now supported for all sizes.
+- `PrimaryButton` has a new `inverse` variant.
+
+All these changes are described in detail by button type in the sections below.
+
+### Primary Button
+
+#### Primary Disabled State
+
+Previously the button's disabled state had a `blueberry200` background, but it now uses the default
+`blueberry400` and sets the entire button to 40% opacity. This creates more consistency for the
+disabled states across all our buttons.
+
+#### Primary Large
+
+The padding for large `PrimaryButton`s has been slightly adjusted for more visual balance and to
+take up a bit less layout space. Specifically we:
+
+- decreased the space between the button icon and text from `12px` to `8px`
+- decreased the space between the button container and the icon from `28px` to `24px`
+
+#### Primary Medium
+
+The icon size for medium `PrimaryButton`s has been decreased from `24px` to `20px`, but the overall
+height of the button will remain the same.
+
+#### Primary Small
+
+We now support icons for small `PrimaryButton`s. The icons are `20px` x `20px`.
+
+#### Primary Extra Small
+
+We added a new size, `extraSmall` to our `PrimaryButton`s. These are particularly helpful for use
+cases where you have dense UI or tight layout constraints such as tables.
+
+### Secondary Button
+
+#### Secondary Large
+
+The padding for large `SecondaryButton`s has been slightly adjusted for more visual balance and to
+take up a bit less layout space. Specifically we:
+
+- decreased the space between the button icon and text from `12px` to `8px`
+- decreased the space between the button container and the icon from `28px` to `24px`
+
+#### Secondary Medium
+
+The icon size for medium `SecondaryButton`s has been decreased from `24px` to `20px`, but the
+overall height of the button will remain the same.
+
+#### Secondary Small
+
+We now support icons for small `SecondaryButton`s. The icons are `20px` x `20px`.
+
+#### Secondary Extra Small
+
+We added a new size, `extraSmall` to our `SecondaryButton`s. These are particularly helpful for use
+cases where you have dense UI or tight layout constraints such as tables.
+
+### Tertiary Button
+
+#### Tertiary Default
+
+We added an underline to the button text for all states to help distinguish it from the
+`SecondaryButton` and create more visual consistency.
+
+#### Tertiary Disabled
+
+As with our other buttons, we updated the disabled state to set the entire button to 40% opacity.
+They were previously using our light theme color at 50% opacity for icons and text.
+
+#### Tertiary Medium
+
+The medium `TertiaryButton` now uses our new type hierarchy and adjusted the padding, but the
+overall size of the button will stay the same. Specifically, we:
+
+- decreased the space between the button icon and text from `8px` to `4px`
+
+#### Tertiary Small
+
+The small `TertiaryButton` now uses our new type hierarchy and adjusted the padding, but the overall
+size of the button will stay the same. Specifically, we:
+
+- decreased the space between the button icon and text from `8px` to `4px`
+- increased the container padding outside the button text when an icon is present from `8px` to
+  `12px`
+
+#### Tertiary Extra Small
+
+We added a new size, `extraSmall` to our `TertiaryButton`s. These are particularly helpful for use
+cases where you have dense UI or tight layout constraints such as tables.