@nvps/design

NvDesign

The Angular UI Library by New Visions for Public Schools

Usage

1. Install using npm install @nvps/design
2. Import @nvps/design into the appropriate modules
3. To get the appropriate design system color, size, and font variables:

• Recommended Add the following to your main sass/scss file

  @import '~@nvps/design/nv-global.scss'

• Or, add this to your main css file

  @import '~@nvps/design/nv-global.css'

Development

Component development guidelines

UI Components in the nv-design library should be:

1. Stateless

Components should rely on their parent to determine their state, and should not have any internal state nor reference any store for data. If you need to use data from the store, pass this in from the parent.

2. Dumb

Any logic in the UI component should be presentational only. No business logic should be performed in a UI component.

3. Documented

Inputs and outputs should be documented. This can be achieved by

i) writing JSDoc style comments before each input and output, and

ii) Adding an Overview story in the .story file (See below)

4. Visually tested

All visual states of a UI component should have an associated story-case in the .story file. See Stackoverflow for writing stories

5. Logically tested

All methods in the component should have appropriate unit tests. Additionally any inputs that affect the DOM, should include DOM tests.

Notes: When you add a component, you must update the components.ts file with that component so it is added to the module, and to the export API

Testing a component

Karma

We're using Angular CLI's built-in Karma testing library.

Run your tests:

npm run test

Check your coverage report

npm run coverage

These tests are run automatically in CircleCI each time you push.

Chromatic

We use Chromatic for visual QA. Each time you push, Chromatic will run and check for visual changes.

Your CI build will fail if there are visual changes. When you are ready, ping a designer to approve the changes. Once the changes are approved by Design, you can re-run from the failed step, to complete the CI build.

Opening a PR

To merge your code, open a PR and ensure the above development guidelines are met.

Additionally, use GitHub's code review feature to select at least one developer and one designer to perform a code review and visual review, respectively, and let them know via Slack.

Once you have approval from a Developer and a Designer, a design-system member will merge the PR into master.

Publishing

After a PR is merged to master, we manually deploy to npm.

To publish:

1. Make sure you are a member, and can contribute to the package
2. Run npm login and follow the instructions
3. In master, update the version of the package with

   npm run version "patch | minor | major"

   (or manually edit the package.json)
   • While we don't explicitly plan releases, we're using Semantic Versioning for our design system
   • Patch: A small, no-impact change to an existing component
   • Minor: A new component is added, or new functionality is added to an existing component
   • Major: A breaking change to any component's API
   • Note - This versioning will not be followed closely untill the 1.0.0 release
4. Commit the version change git commit
5. Merge master branch into prod branch
6. From prod, build the distribution library

   npm run build

7. Publish the package to npm

   npm run publish

8. Create a new Release in GitHub off of prod, and summarize the changes since last version
9. Once published, any API changes should be shared on Slack to #portal-design-system.

Deploying docs

When a PR is merged to prod, the CI build will deploy a live Storybook build

Integrating in to the app

Each time a new package version is released:

1. Create a Jira ticket to upgrade the package version in the front-end codebase
2. Update any existing feature Jira tickets that use the modified component to reference the "package upgrade" ticket

Testing in the wild (npm link)

You can develop UI components in this package, and see the impact in context in the app using npm link. This should not be necessary for normal development—Storybook should provide enough context to build components—but this can be a useful debugging tool for the production app.

1. In this repo, build the package and setup the link

   # If your app uses npm
   npm run build && npm run link
   
   # If your app uses Yarn
   npm run build && npm run yarn-link

2. Navigate to the production app's repo directory

   cd path/to/production/app;

3. Remove the reference to this package in the package.json
4. In the app's repo, link the package

   # using npm
   npm link @nvps/design
   
   # or, using Yarn
   yarn link @nvps/design

5. Install node_modules in your app

   # using npm
   npm install
   
   # using Yarn
   yarn

6. Start the app

   npm run start:<environment>
   

7. To see changes in this package reflected in the app, you'll have to restart the server and reinstall node modules

Elements - (experimental)

Angular Elements is a technology that compiles Angular components into HTML custom elements. The experimental library is found in projects/nv-elements.