Migrate from v6 to v7

[filiptammergard]

Breaking changes when migrating from v6 to v7:

Color primitives

The color primitives structure is revamped to increase flexibility and scalability. The color themes are built using color primitives. While a theme color property changes depending on active color theme, a color primitive is always the same. The intention is that the color primitives only should be used by library consumers directly as an escape hatch in rare cases.

The hope is that the evolved color primitives structure with the related theme updates (see next section) will make the theme cover a larger set of color needs and thus reduce the need of reaching for color primitives, while also providing a scalable foundation for future color primitive additions.

Detailed color primitive updates

In v6, there were three color variants for all base colors, using light, default and dark as property names. See the green base color object as an example:

green: {
  light: "#99FB66",
  default: "#1FCF01",
  dark: "#00A500",
},

There has been a need for a fourth color variant, but it was not obvious what property name to give it. Instead of adding something like lighter or medium, we decided to change the color primitives structure in v7 to allow for adding more colors in the future without breaking changes or awkward property names. The v7 structure use numbers as property names instead, like this for the green base color object:

green: {
  20: "#99FB66",
  40: "#1FCF01",
  60: "#0D9D01",
  80: "#016A01",
},

With this change, adding a new color variant is as easy as adding a new property with a logical property name number depending of the brightness of the color (10 if it's lighter than the 20 variant as an example).

In v6, there were a greyscale base color object:

greyscale: {
  white: "#FFFFFF",
  grey20: "#F5F5F5",
  grey40: "#EBEBEB",
  grey50: "#DADADA",
  grey80: "#7A7A7A",
  grey90: "#2D2D2E",
  grey100: "#1E1E1F",
  black: "#121212",
},

In v7, we decided to change the pattern to align with the other colors:

grey: {
  10: "#F5F5F5",
  20: "#EBEBEB",
  30: "#DADADA",
  50: "#ABABAB",
  60: "#7A7A7A",
  80: "#2D2D2E",
  90: "#1E1E1F",
},

Instead of white and black being a part of the greyscale object as in v6, they are placed in the root of the color object in v7:

color: {
  green: {
    // ...
  },
  // ...
  grey: {
    // ...
  },
  white: "#FFFFFF",
  black: "#121212",
}

Here are some examples of changes in how to access the primitives in v7 compared to v6.

import { color } from "@einride/ui"

-color.greyscale.black
+color.black

-color.greyscale.white
+color.white

-color.greyscale.grey40
+color.grey[20]

-color.greyscale.grey100
+color.grey[90]

-color.green.light
+color.green[20]

Theme

• The deprecated customTheme prop is removed from <EinrideProvider>. It was used in the early stage of Einride UI, mainly for the website, but is not needed anymore.

• The type of the theme prop on <EinrideProvider> is changed from any to DeepPartial<Theme> to make it easier to know how the theme is supposed to be overridden.

• The default value of the colorMode prop on <EinrideProvider> is changed from light to system. If you want to continue forcing light color mode, you need to set it explicitly.

• The deprecated theme properties theme.colors.background.reverse and theme.colors.content.reverse are removed. Use primaryInverted instead of reverse. This naming change was done to allow better for using secondaryInverted as an addition to reverse/primaryInverted.

- theme.colors.background.reverse
+ theme.colors.background.primaryInverted

- theme.colors.content.reverse
+ theme.colors.content.primaryInverted

• Theme deprecated theme property theme.grid is removed. It's not used anywhere and if we need grid helpers in the theme in the future we'll add them then.

• secondary and tertiary theme background properties have been updated to use opacity, to allow better for using components inside of containers with various background colors. If there is a need of opting out of the added opacity, secondaryElevated and tertiaryElevated can be used, respectively.

Rationale behind using opacity

If you wanted to use an input inside a card with background="secondary" in v6, there was no contrast between them:

<Card background="secondary">
  <TextInput label="Label" />
</Card>

For that reason, a secondaryOpacity theme background property was introduced, which gave contrast between the two:

<Card background="secondary">
  <TextInput label="Label" background="secondaryOpacity" />
</Card>

Using opacity provides flexibility in the way it allows for putting a component on an arbitrary background. Here's the same input component on a card with a random blue background:

<Card background="#080055">
  <TextInput label="Label" background="secondaryOpacity" />
</Card>

It adds contrast while still letting a part of the background bleed through. Compare that to using the default background without opacity in v6:

<Card background="#080055">
  <TextInput label="Label" />
</Card>

Looks awkward. Another benefit related to using opacity is that it works in an arbitrary amount of levels. Here's an input in a card in a card as an example:

<Card background="secondaryOpacity">
  <Text>Text inside first card</Text>
  <Card background="secondaryOpacity">
    <Text>Text inside second card</Text>
    <TextInput label="Label" background="secondaryOpacity" />
  </Card>
</Card>

They all have contrast automatically, while still using the same theme background property. This technique is used by for example Apple to provide flexibility out of the box. Providing the same flexibility without opacity would require adding many new theme color properties, which would in turn make it more difficult to know when to use what theme property.

• theme.colors.background.secondaryOpacity and theme.colors.background.tertiaryOpacity are removed, since opacity is added theme.colors.background.secondary and theme.colors.background.tertiary instead.

- theme.colors.background.secondaryOpacity
+ theme.colors.background.secondary

- theme.colors.background.tertiaryOpacity
+ theme.colors.background.tertiary

• positive, warning and negative theme background colors are revamped with increased vividness and without opacity. Unlike secondary and tertiary theme background colors, these variants have proven to be better off not using opacity. Since these colors reflect a status (success, error or warning for example), they should not be influenced by container background color, as that could make the status information less clear. Positive should be positive independent on the background of the container.

Components

• <Label> is updated to take advantage over the new color primitives. In v6, these were the available <Label> variants:

In v7, these are available:

This is also an example on how the new color primitives increase background color vividness, while using primary/primaryInverted and text color property.

• The deprecated columns prop on <PrimaryButton>, <SecondaryButton> and <TertiaryButton> is removed. It was used in some places in an early stage of Einride UI, but it's not supposed to be used anymore.

• The deprecated <Popover> component is removed. Use <Alert> or <Sheets> instead. <Alert> should be used for small mandatory confirmation actions and <Sheets> should be used as a regular dialog with the possibility to show more content.

• The deprecated <Segments> component is removed. Use <Tabs> instead.

• All deprecated *Styles props are removed. Use the corresponding *Props instead. The reason behind this change is added flexibility, since *Props accepts a larger set of of properties (onClick, role and tabIndex to give a few examples) compared to *Styles.

- wrapperStyles={ color: "red" }
+ wrapperProps={ style: { color: "red" } }

- labelStyles={ color: "red" }
+ labelProps={ style: { color: "red" } }

- dropdownStyles={ color: "red" }
+ dropdownProps={ style: { color: "red" } }

- optionStyles={ color: "red" }
+ optionProps={ style: { color: "red" } }

- innerWrapperStyles={ color: "red" }
+ innerWrapperProps={ style: { color: "red" } }

- overlayStyles={ color: "red" }
+ overlayProps={ style: { color: "red" } }

• The deprecated <PrimaryCard> and <SecondaryCard> components are removed. Use <Card> instead.
  The reason behind this change is that there were a lot of confusion around when to use <PrimaryCard> and when to you <SecondaryCard>, as well as what the difference between them except the background color was. For these reasons, the component was simplified in the design system, and the <Card> component is reflecting those updates.

- <PrimaryCard>Card content</PrimaryCard>
+ <Card>Card content</Card>

- <SecondaryCard>Card content</SecondaryCard>
+ <Card background="secondary">Card content</Card>

• The checked change handler for <Checkbox> and <Radio> are renamed from onChange to onCheckedChange and takes a boolean instead of an event. The reason is to simplify API and align with <Switch>.

const [checkboxChecked, setCheckboxChecked] = useState(false)
const [radioChecked, setRadioChecked] = useState(false)

// v6
return (
  <>
    <Checkbox checked={checkboxChecked} onChange={(e) => setCheckboxChecked(e.target.checked)} />
    <Radio checked={radioChecked} onChange={(e) => setRadioChecked(e.target.checked)} />
  </>
)


// v7
return (
  <>
    <Checkbox checked={checkboxChecked} onCheckedChange={setCheckboxChecked} />
    <Radio checked={radioChecked} onCheckedChange={setRadioChecked} />
  </>
)