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.