iTwinUI variables v1 migration guide - iTwin/iTwinUI GitHub Wiki
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:
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
.