View online documentation for the NSW Design System.
Welcome to the documentation for the NSW Design System, a frontend toolkit of styles, patterns, standards and guidance for everyone creating distinctly NSW digital products and services. It helps us create unified, trusted, inclusive and audience centered digital experiences for our users that are clearly simple, current and purposeful.
This document provides instructions on how to easily integrate and utilise the NSW Design System styles and components in your projects.
How you use the NSW Design System depends on your team's capabilities.
We recommend the following methods:
-
Clone the repo:
git clone https://github.com/digitalnsw/nsw-design-system.git -
Using npm Package Manager: This method provides a structured and customisable approach to integrating the design system into your project.
-
Using JSDelivr CDN: If you prefer a quicker setup, you can use the JSDelivr content delivery network to directly include the design system's CSS and JavaScript files in your project.
Read the Getting started page for information on the framework contents, templates, examples, and more.
Follow these steps to integrate the NSW Design System into your project using npm:
-
Install Node.js and npm: If you haven't already, install Node.js and npm by following the instructions in the Node.js installation guides.
-
Create a package.json: In your project's root directory, run the
npm initcommand in your terminal. Follow the prompts to generate apackage.jsonfile, providing essential project information. -
Add nsw-design-system to your dependencies: Run the following command to install the NSW Design System as a dependency in your project:
npm install --save nsw-design-system -
Import Styles and JavaScript: Learn how to import the design system's styles and JavaScript into your project's build by referring to the relevant sections below.
To import all design system styles as a single package, add the following snippet at the start of your main SCSS file:
@import 'node_modules/nsw-design-system/src/main';
The core library includes the design system's base theme, typography, mixins, and helper functions. Import the core library at the start of your main SASS file:
// Core libraries
@import 'node_modules/nsw-design-system/src/global/scss/settings/settings';
@import 'node_modules/nsw-design-system/src/global/scss/base/all';
@import 'node_modules/nsw-design-system/src/global/scss/helpers/all';
@import 'node_modules/nsw-design-system/src/global/scss/settings/palette';
@import 'node_modules/nsw-design-system/src/global/scss/settings/theme';
@import 'node_modules/nsw-design-system/src/core/all';
After importing the core library, you can start importing individual components as needed:
// Components
@import 'node_modules/nsw-design-system/src/components/accordion/accordion';
@import 'node_modules/nsw-design-system/src/components/card/card';
@import 'node_modules/nsw-design-system/src/components/notification/notification';
Include the following lines of code in the <head> tag of your main HTML document, placing them before the NSW Design System styles import:
<link href="https://fonts.googleapis.com/css2?family=Public+Sans:ital,wght@0,400;0,700;1,400&display=swap" rel="stylesheet">
<link href="https://fonts.googleapis.com/icon?family=Material+Icons" rel="stylesheet">
Alternatively, you can import fonts and icons directly in your CSS:
@import url('<https://fonts.googleapis.com/css2?family=Public+Sans:ital,wght@0,400;0,700;1,400&display=swap');>
@import url('<https://fonts.googleapis.com/icon?family=Material+Icons');>
Certain NSW Design System components require JavaScript to enable advanced functionality. To ensure your page is ready for JavaScript execution, include the following script tags at the end of your HTML document:
<script src="path/to/main.js"></script>
<script>window.NSW.initSite()</script>
</body>
</html>
Depending on your project setup, you can copy the JavaScript file from node_modules or add a reference in your build workflow.
For a faster setup, you can utilize the JSDelivr CDN to include the NSW Design System's CSS and JavaScript files directly in your project's HTML:
<html>
<head>
<!-- ... -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/nsw-design-system@3/dist/css/main.css">
</head>
<body>
<!-- ... -->
<script src="https://cdn.jsdelivr.net/npm/nsw-design-system@3/dist/js/main.min.js"></script>
<script>window.NSW.initSite()</script>
</body>
</html>
Please read through our contributing guidelines. Included are directions for opening issues, coding standards, and notes on development.
Get notified when there’s an update or new release on the NSW Design System's and chat with the project maintainers and community members.
-
Join our Digital NSW Community.
-
Watch the NSW Design System Github.
-
Ask and explore our GitHub Discussions.
View and raise issues and bugs through our Issues tracker on Github or report a bug on the Digital NSW community.
Access the complete set of design assets required for designing, sharing, and prototyping using our Figma UI Kit.
For transparency into our release cycle and in striving to maintain backward compatibility, The NSW Design System is maintained under the Semantic Versioning guidelines. Sometimes we make mistakes, but we adhere to those rules whenever possible.
Our version numbers consist of MAJOR.MINOR.PATCH, where:
-
MAJOR version is used for incompatible global changes.
-
MINOR version is used for significant backward-compatible updates and the release of new components.
-
PATCH version is used for minor backward-compatible updates, new component variations, and bug fixes.
See the Releases section of our GitHub project for changelogs for each release version. Release posts on our what’s happening page contain summaries of the most noteworthy changes made in each release.
Feel free to reach out if you have any questions or need more help with integrating the NSW Design System into your projects!