vvornanen / helsinki-design-system

Components, principles, documentation and templates for the City of Helsinki design system.

Helsinki Design System

Design System for the City of Helsinki

Helsinki Design System (HDS) is an open-source design system built by the City of Helsinki. It consists of tools for development and design as well as resources and guidelines for creating user-friendly, accessible solutions for the city.

HDS documentation | Available components | React Storybook | Core Storybook | Contributing

---

Features

• Accessibility baked-in – All HDS components are from the ground up designed to be as accessible as possible. Components go through a third-party accessibility audit before release.
• React & CSS – Components are available both as React and CSS styles. Choose the one which suits the best for your project.
• Customizable – HDS components are designed to be customizable to allow expressing the vibrant Helsinki brand.
• Design and Implementation in sync – Designers use a collection of Sketch libraries which are perfectly in sync with the implementation.

Packages

HDS is divided into three (3) separate packages:

• – Helsinki City brand colors, typography and base styles as css-styles and variables
• – Provides HDS components implemented using React
• – Basis of the HDS which includes base colors, typography etc. as design tokens.

Getting started

🔧 Are you a developer? If yes, start by checking out HDS - For developers page.
🎨 Are you a designer? If yes, start by checking out HDS - For designers page.

Helsinki Design System uses Lerna for running scripts across the repo as well as versioning and creating releases of the packages. Yarn workspaces is used to manage dependencies. This allows the separate packages to reference each other via symlinks during local development.

Using the packages in your project

See the package specific instructions on how to get started using the packages.

• hds-design-tokens
• hds-core
• hds-react

Setting up local development environment

0. Download and Install git lfs which is used to store images outside repository.

git lfs install

1. Clone the HDS repository.

git clone https://github.com/City-of-Helsinki/helsinki-design-system.git

2. Go to the root of the project and install dependencies with yarn.

cd helsinki-design-system
yarn

3. Build packages with yarn build. This builds all packages; core, react, design-tokens and site (documentation).

yarn build

4. Start the development server. You can start these individually for each platform with yarn start:<platform>. For example, to start the React Storybook development environment, run:

yarn start:react

Commands

Command	Description
yarn	Installs dependencies and links local packages.
yarn build	Builds all the packages.
yarn build:<package>	Builds a specific package (tokens, core, react or site).
yarn start:<platform>	Starts the development environment for a specific platform (core or react).
lerna release	Publishes packages that have changed since the last release.

To ensure code quality in the repo, every package will have their pre-commit and pre-push scripts run automatically before git commit and push (added with Husky).

Roadmap

Helsinki Design System has a public roadmap. For the long-term Roadmap, please refer to HDS About - Roadmap page. If you are interested what the team is currently working on, refer to the Design System Roadmap in Github.

Contributing

Before contributing, it is recommended to read HDS Contribution - Before contributing page.

We are accepting new features, feature requests and help with improving the documentation. There are multiple ways you can contribute:

• Opening issues about bugs/improvements/new features/etc.
• Opening pull requests with changes/fixes/new features/etc.
• Opening branches in Abstract to propose new component designs or design changes. More information about design contribution can be found in HDS Contribution - Design page.
• Take part in discussion and commenting new HDS features. The easiest way to do this is to browse open issues and pull requests and leave a comment! If you have an access to the City of Helsinki Slack, you may also join the discussion there. More info about the ways to contact us can be found in HDS About - Support page.