Variables

iTwinUI offers an extensive set of handcrafted CSS variables. If you’re using iTwinUI-react, these variables will be automatically included and imported into your application. If you want to use it standalone, you can manually npm install @itwin/itwinui-variables.

We strongly encourage the use iTwinUI’s CSS variables rather than hardcoding values. Many of the color values change depending on the theme or contrast settings. Because of this, we purposefully do not expose the variables’ values on this site. However, if you need a particular variable’s value, you can extrapolate it from the raw CSS file.

Border radius

Most iTwinUI components use var(--iui-border-radius-1). For pill-shaped components, iTwinUI also offers var(--iui-border-radius-round).

Color

iTwinUI supplies many different color variables, with each variable being specific to its own use case. All colors, if applied correctly, are guaranteed to meet WCAG AA in base themes and WCAG AAA in high contrast unless noted otherwise. All CSS variables are prefixed with --iui- followed by the category and ending with the value if applicable.

Example: --iui-color-background-backdrop

Background

There are several main background colors. These colors are used to build the backdrop of your website or application and are the most commonly used background colors.

• background: for surface elements placed over the body. This will be the most commonly used background color.
• background-hover: an element using background with a hover state.
• background-zebra: an element using background with zebra striping, present in table rows and tile thumbnail areas. This color is halfway between background-backdrop and background and should be used sparingly.
• background-disabled: an element using background with a disabled state.
• background-transparent-hover: an element using a transparent background with a hover state, present in borderless buttons.
• background-backdrop: the main body background. Most if not all content placed above this should use background.
• background-backdrop-hover: an element using background-backdrop with a hover state.

Sometimes you may need to use colors to help convey some sort of status. These status background colors require icons and text to use --iui-color-white to pass accessibility requirements. The available options are:

• accent: typically used for designating an active / on state. Uses the same color as informational, but can be changed by the development team to inject their own custom branding colors.
• informational
• positive
• warning
• negative

The muted status background color palette can be used to help convey some sort of status without using a strong color. It can also be used for normal text or icons above a main background color

The soft background colors can be used to categorize things that may not be associated with a status. These soft background colors do not meet accessibility requirements when paired with text or icons, so use sparingly.

Border

There are also a few special named colors for borders or dividing lines.

• border: a strong border color.
• border-subtle: a less-strong border color, typically used for divider lines.
• border-foreground: for input elements.
• border-foreground-hover: for input elements with a hover state.
• border-disabled: for elements with a disabled state.

You can also use border status colors in combination with status background colors and muted status background colors.

Color & opacity

If you need to use a color in combination with an opacity, we have provided HSL specific variables. Note that when pairing colors with opacity that you will need to verify you are meeting color contrast requirements.

• background-hsl
• foreground-hsl
• accent-hsl
• informational-hsl
• positive-hsl
• warning-hsl
• negative-hsl

These can be used like so:

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

Icon

Icon colors have been carefully selected to ensure you meet legal accessibility requirements. All of these icon colors ensure a passing score except when paired with status background colors and soft background colors.

• icon: an actionable icon color, such as an icon within a button.
• icon-hover: an icon using icon with a hover state.
• icon-disabled: the disabled icon color.
• icon-muted: typically used for a non-actionable icon but sometimes can be used for an actionable icon.
• icon-muted-hover: an icon using icon-muted with a hover state. This should be used sparingly.

Similarly, there are icon status colors.

Text

Text colors have been carefully selected to ensure you meet legal accessibility requirements. All of these text colors ensure a passing score except when paired with status background colors and soft background colors.

• text: the default text color.
• text-hover: text using text with a hover state.
• text-disabled: the disabled text color.
• text-muted: lighter colored text that is supplemental to text.

Similarly, there are text status colors and their hover states.

Duration

If you need to animate anything, use one of the supplied duration variables. The duration scale ranges from 0 to 3, where --iui-duration-0 has no duration and --iui-duration-3 is the slowest. For most hover or click interactions, we encourage using the fastest speed.

Try clicking on these buttons to play a small animation and get a sense of how quick each duration is.

Please use these variables in combination with the prefers-reduced-motion media feature for accessibility reasons.

Opacity

The opacity scale ranges from 1 to 6, where --iui-opacity-1 is fully opaque and --iui-opacity-6 is the most transparent, although not fully transparent.

Shadow

iTwinUI offers a few shadows that increase in elevation from 0 to 5. These variables are typically used in combination with the surface component.

Size

iTwinUI’s spacing scale follows t-shirt sizes as a naming convention, where m corresponds to 1rem. iTwinUI uses rem rather than px, a relative sizing unit that adjusts based off the root font size.

If you are creating an input component, we have 3 variables:

• --iui-component-height-small
• --iui-component-height
• --iui-component-height-large

Typography

iTwinUI uses Noto Sans for body text (--iui-font-sans) and Noto Sans Mono for monospace text (--iui-font-mono).

The font scale increases in size from 0 to 5, with --iui-font-size-1 being the base font size for body text.

There are four font weights available: light, normal, semibold, and bold.