Contributing to the development

Ready made components are what make HDS tick. You can contribute to HDS React and Core libraries by proposing new implementations and bugfixes to existing components.

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

Guidelines for implementation

General guides

  • Do not merge the pull request after it is accepted. The HDS team will merge it. Merging the PR has a side-effect that will update the documentation site.
  • Remember to apply HDS Design tokens package when creating a component. Instead of specifying pixel values, colours, fonts, or breakpoints by yourself, apply those from design tokens instead
  • Take a look at Develop with Helsinki site for practical details for developing open source code for the City of Helsinki.

HDS Technologies

  • HDS React and HDS Core both apply the Storybook library
  • HDS React is built with Typescript and SASS
  • HDS Core is built with pure JS and CSS
  • HDS applies yarn as its dependency manager
  • HDS applies git for version control

Creating a new component

  • Apply the Scaffolding yarn script when creating a new component: Scaffolding

  • For simple components, create both versions, HDS Core and HDS React. Create common styles to HDS core that you can then import to HDS React like in this example. HDS React has HDS Core as its dependency.

  • Add ready components to rollup.config.js


  • Write unit tests for each component. Test rendering, accessibility, and possible functionality of the component. HDS applies Jest for unit testing. Example of unit tests can be found here: Number input unit tests
  • HDS applies Loki for visual regression testing. Loki is integrated with Storybook. Hence it's important to add a story for each different UI state of the component
  • It is a good idea to test the component independently in a fresh Create React App