This migration guide focuses on the process of migrating from Orbit v15 to v16.0, as some breaking changes were introduced. With this guide, we aim to walk through all the breaking changes and how they can be addressed, allowing the migration to be smoother and effortlessly.

This version addresses especially a change in the design tokens, and tailwind classes.

A new heading token was added: title0. This token is similar to the previously existing title1 token. Therefore, title1 token was updated to have new font size and line height values.

With that, the Heading component now accepts a new value for the type prop: "title0".

Because of that, all occurrences of Heading with type="title1" must be replaced with type="title0", to avoid the visual breaking change.

Before:

<Heading type="title1">Title 1</Heading>

Now:

<Heading type="title0">Title 0</Heading>

The Tailwind classes should also be updated. So if you are using tailwind classes that refer to title1 in your components, be sure to update them to use title0 in order to keep the same styles.

Before:

<p className="leading-heading-title1 text-heading-title1 font-heading-title1">Title 1</p>

Now:

<p className="leading-heading-title0 text-heading-title0 font-heading-title0">Title 0</p>

A number of new design tokens were introduced and others were removed. This means that some of the tailwind classes have been updated to reflect these changes.

Some deprecated Heading tokens were removed. They have been deprecated since the first Tailwind release and were now finally removed. The equivalent new tokens are:

• fontSizeHeading<TYPE> -> heading<TYPE>FontSize
• lineHeightHeading<TYPE> -> heading<TYPE>LineHeight
• fontWeightHeading<TYPE> -> heading<TYPE>FontWeight

Where <TYPE> can be Display, DisplaySubtitle, Title1, Title2, Title3, Title4, Title5, or Title6.

Four border radius tokens were deprecated (to be released in the next major version) and six new ones were added.

Here’s the mapping for the new tokens:

• borderRadiusSmall -> borderRadius50
• borderRadiusNormal -> borderRadius100 (value change from 3px to 4px)
• borderRadiusLarge -> borderRadius150
• borderRadiusCircle -> borderRadiusFull
• borderRadius300 (new value of 12px)
• borderRadius400 (new value of 16px)

And their respective tailwind classes:

• rounded-small -> rounded-50
• rounded-normal -> rounded-100 (value change from 3px to 4px)
• rounded-large -> rounded-150
• rounded-circle -> rounded-full
• rounded-300
• rounded-400

We recommend to start adopting the new tokens and classes as soon as possible.

Because the Box component props rely heavily on design tokens and their values, some of the prop values have been updated to reflect the changes in the design tokens.

Before:

<Box borderRadius="small">"small" borderRadius</Box>
<Box borderRadius="normal">"normal" borderRadius</Box>
<Box borderRadius="large">"large" borderRadius</Box>
<Box borderRadius="circle">"circle" borderRadius</Box>

Now:

<Box borderRadius="50">"50" borderRadius</Box>
<Box borderRadius="100">"100" borderRadius</Box>
<Box borderRadius="150">"150" borderRadius</Box>
<Box borderRadius="full">"full" borderRadius</Box>

A codemod was made available to help with the migration. It should target all the tokens and tailwind classes that were updated and correctly migrate them.

Please ensure the changes are expected and there is no change missing. Please note that the codemod does not cover the Box component changes.

node .../transforms/tokens-v16.mjs