Contributing to the design

Consistent design of components ensures a great user experience across services. You can contribute to HDS design library by proposing new components or additional features and fixes to existing ones. HDS design versions are managed in City of Helsinki Figma, in a project file called HDS Design kit.

The design assets are also available as a design kit package which is downloadable from the official HDS repository releases.

Proposing a design

You can contact HDS team directly if you have an idea for a feature, or alternatively here are two ways of proposing new designs to be added to HDS.

1. Propose design in Figma

If you have access to the City of Helsinki organisation and Helsinki Design System library in Figma follow these steps:

1. Create a file inside a team under City of Helsinki organisation. File name should follow naming convention Feature request: [Component name]. If a related Jira ticket exists, add the number of the ticket at the start of the file name (for example HDS-123 Feature request: Multiselect custom theme).
2. Add designs related to your proposal on the file. If a suitable component does not exist yet, you can create a new component named and structured according to Guidelines for HDS Design kit
3. When the design is done, make sure you have a description of what changes were made, how should your component be used, and where (give an example layout if possible).
4. Notify HDS team of the feature request with links to your design file. They will provide feedback and suggest changes if needed.

2. Creating an issue to the GitHub repository

If you do not have access to the City of Helsinki Figma and HDS Design kit, you can create an issue in HDS GitHub repository.

• Use the component name as the issue name and label it as feature-request.
• When writing the issue, follow the "What & why" issue template. Be specific.
• You may attach a Figma file containing the designs to the issue. You can also attach reference screenshots to illustrate your proposal better.

Guidelines for HDS Design kit

Here are some guidelines and tips that help us keep HDS library content consistent, and easy to use for all.

Component naming practices

• Naming language is British English (except for colour names that follow the brand guidelines). e.g Header

• Naming should be consistent in design, implementation, and documentation.

• [TBC] Old versions of items that are going to be replaced in the future but are still supported, are named xx_Deprecated.

Sub-components

• Names of sub-components that you use as building blocks of more complex components should begin with a period (.), indicating that they won’t be published in the asset library and appear in the bottom of the menu in the main file. Also a period is used between the main component name and sub-component name. e.g .Header.Actionbar
  • Any related subsequent sub-components are added the same way. e.g .Header.Actionbar.Actionitem

Variant properties

• The basic type of the component can be named Default
• Size variants are named with T-shirt sizes S, M, L, XL, 2XL…).
  • Don’t use Default/Basic as a size name
• Colour theme variants are named Light and Dark
• Breakpoints are always named in the same way:
  • XXL Desktop (≥ 1440)
  • XL Desktop (≥ 1248)
  • L Desktop (≥ 992)
  • M Tablet (≥ 768)
  • S Mobile (≥ 576)
  • XS Mobile (≥ 320)

Quality assurance checklist

HDS team uses a design review checklist you can find on Confluence. Using it as a guide you can check your design as you go. Below are some best practices.

Styles

• Use the design kit’s built-in styles in components
  • Text layers are styled with HDS typography text styles.
  • Fills and strokes are styled with HDS color styles.
  • Avoid using local styles. All styles used in HDS components should be found in HDS style library.
  • Respect the shared styles. Don’t customise or break the linking to the original style. This can cause trouble if shared styles are updated later on.
  • If the style you need is missing from shared styles propose adding a shared style to the HDS style library.

Layout and autolayout

• Align elements and frames to pixel grid
• Use HDS Spacing values for margins and paddings
  • Use Spacing tokens for the component's internal spacing.
  • Use Layout tokens for margins between elements in the layout.

Layers and groups

• Give layers and groups names that state their purpose or content
  • Avoid automatically generated names like Copy, Group …
• Group layers that belong together
• Delete hidden layers or groups
• Delete empty groups
• Ungroup unnecessary groups
  • Groups should have at least two items in them.
  • Avoid groups that have only one another group in them.
• Use Simplify all instances on component level