Typography

Stable

Typography tokens are used to define typographic style of headings, body text, and HDS components.

Usage

Typography can be used to organise information and help users find their way around our services. For example, using heading levels clearly and consistently helps users to understand the hierarchy and structure of the page.

Typography is also an essential part of the City of Helsinki's brand identity. Helsinki Design system typography is based on the proprietary Helsinki Grotesk typeface. Preferably, no other typefaces should be used. The font licenses can be purchased from the Camelot Typefaces website.

Principles

  • Use black (--color-black-90) or white (--color-white) text colour depending on the background. Other text colours should be used intentionally, if at all.
  • Use typography consistently throughout your service, to ensure that the content hierarchy and structure are clear and easily understandable.
  • Use heading levels semantically. For example after h1, next heading on the same page should be h2, not h3. If needed, the appearance and visual hierarchy of headings can be altered separately from the semantic structure with the font size tokens.

Accessibility

  • Always check that sufficient colour contrast between text and its background is maintained. All colour choices should comply with WCAG 2.1 Standard at AA Level contrast ratios.
  • Avoid placing text over images, especially in small sizes.

Usage

The HDS offers two different sets of font size tokens for heading and body text. The tokens define the font size in rem values.

Heading sizes

The heading font size tokens are heading level agnostic. This allows you to fit the heading scale to the specific needs of the service. In addition to predefined default and small heading scales, custom scales can be also used.

You can use helper classes provided in the Core package to match each heading size with the correct line height and letter spacing.

Table 1: Heading sizes
Heading sizePX valueREM valueExample
Heading XXL64px4rem
Heading XXL
Heading XL48px3rem
Heading XL
Heading XL Mobile40px2.5rem
Heading XXL Mobile
Heading L32px2rem
Heading L
Heading M24px1.5rem
Heading M
Heading S20px1.25rem
Heading S
Heading XS18px1.125rem
Heading XS
Heading XXS16px1rem
Heading XSS

Heading scales

The heading font size tokens allow two different heading scales to be used. The default heading scale is suitable for desktop screen sizes. The small heading scale is used on mobile devices and it can be also used on information-heavy user interfaces (e.g. admin panels).

Table 2: Heading scales
Heading levelDefault scaleSmall scale
Heading 1 (h1)
Heading XXL (64px)
Heading XL-Mobile (40px)
Heading 2 (h2)
Heading XL (48px)
Heading L (32px)
Heading 3 (h3)
Heading L (32px)
Heading M (24px)
Heading 4 (h4)
Heading M (24px)
Heading S (20px)
Heading 5 (h5)
Heading S (20px)
Heading XS (18px)
Heading 6 (h6)
Heading XS (18px)
Heading XXS (16px)

Body text sizes

Body font size tokens allow more subtle variations of body text sizes for improved content hierarchy and legibility.

Table 3: Body text sizes
Heading sizePX valueREM valueUsage
Body XL20 px1.25Emphasising short introductory texts and other subtitles.
Body L18 px1.125Body text default for desktop screens. Improving legibility of essential components, e.g. Text input and other form fields.
Body M16 px1Body text default for mobile screens. Can also be used on text-heavy user interfaces as the default desktop body text size.
Body S14 px0.875Conserving space in data-heavy layouts and small components, e.g. Status label.

When choosing the body text size, start with the default Body M (16 px) token. It is a good starting point for most text-heavy user interfaces. This is also the minimum for the body text size in Helsinki services. This body text size can be used on all screen sizes.

The smaller Body S (14px) token should only be used in secondary text content and inside components.

If your service is not text-heavy, you can experiment with using the Body L, 18px token as the default body text size. In this case, it is recommended to use a smaller Body M (16 px) token for mobile breakpoints breakpoint-s and breakpoint-xs.

Line height

Line height tokens can be used to control the spacing between lines of text. The tokens define the ratio between line height and element font size. Note that HDS heading and text tokens use their line-height values to ensure line-height applies to 4 point grid. You can use helper classes provided in the Core package to match each heading and body text style with the correct line-height.

Table 4: Line height sizes
Line height sizeRatioUsage
Line height S1Buttons, navigation, and other UI components.
Line height M1.2Lead texts and short paragraphs (no longer than 2-3 sentences).
Line height L1.5Optimal for longer text content and extended reading.
Line height XL1.75Smaller text sizes or if you need to emphasise text (i.e. quotes).

Font weights

HDS typography uses three font weights.

Table 5: Font weights
Weight nameCSS font-weightUsage
Regular400Body text default.
Medium500Used for labels in components e.g. Button and form components.
Bold700Used to emphasise text.