Wrapper package for NSW Design System

• separates out the CSS/JS into components
• uses the material icon svgs rather than the font
• provides Twig templates for each component (based on nswds .hbs files)
• documented in Storybook

Using NSWDS

Installation

npm install @pnx-mixtape/nswds --save

Usage

Once installed, you can import the css and javascript into your project's codebase.

Importing and overriding styles

Dependencies:

• postcss-design-tokens

Add the tokens and override the values or just copy/paste from Mixtape and update;

eg. project-tokens.mjs

import tokens from "@pnx-mixtape/nswds/tokens"

// Override existing ones;
tokens.colour.brand.primary = "rgb(0, 92, 250)"

//Add new ones;
tokens.newThing = "somethingNew"

export default tokens

The custom properties can also be included via @import or just copy/paste if you only need a limited set.

This file should be included in the browser.

eg. project-constants.css

@import "@pnx-mixtape/nswds/src/constants.css";

:root {
  --my-colour-primary: rgb(0, 92, 250);
  --my-colour-secondary: rgb(247, 143, 29);
}

The custom media should also be included, and is required in EVERY css file that uses them. PostCSS replaces this, so there is no need to worry about duplication.

eg. project-breakpoints.css

@import "@pnx-mixtape/nswds/src/_custom-media.css";

@custom-media --my-breakpoint (width >= "200px");

Once these 3 files are setup, you can proceed with adding the components.

eg. buttons.css

@import "../project-breakpoints.css";
@import "@pnx-mixtape/nswds/src/Atom/Button/button.css";

.nsw-button--dark {
  --border-radius: 0;

  @media (--medium-up) {
    border-width: 6px;
  }
}

The packages are as modular as practical, so you can be specific about what to include based on your projects requirements.

Cascade layers

@layers are used to ensure ease in overriding CSS on a project level. If you are importing @pnx-mixtape/nswds/src/base.css CSS then the layers are included.

If you are only partially importing the base CSS files, then you'll need to manually include the layers at the start of your CSS;

@layer design-system.defaults, design-system.atoms, design-system.layout, design-system.components, design-system.utilities;

Any CSS not wrapped in a layer will have higher specificity to NSWDS's CSS. Alternatively you can append your own layers to the end of these, to achieve a similar result.

Examples

nswds.pnx.io is this packages storybook (coming soon).

Contributing to NSWDS

Finding and Logging issues

Please log bugs to Jira or join the #mixtape channel in the PNX Slack to ask questions.

Adding patch-package to your project will allow you to create project specific patches for NSWDS, so you're not hampered by waiting for a bug fix to released in NSWDS. Please upload any patches made to the relevant bug report in Jira.

Build tools

This project uses NVM and NPM to manage node versions and build tasks.

Dependencies and building

First clone this repository;

git clone [email protected]:previousnext/nswds.git
cd mxds

Install project dependencies:

nvm i
npm i
npm run build-nswds

Then you can start watching for changes with;

npm run dev

Linting and Test coverage

Before pushing a PR make sure your changes are linted and pass the test coverage.

npm run format
npm run lint
npm run test-storybook

These will all run by Github Actions on the PR but it's better to catch issues first.

Integration testing with Vitest will be added in a future release.

Publishing changes

When you are ready to publish your change, commit your work and follow the prompts using:

npm run commit

This uses Commitizen to manage commit messages and versioning. You will be walked through an interactive questionnaire.

Select the type of change from Feat (Feature), Fix, Docs, Style, Refactor, Perf, Test, and Chore. This will be used in the commitizen changelog.

Then create a pull request, wait for builds to pass, and get the code reviewed.

Once approved, merge the PR.

When you are ready for a full release, from main, run;

npm version patch -m 'chore: tag %s'

To bump the version number in package.json, then tag the commit and push to origin.

This will trigger a deploy in CircleCI to update nswds.pnx.io. Approval is then required to publish to the NPM registry.