Helsinki Design System
Helsinki Design System
Getting started
Visual assets
Design tokens
ResourcesContributingBefore contributingDesignImplementationDocumentation


You can contribute content in different ways to HDS. This section gives you all the information needed to get started.

Before contributing

Note that everything added to HDS has to have design, implementation and documentation. You may contribute only part of these but please note that HDS team has to implement all three parts before the feature can be released.

Before you start contributing to HDS, please refer to following guidelines.

Tools needed

Depending on the feature you want to be working on, you will need access at least some of these tools:

  • Sketch
  • City of Helsinki Abstract
  • City of Helsinki Slack (channel #designsystem)
  • HDS GitHub repository

Process of adding new components

How to contribute to Helsinki Design System

Answer the following three questions to find out whether you should propose a new component.

1. Does it already exist?

Before you start working or proposing a new component, it is important to check whether it already exists in HDS or in our roadmap.

  • First, check if it exists in HDS components.
  • Second, check if it exists on HDS roadmap.
  • Third, check if someone else has already proposed it in GitHub issues.

2. If not, how easily could a existing component be altered to fulfill new requirements?

Go through the list of existing HDS components. See if some of the components could be slightly altered to suit your needs while still fulfilling existing requirements. If yes, move on to making a proposal for the change.

3. If not, is this component something that is needed in several projects?

Think outside of the scope of your project. Can this component be utilized in other projects as well? If not, could you make it something more generic to match needs of other projects? Discuss with other projects and community.


HDS design versions are managed in City of Helsinki Abstract, in a project called Helsinki Design System. The design assets are also available as a kit which is downloadable from the official HDS repository releases.

There are two ways of proposing new designs to be added to HDS.

Opening a new branch to Abstract repository

If you have an access to City of Helsinki Abstract and HDS repository, you can

  • Create branch from Master branch. Branch name should follow naming convention [Your name] - [Component name], for example "John Doe - Dropdown"
  • Add all sufficient designs related to your proposals to their own file named HDS [Component name], for example "HDS Dropdown".
  • When done, make a commit, along with a description of what changes were made, your component, how should your component be used and where (give an example layout if possible).
  • Last, submit branch for review and add both Roni Jaakkola and Eemeli Nieminen as reviewers. They will provide feedback and suggest changes if needed.

Do not merge your branch to Master. HDS team will do it if the feature is accepted.

Creating an issue to GitHub repository

If you do not have an access to City of Helsinki Abstract and HDS repository, you can

  • Create an issue in HDS GitHub repository. Use the component name as issue name and label it as "feature-request".
  • In issue body, follow "What & why" issue template when writing the issue. Be specific.
  • You may attach a Sketch file containing the designs to the issue. You can also attach reference screenshots to illustrate your proposal better.

Guidelines for design

Coming soon!


When contributing for implementation, create pull request to HDS GitHub repository.

Guidelines for implementation

Coming soon!


When contributing for documentation, there are a couple of ways of doing it

Editing pages directly in GitHub website

The easiest way to edit a page is with the Edit this page on Github link that appears at the bottom of every page on the site. The link opens the specific Github page where you can edit the content and propose the change with a pull request.

Forking repository and setting up local environment

If you are planning regular or more comprehensive content updates, you will want to fork the repository and install some of the tools we use to build the website. This will create an easier workflow for you long term. Follow README in documentation site package to get you started setting up local development environment.

Guidelines for writing documentation

Coming soon!