Typography
Typography tokens are used to define typographic style of headings, body text and HDS components.
Typography can be used to organise information and help users find their way around our services. For example using heading levels in a clear and consistent way helps users to understand the hierarchy and structure of the page.
Typography is also an essential part of the City of Helsinki 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 or 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 is 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 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 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 scale, custom scales can be also used.
| Token size | px value | rem value | Default heading scale | Small heading scale |
|---|---|---|---|---|
| Branding and user interface of most services. | Information heavy layouts and admin interfaces. | |||
| Heading XL | 52 px | 3.25 | Heading h1 | |
| Heading L | 36 px | 2.25 | Heading h2 | Heading h1 |
| Heading M | 24 px | 1.5 | Heading h3 | Heading h2 |
| Heading S | 20 px | 1.25 | Heading h4 | Heading h3 |
| Heading XS | 18 px | 1.125 | Heading h5 | Heading h4 |
| Heading XXS | 16 px | 1 | Heading h5 |
Body text sizes
Body font size tokens allow more subtle variations of body text sizes for improved content hierarchy and legibility.
| Token size | px value | rem value | Usage |
|---|---|---|---|
| Body XL | 20 px | 1.25 | Emphasising short introductory texts and other subtitles. |
| Body L | 18 px | 1.125 | Improving legibility of essential components, e.g. Text input and other form fields. Can also be used as the default body text size if the layout is not text heavy. |
| Body M | 16 px | 1 | Body text default. |
| Body S | 14 px | 0.875 | Conserving 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 smaller Body M (16 px) token for mobile breakpoints breakpoint-s and breakpoint-xs.
Line height
Line height tokens can be used to control spacing between lines of text. The tokens define the ratio between line height and element font size.
| Token size | Ratio | Usage |
|---|---|---|
| Line height S | 1 | Buttons, navigation and other UI components. |
| Line height M | 1.2 | Headings, lead texts and short paragraphs (no longer than 2-3 sentences). |
| Line height L | 1.5 | Body text default. Optimal for longer text content and extended reading. |
| Line height XL | 1.75 | Smaller text sizes or if you need to emphasise text (i.e. quotes). |
Font weights
HDS typography uses three font weights.
| Weight | css value | Usage |
|---|---|---|
| Regular | 400 | Body text default. |
| Medium | 500 | Used for labels in components e.g. Button and form components. |
| Bold | 700 | Heading default. Used to emphasise body text. |
Tokens
| CSS | SASS | value | Example |
|---|---|---|---|
| --font-default | $font-default | HelsinkiGrotesk | |
| --fontsize-heading-xl | $fontsize-heading-xl | 3.25 rem | Aa |
| --fontsize-heading-l | $fontsize-heading-l | 2.25 rem | Aa |
| --fontsize-heading-m | $fontsize-heading-m | 1.5 rem | Aa |
| --fontsize-heading-s | $fontsize-heading-s | 1.25 rem | Aa |
| --fontsize-heading-xs | $fontsize-heading-xs | 1.125 rem | Aa |
| --fontsize-heading-xxs | $fontsize-heading-xxs | 1 rem | Aa |
| --fontsize-body-s | $fontsize-body-s | 0.875 rem | Aa |
| --fontsize-body-m | $fontsize-body-m | 1 rem | Aa |
| --fontsize-body-l | $fontsize-body-l | 1.125 rem | Aa |
| --fontsize-body-xl | $fontsize-body-xl | 1.25 rem | Aa |
| --lineheight-s | $lineheight-s | 1 | |
| --lineheight-m | $lineheight-m | 1.2 | |
| --lineheight-l | $lineheight-l | 1.5 | |
| --lineheight-xl | $lineheight-xl | 1.75 |