For developers

Using the design system

How you use the NSW Design System depends on your team's capabilities. We recommend using npm, but the system is also provided through a CDN and a downloadable starter kit containing the compiled assets.

Installing with NPM

Follow these steps to install the NSW Design System in your project.

The NSW Design System is now installed as a dependency of your project. Next, import styles and JavaScript into your project build.

Importing styles

The NSW Design System styles can be imported as a whole package, or you can install core styles and add components selectively.

All styles

To import all styles as a single package you need to add following snippet at the start of your main SCSS file:

Core and selected components

Our core library includes the design system's base theme, typography, mixins and helper functions. Once you imported it, you can take full advantage of our variables and helpers. To import core library you need to add following snippet at the start of your main SASS file:

Once you have installed the core library you can start importing components as you need it. To import individual components you need to add following snippets to your main SASS file under core libraries import:

Using the Tools barrel

The tools barrel gives you access to shared mixins and functions via a single, stable import path. It does not output CSS and it does not replace importing the core styles or any components you use. Keep importing settings, base, helpers and your chosen components as shown above; the tools barrel is purely Sass utilities for use inside your component styles.

The nsw.reflow mixin targets the WCAG Reflow benchmark of 320 CSS pixels for constrained viewports and 400% zoom states. It is separate from the standard $nsw-breakpoints scale and does not generate grid, offset or visibility utility classes. Use it only where a component needs a specific adjustment at the WCAG Reflow benchmark. See Reflow for guidance.

Performance note: Importing the tools barrel does not add unused CSS. Mixins and functions only generate CSS when you call them, and the module is parsed once per build.

Tip: Prefer the barrel for consistency. If a file needs exactly one tool and you want explicit coupling, you can import that file directly (for example, @use 'node_modules/nsw-design-system/src/global/scss/base/mixins' as mixins;).

Adding the fonts and the icons

In your main html document add this line of code inside the head tag. Make sure that it's placed before the NSW Design System styles import. Or install iconopen_in_new and fontopen_in_new from npm.

Another way is to import it in css:

Importing javascript into your project

Some NSW Design System components require javascript to provide advanced functionality. To ensure the page is ready for javascript to run, include the follow scripts tags at the end of the html document.

Depending on your project set up, you might wish to copy the file into your project from node_modules or add the reference to your build workflow.

Using JSDelivr CDN

You can add the files to your main html document

Download starter kit

Download the compiled design system assets, including HTML, CSS and JavaScript, from the latest release.

Download HTML starter kitdownload

Theming

The NSW Design System uses Sass and CSS variables to propagate theme settings through core styles and components.

Theming for developers

Configure Sass and CSS variables to implement and customise your product theme.

east

Browser support

The NSW Design System supports the two most recent versions of:

• Chrome
• Safari, including iOS Safari
• Microsoft Edge
• Firefox

Browsers that are no longer maintained by their vendor are not supported.

Getting updates

Watch the NSW Design System repository on GitHubopen_in_new to receive release notifications, and star it to bookmark the project and show your support.