Helsinki Design System: A unified digital identity for the city

Case: City of Helsinki

In the city of Helsinki, a significant transformation was underway as the city aimed to unify the appearance of its digital services and channels. Kodan helped the City of Helsinki build their award-winning Helsinki Design System.


The city of Helsinki faced a problem with its digital services: the lack of a unified design system meant that each service appeared different, leading to a confusing and disjointed user experience. This inconsistency not only made it difficult for residents to navigate these services, but also reflected poorly on the city's digital maturity. Simply put, the city’s digital services were disjointed in design, creating confusion among the city's residents and staff.

The city of Helsinki decided to develop its very own design system, Helsinki Design System (HDS), to address the issue. But what is a design system? A design system is a collection of reusable components, guidelines, and standards that help maintain consistency across digital services. It accelerates development time by providing pre-designed elements, allowing developers to focus on functionality rather than design details. Additionally, a design system improves collaboration between designers and developers, ensures a cohesive user experience, and simplifies updates and scalability.

Kodan joins the multi-vendor environment

Building the HDS was an in-house initiative driven by the city's own product owner, with initial thoughts and expertise coming directly from within. However, external designers and developers were brought in, creating a multi-vendor environment that fostered diverse insights and innovation. The team was also accompanied by an accessibility expert because accessibility was one of the main drivers of the development of the design system.

Kodan's lead developer, Mika Nevalainen, joined the project when the development of the design system had already been underway for almost a year. By this time, the building of the core of the component library, along with a website, documentation, and user interface resources, including design tokens, had already begun.

Mika Nevalainen gradually transitioned into the role of lead developer for the project. Alongside his software development duties, he also took on the role of mentoring the team and guiding new developers through the process.

Built with React

The HDS is structured in three layers: The first layer consists of design tokens that establish basic styling rules. The second layer includes static styles with CSS for simpler components, which can be used in building services outside of React environments. The third layer is a React component library that contains more complex components and user interface assemblies.

The React component library was developed using React and TypeScript, with Storybook for component previewing. SASS was used for styling, while the documentation site was built with Gatsby, emphasizing accessibility and ease of use. Gatsby was also selected because the team wanted the documentation page to use the Helsinki Design System components and no external components.

Testing was thorough, utilizing the Testing Library for both functional and visual regression tests to ensure that components remained functionally and visually consistent and of high quality.

Example user interface components from HDS web page

From design tools to live component library

The project began with creating components in various design tools, focusing on collaboration between designers and developers from the start. As the designs evolved, the team made sure they stayed in sync with the developed components. This back-and-forth process kept the design tool templates and live components aligned, maintaining accessibility standards throughout. Additionally, automation helped by using scripts and design tools' APIs to generate icons for the component library dynamically.

Documentation was a vital part of the project, crafted to be clear and consistent with the live design system. New components were initially released under a beta flag to gather internal feedback and ensure they met specific evaluation criteria before being considered stable. These criteria for stable components included factors such as maturity, developmental needs, and usage rate.

The quality of the HDS remained high across all facets, from branding to the component library, thanks to a team committed to excellence. Working together with a common goal and easily understandable success metrics—aimed at improving the digital experiences and lives of Helsinki’s residents—was key. Accessibility was also a core principle, ensuring the system was usable by everyone from the start.

Award-winning collaboration

The Helsinki Design System is more than just a set of digital tools; it is a testament to collaborative innovation, quality, and accessibility. Kodan's involvement in the HDS not only helped solve the initial problem of disjointed digital services but also set a new standard for public digital infrastructure. HDS has also been released under an open-source license, so anyone can utilize it and learn from it.

Through meticulous planning, execution, and an unwavering commitment to quality and accessibility, the HDS now serves as a beacon for other cities aiming to unify and enhance their digital services. And of course, the work still continues because, like any digital resource, the HDS needs to evolve to match the requirements of new services, end devices, usage contexts, and so on.

The Helsinki Design System won the "Best Design System'' award in the Grand One 2023. The jury particularly appreciated HDS’s ease of use, cohesion, and accessibility features.


Source for images: The Helsinki Design System page

Want to know more?

Our expertise is at your service. Whether you’re starting a new project or need assistance with an existing one, we’re here to help.

Say hello to get the ball rolling.