Units

An overview of units in the App UI Kit.

Canva's user interface is laid out on a grid. This grid is made up of square cells, with each cell having a width and height of 8 pixels. This value of 8 pixels is known as the base unit.

By aligning interface elements to this grid, apps can maintain a level of visual consistency that is pleasing to the eye. It's not enough for apps to only conform to the grid, but it is a fundamental building block.

To help apps conform to the grid, most size and spacing values in the App UI Kit – widths, heights, margins, etc — are multiples of the base unit. This simple math ensures that interface elements line up as expected.

What are units?

When a value is a multiple of the base unit, it's known as a unit. This is abbreviated as u. You can therefore think of the following values as synonymous:

8 pixels
1 unit
1u

We use units instead of hard-coded pixel values to ensure that, even if the size of the base unit were to change, the apps would continue to conform to the grid. It also makes it easier to reason about relative sizing, as "2u" is twice the "1u", and so on, which reduces the need for mental math when laying out components.

Using the base unit

Generally speaking, apps don't need to use the base unit directly. The number is used to calculate the values of tokens in the spacing scale and apps should typically use those tokens when setting sizes and spaces.

If, however, you want to conform to the grid while using a value that isn't available in the spacing scale, you can access the base unit as a CSS or JavaScript variable and calculate the value yourself.

CSS

.container {
  padding: calc(var(--ui-kit-base-unit) * 10);
}

css

JavaScript

import { tokens } from "@canva/app-ui-kit";

const style = {
  padding: `calc(${tokens.baseUnit} * 10)`,
};

Exceptions

There are times where it doesn't make sense to conform to the grid, such as when rendering a raster image that has a fixed width and height. In these cases, ignore the grid. It's there as a tool, not a barrier.