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.

To minimize the impact of this release, the new tokens were added and the old ones were deprecated. This means that the old tokens and respective tailwind classes still work in this version, but they are deprecated and will be removed in a future version.

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

As some components have their props relying on these tokens, the props were also updated to reflect the changes in the design tokens. The old values of the props also still work in this version, but they are deprecated and will be removed in a future version.

We recommend to start adopting the new values as soon as possible.

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

Five elevation (box shadow) tokens were deprecated (to be removed in the next major version) and five new ones were added.

Here’s the mapping for the new tokens:

• elevationActionBoxShadow -> elevationLevel1BoxShadow
• elevationActionActiveBoxShadow -> elevationLevel2BoxShadow
• elevationRaisedBoxShadow -> elevationLevel3BoxShadow
• elevationRaisedReverseBoxShadow -> elevationLevel3ReverseBoxShadow
• elevationOverlayBoxShadow -> elevationLevel4BoxShadow

And their respective tailwind classes:

• shadow-action -> shadow-level1
• shadow-action-active -> shadow-level2
• shadow-raised -> shadow-level3
• shadow-raised-reverse -> shadow-level3-reverse
• shadow-overlay -> shadow-level4

The spacing tokens were also updated, allowing for more flexibility in the spacing values. The new tokens and their corresponding mapping are:

• spaceXXXSmall -> space50 (2px)
• spaceXXSmall -> space100 (4px)
• (new token) -> space150 (6px)
• spaceXSmall -> space200 (8px)
• spaceSmall -> space300 (12px)
• spaceMedium -> space400 (16px)
• (new token) -> space500 (20px)
• spaceLarge -> space600 (24px)
• spaceXLarge -> space800 (32px)
• spaceXXLarge -> space1000 (40px)
• (new token) -> space1200 (48px)
• spaceXXXLarge -> DEPRECATED (52px)
• (new token) -> space1600 (64px)

This means that a vast number of tailwind classes were also updated to reflect these changes. Below, some examples of the updated classes, although we are not listing them all, as there are too many:

• p-xxxs -> p-50
• m-xxs -> m-100
• h-xs-> h-200
• w-sm -> w-300
• size-md -> size-400
• top-lg -> top-600
• space-x-xl -> space-x-800
• space-y-xxl -> space-y-1000
• left-xxxl -> left-[52px] (custom hardcoded value)

The spaceXXXLarge token is deprecated and will be removed in a future version, as well as all tailwind classes associated to it. If you are using it or any tailwind class associated to its value, please replace it with a custom hardcoded value, or check with your designer for the best alternative solution.

The borderRadius and elevation props were updated to reflect the changes in the design tokens.

Before:

<Box borderRadius="small" elevation="action">…</Box>
<Box borderRadius="normal" elevation="raised">…</Box>
<Box borderRadius="large" elevation="raisedReverse">…</Box>
<Box borderRadius="circle" elevation="overlay">…</Box>

Now:

<Box borderRadius="50" elevation="level1">…</Box>
<Box borderRadius="100" elevation="level3">…</Box>
<Box borderRadius="150" elevation="level3Reverse">…</Box>
<Box borderRadius="full" elevation="level4">…</Box>

Both padding and margin props were updated to reflect the changes in the design tokens. The change also applies when using the object notation and inside media queries props.

The code snippets below show some examples of the changes.

Before:

<Box padding="XXXSmall">"XXXSmall" padding</Box>
<Box margin="XXSmall">"XXSmall" margin</Box>
<Box padding={{ top: "XSmall", left: "small" }}>padding-top="XSmall"; padding-left="small"</Box>
<Box margin={{ bottom: "medium", right: "large" }}>margin-bottom="medium"; margin-right="large"</Box>
<Box tablet={{ padding: "XLarge", margin: "XXLarge" }}>padding="XLarge"; margin="XXLarge" (tablet and bigger)</Box>

Now:

<Box padding="50">"50" padding</Box>
<Box margin="100">"100" margin</Box>
<Box padding={{ top: "200", left: "300" }}>padding-top="200"; padding-left="300"</Box>
<Box margin={{ bottom: "400", right: "600" }}>margin-bottom="400"; margin-right="600"</Box>
<Box tablet={{ padding: "800", margin: "1000" }}>padding="800"; margin="1000" (tablet and bigger)</Box>

The spacing prop in Stack was updated to accept the new values associated with the new design tokens. Similarly to the Box component, the media queries props also accept the new values for spacing.

Before:

<Stack spacing="XXSmall">"XXSmall" spacing</Stack>
<Stack tablet={{ spacing: "small" }}>"small" spacing (tablet and bigger)</Stack>
// ...

Now:

<Stack spacing="100">"100" spacing</Stack>
<Stack tablet={{ spacing: "300" }}>"300" spacing (tablet and bigger)</Stack>
// ...

The spacing prop in HorizontalScroll inherits its values from the Stack component. Therefore, it was also updated to accept new values associated with the new design tokens.

Before:

<HorizontalScroll spacing="XXSmall">"XXSmall" spacing</HorizontalScroll>
// ...

Now:

<HorizontalScroll spacing="100">"100" spacing</HorizontalScroll>
// ...

The spacing prop in LinkList inherits its values from the Stack component. Therefore, it was also updated to accept new values associated with the new design tokens.

Before:

<LinkList spacing="XXSmall">"XXSmall" spacing</LinkList>
// ...

Now:

<LinkList spacing="100">"100" spacing</LinkList>
// ...

The spacing prop in Tabs inherits its values from the Stack component. Therefore, it was also updated to accept new values associated with the new design tokens.

Before:

<Tabs spacing="XXSmall">"XXSmall" spacing</Tabs>
// ...

Now:

<Tabs spacing="100">"100" spacing</Tabs>
// ...

The spacing prop in Inline was also updated to accept the new values from the tokens.

Before:

<Inline spacing="XXSmall">"XXSmall" spacing</Inline>
// ...

Now:

<Inline spacing="100">"100" spacing</Inline>
// ...

The sideOffset prop in Separator was also updated to accept the new values from the tokens.

Before:

<Separator spacing="small">"small" spacing</Separator>
// ...

Now:

<Separator spacing="300">"300" spacing</Separator>
// ...

A codemod is available to help with the migration. It should target 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 guarantee a full migration, nor its complete correcteness. Manual checks are still necessary, especially if prop values are being calculated conditionally.

The codemod should be executed from your code directory. It will look for all files with the extensions .js, .jsx, .ts, and .tsx in the current directory and all its subfolders. To execute, run the following command:

curl -fsSL https://raw.githubusercontent.com/kiwicom/orbit/master/packages/orbit-components/transforms/tokens-v16.mjs | node --input-type=module