New Jersey Web Design System (NJWDS)

The NJ Web Design System is an extension of the US Web Design System with a specific theme and components for State of New Jersey digital properties and services.

How to install and use the NJWDS

With Node and NPM

Follow the instructions on the USWDS Documentation - Installation page starting at "Install using Node and npm." The key difference between these instructions and what you will need to do is that our package name is @newjersey/njwds instead of @uswds/uswds. Therefore, on Step 4, your installation commmand would be:

npm install @newjersey/njwds --save

Once installed, the NJWDS package name would affect the file path used in node_modules as well (i.e. node_modules/@newjersey/njwds/dist/ instead of node_modules/@uswds/uswds/dist/).

Without Node and NPM

1. On our GitHub Releases page, on the latest release (at the top of the list), you will see an "Assets" section at the bottom of the release information. Click on the "Source codede (zip)" link to download our package.
2. Follow the instructions on the USWDS Documentation - Installation page, starting with Step 2 of "Install the package directly from GitHub." Note that in our case, you would want to replace the uswds folder name with njwds.

Using NJWDS files in your project

Follow the instructions on the USWDS Documentation - Using USWDS page. Note that instead of uswds.css or uswds.min.css, you will refer to styles.css in the /dist/css directory. Also, the filepath should have njwds instead of uswds (i.e. assets/njwds/dist/js/uswds.min.js instead of assets/uswds/dist/js/uswds.min.js).

For a full list of examples of NJWDS components and their corresponding code, see our NJWDS Component Gallery. Note that because the NJWDS is built on top of the USWDS, you can use USWDS components and utilities not listed in our docs.

Customizing NJWDS or compiling your own assets

The NJWDS package also includes pre-compiled files in the src/ directory. Specifically, we add custom styles to USWDS on _uswds-theme-custom-styles.scss and custom theme on _uswds-theme.scss. Follow the instructions on the USWDS Documentation - Compiling SASS into CSS page to compile your own CSS using SASS.

Developing the library

Initial set up

• Clone this repository
• Run npm install
• [Optional] Run npm run import-components to import new USWDS components. This only needs to be done if new upstream components are developed. This imports the USWDS, pulls in the NJ-specific components and styles, and saves them in a dist directory. Note: This option may no longer work, if trying it out, use caution and check for regressions.

Build the design system assets

• Run npm run build-uswds to build the assets into the dist/ directory

Build the component library

• Run npm run build-docs to build the Fractal component gallery for reviewing the component documentation

View component library locally or development

• Run npm start to build the component library, launch a web server to host it, and live reload on development changes.

Deploy the component library

• Run npm run deploy

This builds USWDS styles, builds the Fractal docs, and then deploys them to the gh-pages branch.

Note: Do not push directly to the gh-pages branch. This is done automatically when committing to main.

Releasing a new version to NPM

1. Go to the Draft Release GitHub Action
2. Click the "Run workflow" dropdown, keep the branch set to main, and update the Semver Level based on what has changed since the previous release (semver documentation). Click the green button to "Run workflow".
3. This should create a new Pull Request bumping the package.json file's version according to the level you set to the release (e.g. minor release changes version from 0.1.0 to 0.2.0). Rebase & merge this PR into the main branch.
4. Go to the GitHub Releases page and confirm that you see a new draft release with this version. (Note that this will automatically happen after Step 2, and is not dependent on Step 3)
5. On the releases page, click the pencil icon on the top right to Edit the release. Document what has changed in this release; be sure to note any breaking changes. Once all looks good, click "Publish release" at the bottom.
6. This will automatically trigger the Publish Release GitHub Action. Confirm this action succeeded by checking the the NJWDS package on the NPM registry.