Skip to main content

Contribution Guide

Adding to / updating the Design System​

If you have an idea for a component or style and feel it belongs in the design system, or you have an idea for how part of the Design System could be improved, we want to hear it!

We encourage you to start a thread in the #design-system channel on slack and @ the relevant engineering and design maintainers.

Design mockups or prototypes (code or design) are welcome to help discussion but are not required.

The Design System should create consistency, and reduce duplication of effort, and all work on the Design System should be in the spirit of this goal.

What makes a new style/component suitable for the Design System?​

New additions to the Design System will be considered if:

  • The addition or something similar are already being used in multiple products.
  • The addition is very likely to be used in multiple products in the near future.

What justifies changing a style/component in the Design System?​

Likely reasons to change part of the Design System would include:

  • Making a component/style more suitable across other products.
  • Adding functionality to an existing component/style.
  • Improving process or designer/engineer experience.

Development process​

If your addition or change has been agreed with design and engineering, please contribute via a pull request:

  1. Create an issue for the design system changes
  2. Create a branch based off the issue
  3. Make all relevant changes on your branch
  4. Update the Changelog
  5. Create a Pull request
  6. Post the Pull request into the #design-system slack channel for review

Creating issues​

Please create an issue for any work in the design system. There is a project board that helps us track what needs doing and what is currently being worked on. If you are undertaking design system work as part of your team's sprint work, please also add it to the Design System as one of the projects so we also have transparency on what is being worked on.

To create an issue:

  • Make sure you are adding the issue to the correct repo (core, react or rails)
  • Add the relevant type tag of documentation, build, or design
  • Add the relevant Implementation tag of docs, core, react, rails
  • Use the issue template if one is provided