Grove: Garden State Design System (fka NJWDS)

Grove (aka NJWDS) is the design system for the State of New Jersey, built to extend the U.S. Web Design System (USWDS). It provides components and guidance specific to New Jersey's needs, with accessibility built in by default. Grove is published as @newjersey/njwds on npm for installation (see below)

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 Grove/NJWDS npm 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 Grove 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 Grove (NJWDS) components and their corresponding code, see our Storybook Component Examples and our Grove (NJWDS) Documentation Site. 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 Grove 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 grove:build to build the assets into the dist/ directory

View component library locally or development

Start the local development server

• Run npm run storybook to build the docs, launch a web server to host it on port 6006, and live reload on development changes. This is not the design system, it is Storybook. Run npm run grove:dev to work on the design system itself.

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 "Deploy to GitHub Pages" GitHub Action as well as the "Publish Release" GitHub Action. Confirm the "Publish Release" action succeeded by checking the the NJWDS package on the NPM registry.

Automated testing

Visual regression tests

Visual regression tests are setup to run against the Fractal documentation in order to catch any simple regressions as we rebuild the CSS. To set the initial screenshots run npm run test:visual:update to run tests against those screenshots run npm run test:visual. Whenever visual updates are made to components, the screenshots will need to be updates. These tests also run CI. Make sure the documentation is running locally (npm start) or the tests will fail.

Accessibility tests

Components also have basic accessibility tests. To run these tests, run: npm run test:accessibility. These tests also run in CI.