npm package: @pnx-mixtape/nswds
Description: Wrapper package for the NSW Design System
Latest version: 0.0.17

# 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

```
pnpm add @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](https://www.npmjs.com/package/postcss-design-tokens)

Add the [tokens](https://github.com/previousnext/nswds/blob/main/src/tokens.js)
and override the values or just copy/paste from Mixtape and update;

_eg. project-tokens.mjs_

```js
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](https://github.com/previousnext/nswds/blob/main/src/constants.css)
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_

```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](https://github.com/previousnext/nswds/blob/main/src/_custom-media.css)
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_

```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_

```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](https://developer.mozilla.org/en-US/docs/Web/CSS/@layer) 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;

```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](https://nswds.pnx.io/)** is this packages storybook (coming soon).

# Contributing to NSWDS

## Finding and Logging issues

Please log bugs to [Jira](https://previousnext.atlassian.net/secure/RapidBoard.jspa?rapidView=5)
or join the #mixtape channel in the PNX Slack to ask questions.

Adding [patch-package](https://www.npmjs.com/package/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 pnpm to manage node versions and build tasks.

### Dependencies and building

First clone this repository;

```
git clone git@github.com:previousnext/nswds.git
cd mxds
```

Install project dependencies:

```bash
nvm i
pnpm i
pnpm run build-nswds
```

Then you can start watching for changes with;

```pnpm
pnpm run dev
```

### Linting and Test coverage

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

```
pnpm run format
pnpm run lint
pnpm 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:

```
pnpm run commit
```

This uses [Commitizen](https://www.npmjs.com/package/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;

```
pnpm 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](https://nswds.pnx.io/).
Approval is then required to publish to the [npm registry](https://www.npmjs.com/package/@pnx-mixtape/nswds).