Design system

Contribute

Add to the components or patterns in the design system

The design system is a shared resource for product teams to use and contribute to. We encourage everyone, regardless of their role, to help improve the design system.

Start by using what's in the design system

View the full governance process in Figma

There are open contribution files in Figma for every component and pattern in the design system, including unpublished ideas and experiments.

Design contribution process

If a component or pattern doesn’t exist in production or doesn’t meet the needs of your users, please contact the design system team. We’ll discuss the issue to understand it better and decide on the next steps together.

1. Come talk to us:

#design-system-support on slack

Be prepared to:

Describe the component or pattern and its purpose
Explain your user and service goals
Share any options and iterations that were explored with and without the Design System

Contribution criteria

2. Your contribution will be evaluated against the following contribution criteria:

Proposing a component or pattern

For something to be added or changed in the design system, it needs to be:

Criteria	Description
Useful	There is evidence that this component or pattern would be useful for many teams or services. Evidence could be screenshots or links to versions of it being used in different services.
Unique	It does not replicate something already in the Design System. If it’s intended to replace an existing component or pattern, there is evidence to show that it’s better than the existing version.

Standards for a given solution

For a new component or pattern to be published, a given solution has to be:

Criteria	Description
Usable	It creates a better and more accessible, usable, and simple experience for the user. The user has a greater understanding and useful control of what they are doing. It should be informed by research to show that it improves user experience and is responding to a user need.
Universal	It is inclusive and accessible. It should meet or exceed accessible standards. WCAG 2.1 AA is the minimum standard.

3. Once approved, it will be added to the Design System's backlog

When work starts, we will collaborate with you and your team to ensure the component meets your specific needs.

4. Contribute code to the component or pattern

To help build or contribute code to the component or pattern in the design system, follow the code contribution process below.

Code contribution process

In order to support all of the development frameworks that service teams use, we build and support a library of web components. Contributing entire components can be challenging and time-consuming, so we recommend and encourage smaller-scale contributions instead.

Recommended ways to contribute:

bug fixes
documentation updates
enhancements to existing components

Start by reaching out on the #design-system-support channel on slack to let us know you’re interested in contributing.
Find an issue in our backlog tagged with “ready-for-contribution”. Let us know which issue(s) you’re picking up.Since our repository is “public”, you'll need to use a different GitHub account than the Enterprise Managed User (EMU) account you use for your product team work.

Setup contribution environment

Go to ui-components repo and clone the repo
Open the repo’s folder in your IDE
Create a branch to work on with the name "contributions/story-number"
Run the following command:
Run the bash script:
The commands above will install all necessary packages and create a “playground” folder containing both React and Angular environments. Since nothing in this folder is committed to the repository, you can freely make any changes you want. These environments are designed for testing purposes.
Use the following commands to run your playground environments:
Angular
React

React and Angular wrappers

React wrappers

Each folder represents a single component with its associated unit tests and wrapper code

Angular wrappers

Each folder represents a single component with its associated unit tests and wrapper code

Web Components

Each folder represents a single component with:

Unit tests as *.spec.ts
Component code as *.ts

Testing procedures

All unit tests must be written in Svelte.

If you're updating/modifying React and/or Angular wrappers, you will need to write unit tests in React and/or Angular
It would also be recommended to add proper browser testing using jest for React wrappers and Svelte components.
Manually test in React and Angular

Additionally, one of our developers will manually test the PR to ensure the components' quality and functionality.

Submitting your code

Submit a commit using the following as your commit message:
Bug Fix:
fix(#storyNumber): short description of issue fixed (7 words max)
Feature Request:
feat(#storyNumber): short description of feature (7 words max)
Create a pull request to the alpha branch from your branch
Mark the PR as a draft

Join design system drop in hours to get feedback on your service, propose new components or patterns, suggest changes to existing resources, ask questions, and give feedback to the design system. These sessions are for Government of Alberta product teams.
Book time in drop in hours