Guidance
Using the Commonwealth Design System
The components, patterns, and styles Commonwealth services share, and when it is right to build something that is not in the system.
Why a shared design system
A person completing three different public services in a week should not have to learn three different date inputs. Consistency is not an aesthetic preference here; it is the reason someone succeeds first time.
The system's components have been tested with assistive technology and with people who find services difficult. Rebuilding one of them means repeating that testing yourself.
Using components
Take components as they are. Changing the visual design of a shared component costs your service the accumulated research behind it and costs everyone else the consistency.
You can change the content in a component freely — labels, hint text, and error messages should be written for your service, not copied from the examples.
When to build something new
Sometimes the system does not cover what your service needs. That is expected, and it is how the system grows.
Build it, test it with the people who will use it, then propose it. Patterns proposed with research behind them are usually accepted; patterns proposed because a team preferred them are not.
- Check whether another service has already solved it
- Build the simplest version that works
- Test it with at least five people, including assistive technology users
- Propose it to the design system team with your findings
Related guidance
Meeting accessibility requirements
What a Commonwealth public service must do to be usable by disabled people, how it is tested, and what to publish when something is not yet fixed.
Writing for public services
How to write service content people understand first time, including the Commonwealth's rules on terminology, tone, and reading level.
Services this guidance applies to
Commonwealth Hosting
Run a public service on shared, monitored infrastructure that already meets the Commonwealth's security and availability requirements.
Commonwealth Notify
Send emails, text messages, and printed letters from your service without building or contracting your own messaging system.