iTwinUI variables v1 migration guide

Semi-Automated Migration Tool 🤖

To help with the migration, we also provide a semi-automated migration tool that scans your project repo for old code and recommends replacements.

Download options:

• Clone iTwinUI-migration-tool GitHub repo (recommended)
• Download zip file (version: 24 Sep 2024) with the tool (for users outside the iTwin GitHub org)

---

This guide will help you migrate from the old Sass variables (previously in @itwin/itwinui-css v0) to the new CSS variables (@itwin/itwinui-variables v1 or v2).

Sass variables (in the format $iui-variable-name) have been replaced with CSS variables (in the format --iui-variable-name). Many of the variable names have been changed to better communicate their use. Additionally, some variables have been removed entirely, some new variables have been added, and some variables have significantly changed their usage and don't have one-to-one counterparts. Variables not mentioned have not changed names and only need to be converted from SASS to CSS.

You can see the changes made to iTwinUI-CSS recently at the iTwinUI-CSS v1 migration guide. You can see the changes made to iTwinUI-react recently for v2 at the iTwinUI-react v2 migration guide.

Notes for migrating:

• There is no need to explicitly import @itwin/itwinui-variables in every file that uses the variables. CSS variables only need to be included once per page, and this is done automatically by @itwin/itwinui-react, so in most cases you will be able to reference the variables directly. If you were previously importing Sass variables, you can remove that import now.

  - @import '@itwin/itwinui-css/scss/variables';

  // ⚠️ Caution! Don't do this in every file or it will cause unnecessary duplication.
  @import '@itwin/itwinui-variables';

• The primary color has been split into accent & informational. You must decide which makes the most sense:
  • Use accent when you want to use the brand color.
  • Use informational when you need to designate the status of informational.
• If SASS variables were being mathematically manipulated, their CSS counterparts will need to be surrounded by calc(...) to operate correctly. See more here.
• CSS variables need to be surrounded by var(...) to work. See more here.
• To combine a color with opacity, use the HSL variables like below. See more here.

  background-color: hsl( var(--iui-color-accent-hsl) / var(--iui-opacity-6) );

Theming

Background colors

Before	After
$iui-color-background-1	--iui-color-background
$iui-color-background-1-overlay	--iui-color-background-hover
$iui-color-background-2	--iui-color-background-backdrop
$iui-color-background-disabled	--iui-color-background-disabled
$iui-color-background-primary	--iui-color-background-accent or --iui-color-background-informational
$iui-color-background-primary-overlay	--iui-color-background-accent-hover or --iui-color-background-informational-hover
$iui-color-background-positive	--iui-color-background-positive
$iui-color-background-positive-overlay	--iui-color-background-positive-hover
$iui-color-background-warning	--iui-color-background-warning
$iui-color-background-warning-overlay	--iui-color-background-warning-hover
$iui-color-background-negative	--iui-color-background-negative
$iui-color-background-negative-overlay	--iui-color-background-negative-hover

New background colors

• --iui-color-background-backdrop-hover: hover state for $iui-color-background-backdrop.
• --iui-color-background-zebra: zebra striping for table rows, color is halfway between --iui-color-background & --iui-color-background-backdrop.
• --iui-color-background-accent-muted: a muted color of --iui-color-background-accent that --iui-color-text can safely be placed on.
• --iui-color-background-informational-muted: a muted color of --iui-color-background-informational that --iui-color-text can safely be placed on.
• --iui-color-background-positive-muted: a muted color of --iui-color-background-positive that --iui-color-text can safely be placed on.
• --iui-color-background-warning-muted: a muted color of --iui-color-background-warning that --iui-color-text can safely be placed on.
• --iui-color-background-negative-muted: a muted color of --iui-color-background-negative that --iui-color-text can safely be placed on.
• --iui-color-background-transparent-hover: used by borderless buttons for hover.

Removed background colors

• $iui-color-background-3: if you're using these as backgrounds, you should consider changing to use --iui-color-background.
• $iui-color-background-4: if you're using these as backgrounds, you should consider changing to use --iui-color-background.
• $iui-color-background-5: if you're using these as backgrounds, you should consider changing to use --iui-color-background.

Border colors

Before	After
$iui-color-background-4	--iui-color-border-subtle
$iui-color-background-5	--iui-color-border
$iui-color-background-border	--iui-color-border
$iui-color-foreground-primary	--iui-color-border-accent or --iui-color-border-informational
$iui-color-foreground-positive	--iui-color-border-positive
$iui-color-foreground-warning	--iui-color-border-warning
$iui-color-foreground-negative	--iui-color-border-negative

New border colors

• --iui-color-border-foreground: for input elements.
• --iui-color-border-foreground-hover: for input elements when hovered.
• --iui-color-border-disabled: for input elements when disabled.

Text colors

Before	After
$iui-text-color	--iui-color-text
$iui-text-color-muted	--iui-color-text-muted
$iui-text-color-placeholder	--iui-color-text-disabled
$iui-color-foreground-primary	--iui-color-text-accent or --iui-color-text-informational
$iui-color-foreground-primary-overlay	--iui-color-text-accent-hover or --iui-color-text-informational-hover
$iui-color-foreground-positive	--iui-color-text-positive
$iui-color-foreground-positive-overlay	--iui-color-text-positive-hover
$iui-color-foreground-warning	--iui-color-text-warning
$iui-color-foreground-warning-overlay	--iui-color-text-warning-hover
$iui-color-foreground-negative	--iui-color-text-negative
$iui-color-foreground-negative-overlay	--iui-color-text-negative-hover

New text colors

• --iui-color-text-hover: for --iui-color-text when hovered.

Icon colors

Before	After
$iui-icons-color	--iui-color-icon-muted
$iui-icons-color-actionable	--iui-color-icon
$iui-icons-color-actionable-hover	--iui-color-icon-hover
$iui-icons-color-actionable-disabled	--iui-color-icon-disabled
$iui-icons-color-primary	--iui-color-icon-accent or --iui-color-icon-informational
$iui-icons-color-positive	--iui-color-icon-positive
$iui-icons-color-warning	--iui-color-icon-warning
$iui-icons-color-negative	--iui-color-icon-negative

New icon colors

• --iui-color-icon-muted-hover: for --iui-color-icon-muted when hovered.

Foreground colors

Before	After
$iui-color-foreground-accessory	--iui-color-white

Removed foreground colors

• $iui-color-foreground-body-invert: no direct counterpart.

RGBA / HSL colors

Before	After
$iui-color-foreground-body-rgb	--iui-color-foreground-hsl
$iui-color-foreground-primary-rgb	--iui-color-accent-hsl or --iui-color-informational-hsl
$iui-color-foreground-positive-rgb	--iui-color-positive-hsl
$iui-color-foreground-warning-rgb	--iui-color-warning-hsl
$iui-color-foreground-negative-rgb	--iui-color-negative-hsl

New RGBA / HSL colors

• --iui-color-background-hsl: for when you need to use --iui-color-background with opacity.

Non-theming

Colors

Before	After
$iui-color-background-skyblue	--iui-color-background-skyblue
$iui-color-background-celery	--iui-color-background-celery
$iui-color-background-froly	--iui-color-background-froly
$iui-color-background-steelblue	--iui-color-background-steelblue
$iui-color-background-sunglow	--iui-color-background-sunglow
$iui-color-background-seabuckthorn	--iui-color-background-seabuckthorn
$iui-color-background-montecarlo	--iui-color-background-montecarlo
$iui-color-background-poloblue	--iui-color-background-poloblue
$iui-color-background-bouquet	--iui-color-background-bouquet
$iui-color-background-ash	--iui-color-background-ash
$iui-color-background-oak	--iui-color-background-oak

Removed colors

• $iui-color-dataviz-skyblue: please hardcode hsl(204 77% 67%).
• $iui-color-dataviz-celery: please hardcode hsl(72 51% 56%).
• $iui-color-dataviz-froly: please hardcode hsl(2 90% 70%).
• $iui-color-dataviz-steelblue: please hardcode hsl(200 41% 46%).
• $iui-color-dataviz-sunglow: please hardcode hsl(42 100% 60%).
• $iui-color-dataviz-seabuckthorn: please hardcode hsl(29 92% 61%).
• $iui-color-dataviz-montecarlo: please hardcode hsl(176 43% 62%).
• $iui-color-dataviz-poloblue: please hardcode hsl(211 44% 67%).
• $iui-color-dataviz-bouquet: please hardcode hsl(305 19% 55%).
• $iui-color-dataviz-ash: please hardcode hsl(42 15% 75%).
• $iui-color-dataviz-oak: please hardcode hsl(27 32% 49%).
• $iui-color-system-red: please hardcode red.
• $iui-color-system-burgundi: please hardcode maroon.
• $iui-color-system-orange: please hardcode orange.
• $iui-color-system-yellow: please hardcode yellow.
• $iui-color-system-green: please hardcode limegreen.
• $iui-color-system-cyan: please hardcode deepskyblue.
• $iui-color-system-blue: please hardcode blue.
• $iui-color-system-magenta: please hardcode mediumorchid.
• $iui-color-system-turquoise: please hardcode aquamarine.
• $iui-color-system-gray: please hardcode darkgray.

Elevation / Shadow

Before	After
$iui-elevation-0	--iui-shadow-0
$iui-elevation-2	--iui-shadow-1
$iui-elevation-4	--iui-shadow-2
$iui-elevation-8	--iui-shadow-3
$iui-elevation-16	--iui-shadow-4
$iui-elevation-24	--iui-shadow-5

Speed / Duration

Before	After
$iui-speed-instant	--iui-duration-0
$iui-speed-fast	--iui-duration-1
$iui-speed	--iui-duration-2
$iui-speed-slow	--iui-duration-3

Sizes

Before	After
$iui-xxs	--iui-size-3xs
$iui-xs	--iui-size-2xs
$iui-s	--iui-size-xs
$iui-sm	--iui-size-s
$iui-m	--iui-size-m
$iui-l	--iui-size-l
$iui-xl	--iui-size-xl
$iui-xxl	--iui-size-2xl
$iui-3xl	--iui-size-3xl

Border radius

Before	After
$iui-border-radius	--iui-border-radius-1
$iui-border-radius-round	--iui-border-radius-round

Component specific

Before	After
$iui-component-height	--iui-component-height
$iui-component-height-small	--iui-component-height-small
$iui-component-height-large	--iui-component-height-large
$iui-component-padding-horizontal	--iui-size-s

Removed component specific

• $iui-component-offset: no direct counterpart.
• $iui-component-padding-vertical-small: no direct counterpart.
• $iui-component-padding-vertical-large: no direct counterpart.

Blur

Removed blur

• $iui-blur-filter: no direct counterpart, please hardcode the previous value of blur(5px).

Font families

Before	After
$iui-font-family	--iui-font-sans
$iui-monospace	--iui-font-mono

Removed font families

• $iui-sans: was used as part of $iui-font-family, please use --iui-font-sans.
• $iui-sans-fallback: no direct counterpart.
• $iui-font-loaded-class: no direct counterpart.

Font sizes

Before	After
$iui-font-size-small	--iui-font-size-0
$iui-font-size	--iui-font-size-1
$iui-font-size-leading	--iui-font-size-2
$iui-font-size-subheading	--iui-font-size-3
$iui-font-size-title	--iui-font-size-4
$iui-font-size-headline	--iui-font-size-5

Font weights

Before	After
$iui-font-weight-light	--iui-font-weight-light
$iui-font-weight-normal	--iui-font-weight-normal
$iui-font-weight-semibold	--iui-font-weight-semibold
$iui-font-weight-bold	--iui-font-weight-bold

Font cap sizes

Removed font cap sizes

• $iui-cap-size: no direct counterpart.
• $iui-cap-size-small: no direct counterpart.
• $iui-cap-size-leading: no direct counterpart.
• $iui-cap-size-subheading: no direct counterpart.
• $iui-cap-size-title: no direct counterpart.
• $iui-cap-size-headline: no direct counterpart.

Line height

Removed line height

• $iui-baseline: the closest variable is --iui-size-s.
• $iui-line-height: the closest variable is --iui-size-l.