@newjersey/njwds 0.3.0 → 1.0.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2020 New Jersey
+Copyright (c) 2023 New Jersey
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -2,23 +2,32 @@
 
 The NJ Web Design Standards are an extension of the [US Web Design Standards](https://github.com/uswds/uswds/) with a specific theme and components for State of New Jersey digital properties and services.
 
-## Using the library
+## How to install and use the NJWDS
 
-- If you are using Node and npm in your project, then you can install the package in the root of your project directory with the following command in your terminal:
+### With Node and NPM
+
+Follow the instructions on the [USWDS Documentation - Installation](https://designsystem.digital.gov/documentation/developers/#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:
 
 ```bash
 npm install @newjersey/njwds --save
 ```
 
-If this worked successfully, you should see `@newjersey/njwds` listed as a new dependency in your `package.json` file.
+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/`).
 
-- In the root JavaScript file of your project's frontend, import the CSS for this designs system with the following line:
+### Without Node and NPM
 
-```js
-import "@newjersey/njwds/dist/css/styles.css";
-```
+1. On our [GitHub Releases page](https://github.com/newjersey/njwds/releases), 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](https://designsystem.digital.gov/documentation/developers/#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](https://designsystem.digital.gov/documentation/developers/#using-uswds-css-and-javascript-in-your-project) 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`).
 
-- Use the CSS classes in your frontend code (HTML or JS) to render certain NJWDS components. For a full list of examples and the corresponding code, see here: https://newjersey.github.io/njwds/components/detail/layout--docs.html. Note that the NJWDS is built on top of the USWDS. Components and utilities included in the USWDS can be used with this same package, only they will have certain themed styling included: https://designsystem.digital.gov.
+For a full list of examples of NJWDS components and their corresponding code, see our [NJWDS Component Gallery](https://newjersey.github.io/njwds/components/detail/layout--docs.html). Note that because the NJWDS is built on top of the USWDS, you can use USWDS [components](https://designsystem.digital.gov/components/overview/) and [utilities](https://designsystem.digital.gov/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](https://designsystem.digital.gov/documentation/developers/#compiling-uswds-sass-into-css) page to compile your own CSS using SASS.
 
 ## Developing the library
 
@@ -45,3 +54,12 @@ This imports the USWDS, pulls in the NJ-specific components and styles, and save
 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.
+
+## Releasing a new version to NPM
+
+1. Go to the [Draft Release GitHub Action](https://github.com/newjersey/njwds/actions/workflows/draft-release.yml)
+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](https://semver.org/)). 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](https://github.com/newjersey/njwds/releases) 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](https://github.com/newjersey/njwds/actions/workflows/publish-release.yml). Confirm this action succeeded by checking the the [NJWDS package](https://www.npmjs.com/package/@newjersey/njwds) on the NPM registry.