A NSW Government website
Design System v3.16.1

Contribution criteria

The Design System belongs to you, not us.

We are just caretakers of the design system. To help us with the caretaking we need a few things from newly proposed component contributions. Our aim is to foster an inclusive atmosphere for all contributors to our projects. If you’re unsure about anything, just ask — or submit your issue or pull request anyway. The worst that can happen is we’ll politely ask you to change something.

We value and thank you for all your well-intentioned contributions.

Suggested components

To be considered for inclusion in the design system, components and patterns must be:

Criteria Description

Useful

It addresses a user need that’s shared by multiple services or products

We can't accept components that are for just one project or one specific use-case. If a component is going to be added into the system it must be designed with the intention of being reusable in a variety of circumstances by many teams or departments. We ask contributors to provide examples of the versatility of a proposed component or provide reference to community discussion about it's wider intended use.

Unique

It doesn't duplicate something which already exists in the design system, unless it's intended to replace it.

Components shouldn't duplicate the functionality of another component. We need to keep the system slim; the more components that are in the system, the harder it is to maintain and the possibility for code-bloat and technical debt is increased.

If a component is similar in function consider extending it rather than duplicating it.

Before publication

Before new components and patterns are published into the design system, the team of core contributors will review them to make sure that they are::

Criteria Description

Distinctly NSW

We would like NSW Government website users to feel like they are on a NSW Government website, to ensure this is the case all suggested components must be aligned to the distinctly NSW look and feel. Access the latest NSW Design System Figma UI kit.

Usable

It's been tested and shown to work with a representative sample of users, including those with disabilities.

We need to know that any new components are working as intended for the end-user.
Task-based testing for a specific component is preferred. But at a minimum components in the design system should be tested as part of a product or service and have been operating in a live or beta environment for a period of time before being integrated into the system.

Consistent

It uses existing styles and components in the design system where relevant.

Components that follow the system are much more themeable and reusable by other teams. New components must follow the system as closely as possible, particularly the specifics of colour, spacing, and typescale in ~/src/global/scss/settings/settings.scss.

Versatile

It can be easily applied in different contexts.

Responsive: All components should fill the width of their parent element. This is so that layouts aren't dictated by components, but rather components fit the required layouts.

Robust: Components should accommodate varied content and varied content lengths. For example, what happens with a navigation component that has more items than demonstrated?

Coded

Components are ready to merge in.

Code is for humans: Please look at our coding style and work with it, not against it. We add spacing, and prefer readable code over clever code. Yes, code is actually for computers, but it is humans that need to maintain it.

Code comments: Our stance on commenting code is that we encourage code to be cleanly and logically written to minimize the need to comment. Sensible and clear naming of functions and variables would also help readability without the need for excess comments.

Follow the folder structure: New components should follow the same folder structure as the existing components.

CSS can be dependent on other components, but must use core functions and mixins at a minimum.

  • For spacing, padding, or other metrics like border-width, reference ~/src/global/scss/helpers/_spacing.scss
  • For font-sizes and line-height, reference ~/src/global/scss/tools/_typograpghy.scss
  • For colours, reference ~/src/global/scss/settings/settings.scss.

JavaScript: The Design System vanilla JavaScript which gets transpiled to ES5. We would rather avoid using jquery if possible.

PS: Don't forget to remove your debugging! :)

Tested

It's been tested and shown to work with a range of browsers, assistive technologies and devices.

Accessibility: A component on its own must be accessible to WCAG 2.1 level AA. Some documentation on how this has been checked, tested, or decisions made to support accessibility should be supplied.

Browser and device tested: All components should meet our browser support requirements.

No JavaScript fallbacks: All components must degrade gracefully when JavaScript is disabled. We expect that a user can still complete their task without JavaScript enabled, it just might not be beautiful. For example, accordions default to 'open' when JavaScript is disabled so that users can still use the content.

Considered

Documentation and rationale have been provided. Include a high-level description for what the pattern is, and what it's for.

We aim to explain design and code decisions as openly as possible. Explanations about why decisions have been made help others understand the work involved but also help them understand the consequences of overriding.

Supporting evidence

When making a new component, we would be very grateful if you post the research, design decisions and use cases for the component. Accessibility considerations should be documented or sourced from the community forum before submitting a pull request.

This may be in the form of a code snippet, screenshots, sketch files or written text on your research with references. This gives a chance for members of the community to respond and share any work they may have done in the past on a similar component.

Community

The Digital NSW Community brings together like-minded digital creators to collaborate, share and leverage learnings to create better customer experiences.

We encourage you to ask questions, pose problems/solutions and share your work so we can grow the design system.

Attribution

This Contribution Guide is adapted from Contributing to Australian Government Design System Components.