Sizes in code

September 11, 2025

HTML data attributes and css custom properties (variables) can be used to define the size mode of a component. This works for all components and regular HTML elements, with a few exceptions noted below.

The size mode affects our size variables (--ds-size-*) and font-size variables (--ds-font-size-* and --ds-*-font-size-*).

Setting size mode with `data-size`

This data attribute is used to change the size mode, which affects the element itself and all descendant elements. We support three size modes out of the box: sm, md and lg. By default, md will be used.

<body>  <div>    <!-- The md size mode is used by default -->  </div>
  <div data-size="sm">    <!-- This element will use the sm size mode -->    <!-- Descendants will also use the sm size mode -->  </div></body>

Setting size mode with css custom properties

Instead of setting a specific size mode in the markup, you can set the css custom property --ds-size. The advantage of this is it allows you to set the size mode based on a media query or container query.

This is done by defining --ds-size: var(--ds-size--<mode>) where <mode> is either sm, md or lg. Note that for an element to be affected, the data-size attribute also needs to be set, but it can be blank or set to anything other than "sm", "md" or "lg".

Example: Adding an "auto" size mode

[data-size="auto"] {  --ds-size: var(--ds-size--sm);
  @media (min-width: 600px) {    --ds-size: var(--ds-size--md);  }  @media (min-width: 992px) {    --ds-size: var(--ds-size--lg);  }}

<body data-size="auto">  <div data-size="sm">    <!-- This element will use the sm size mode -->    <!-- Descendants will also use the sm size mode -->  </div>  <!--    Descendants of <body> without an explicit data-size attribute    will now use sm, md or lg based on the viewport width  --></body>

Exceptions

For certain components, data-size doesn't set the size mode, but instead only sets the component size. This is the case for

Avatar
Heading
Paragraph
Spinner

These components support other sizes, such as xs and xl. Refer to the component's documentation to see exactly which sizes are supported.

They are still affected by the surrounding size mode, e.g. in this example the first paragraph will be smaller than the second:

<div data-size="sm">  <Paragraph data-size="xs">Lorem ipsum</Paragraph></div><div data-size="md">  <Paragraph data-size="xs">Lorem ipsum</Paragraph></div>

It is confusing that data-size means size mode in certain contexts, and component size in other contexts. This will likely be remedied in the next major version as a breaking change.

Defining custom size modes

Under the hood, our variables change based on the local value of --ds-size-mode-font-size, and use rem for scaling based on the user's browser settings. data-size="<mode>" and --ds-size: var(--ds-size--<mode>) work by setting --ds-size-mode-font-size to values which correspond to the same size modes in Figma, but you can also set this variable directly for custom sizing.

Note that for an element to be affected, the data-size attribute also needs to be set, but it can be blank or set to anything other than "sm", "md" or "lg".

.example {  --ds-size-mode-font-size: 0.9;}[data-size="giant"] {  --ds-size-mode-font-size: 1.5;}

<body>  <div>    <!-- The md size mode is used by default -->  </div>
  <div data-size class="example">    <!--      This element and descenants will use 0.9 as a scaling factor,      as defined by the .example class    -->  </div>
  <div data-size="giant">    <!--      This element and descenants will use the custom size mode "giant",      with 1.5 as the scaling factor    -->  </div></body>

Edit this page on github.com (opens in a new tab)

Sizes in code

Setting size mode with data-size

Setting size mode with css custom properties

Exceptions

Defining custom size modes

Setting size mode with `data-size`