How to migrate to HDS 2.0?

Here you will find some useful information to make your transition to HDS 2.0 as smooth as possible.

Reading this article will help you understand what you should consider and take into account when you migrate your project to the HDS 2.0. If you are looking for a general overview of changes in version 2.0, please refer to our What is HDS 2.0 page.

Developers

A summary for developers
  1. Check components that had their API slightly changed (Accordion, Link, and Table)
  2. Get familiar with updated typography tokens
  3. Check your tests to see if any of the visual changes have caused them to break
  4. Learn about new content width changes

Before updating, we recommend to take a look at the What is HDS 2.0 page and the official 2.0 changelog. Pay extra attention to the "Breaking changes" section of the changelog. This helps you to get an understanding of what has been changed and what kind of effects updating may have in the implementation.

Start the migration process by updating your project's libraries to the newest HDS version. After this, keep reading below to get familiar with all major changes and how you may need to react to those.

Changes to component APIs

There are only a few breaking API changes in the HDS 2.0.

First, we have removed two (2) theme properties. These variables are not available for customisation anymore.

Table 1: Removed theme variables
ComponentRemoved theme variable
Accordion--button-border-color-hover
Table--background-color

Secondly, there has been one change to a React component's API. The default value of the Link component's property size has been changed from S to M. If you have used the Link component with the old default size (small), from now on you need to specify that explicitly by using the property size="S".

Updated typography tokens

HDS typography tokens have been changed to match the new Hel.fi visual identity. The following font size tokens have been changed:

Table 2: Changed typography tokens
TokenOld font-size valueNew font-size value
--fontsize-heading-xl52px (3.25rem)48px (3.0rem)
--fontsize-heading-l36px (2.25rem)32px (2.0rem)

We have also added two (2) new font size tokens; --fontsize-heading-xxl (64px) and --fontsize-heading-xl-mobile (40px). The --fontsize-heading-xxl token is meant to be used as the size of a heading level 1. The --fontsize-heading-xl-mobile is meant to be used as the size of a heading level 1 on mobile screens and information-heavy user interfaces.

To learn more about the typography usage, please refer to the Typography design token documentation page.

Visual changes to components

Due to the typography change, most of the components have gotten minor visual changes. While these changes are very small, it is good to note that the changes may break your project's regression tests.

The following components have had slight visual changes due to the updated typography tokens:

Content width changes

The container width tokens from xs to l size have been deprecated. From now on, the only container with token used is the --container-width-xl that defined the maximum width of the content area. Below this width, the content area now scales according to the screen size and margins will stay the same.

Please refer to the Breakpoint token documentation page to learn more. Also check out the HDS Container component which makes it easy to follow breakpoint and container width tokens.

Designers

A summary for designers
  1. Get familiar with the visual changes by reading the 2.0 release posts
  2. Update to the newest HDS libraries in each of your project's Sketch files
  3. Adapt your typography elements to the new style
  4. Change your screens to align with the new content width values

Before updating, we recommend to take a look at the What is HDS 2.0 page and the official 2.0 changelog. This helps you to get an understanding of what has been changed and what kind of effects updating may have on your design files.

Updating the HDS Sketch libraries

The newest stable HDS version is always available as an Abstract shared library. If you have already included HDS Sketch libraries in your project, all you need to do is to go to each Sketch file of your project and update libraries to the newest version. If you need help with this process, please refer to our Abstract tutorial page.

Updated typographies

Note that because typography styles have changed, most of the components will get minor visual changes when you update libraries. After updating your libraries, it is a good time to check your project's typographies. To adapt them to new styles, you need to start using the new heading level 1 font sizes (64px and 40px respectively for desktop and mobile). To learn more about the typography usage, please refer to the Typography design token documentation page.

Updated content width

Now there is only one maximum value for the content width, 1200 pixels. In other breakpoints, the content container takes all available space while the outside margins stay unchanged. To update your screens to match the new guideline, please check margin values for each breakpoint in the Breakpoint token documentation page.