@aminohealth/phenotypes

Phenotypes is Amino’s design system. It helps ensure a consistent look and feel within and between Amino’s products, and optimizes the workflow between design & engineering.

The Phenotypes repository is the home for:

A UI library published to npm:@aminohealth/phenotypes, consisting of React componenents + a CSS/SASS library of layout & utility classes
A Storybook site that documents the above library, plus guides for producing Phenotypes-based designs

📚 Documentation

Documentation for the latest version of Phenotypes lives at:

https://phenotypes.amino.com/latest

You can also view docs as they existed in older versions by changing /latest to the version number (12.0.0 is the oldest version available):

https://phenotypes.amino.com/12.0.0

⚙️ Usage

Installation via NPM

The easiest way to install Phenotypes in your project is through NPM or Yarn. This will give you out-of-the-box access to the React components & SASS library, and will make it easier to upgrade Phenotypes to future versions, and to bundle the Phenotypes with your app’s bundle.

/your/app/$ npm install @aminohealth/phenotypes

React components

We recommend using a namespace (import * as phenotypes) when importing Phenotypes components, so that you can easily see which parts of your JSX are Phenotypes components.

import * as phenotypes from '@aminohealth/phenotypes';

function MyComponent() {
  return (
    <div>
      <phenotypes.Button>Submit</phenotypes.Button>
    </div>
  );
}

SASS

If you’re using SASS, you can import Phenotypes’s SASS directly (rather than the pre-compiled CSS). This allows you to use Phenotypes’s SASS variables, functions, mixins, utilities API, etc. We recommend importing it near the beginning of your app’s system, so that your app’s style rules have higher precedence.

// somewhere in your SASS filesystem ...
@import '~@aminohealth/phenotypes/src/styles/phenotypes.scss';

CSS

If you aren’t using SASS, you can have your project use the CSS files located here:

node_modules/@aminohealth/phenotypes/dist/css

Copy that full folder into a publicly-accessible assets folder, and then include the phenotypes.css file in a common template used throughout your application.

<head>
  <link href="/path/to/phenotypes.css" rel="stylesheet" type="text/css" />
</head>

Installation without NPM

If you’re not using NPM, you can grab the latest pre-built javascript & CSS files from the /dist folder.

These can be included within your application code a variety of ways—please reach out to a Phenotypes engineer if you need help getting started.

Theming

Certain aspects of Phenotypes can be themed using CSS variables. See these docs for more info.

🗃 Repository organization

Git

main branch - the main working branch of Phenotypes. Branch off of the main branch when you want to make changes.
gh-pages branch - branched off of main, plus adds the static content for https://phenotypes.amino.com. See the below for instructions on updating that content.
release tags - Each release has a corresponding tag (e.g. v12.0.0). Use these tags to view code as it was for past versions.

Directory structure

/.storybook - contains the configuration for the Storybook site, as well as public "assets" used on the site (such as images).
/dist - contains the compiled JS & CSS files for the public API of Phenotypes library. All contents are automatically generated using make dist.
/docs - contains the automatically-built static content which powers https://phenotyes.amino.com. This directory only exists in the gh-pages branch.
/src - contains all the Phenotypes library source code

👷 Development

Getting started (running Storybook in development mode)

Have Docker installed
Clone this repo and cd into it
Run make build
Run make run
Open http://localhost:3000 in a browser

In development mode, Storybook will hot-reload most changes directly into your browser (without your refreshing the page), including Typescript & SASS changes. However, some aspects of the Storybook UI are inferred from Typescript types & associated jsDocs (such as the props tables on component pages), which are not currently hot-reloaded by Storybook. To see those changes, you'll need to restart Storybook (kill the make run process and run make run again).

Configuring VS Code

If you’re using VS Code, follow these steps to enable Phenotypes’s linting/formatting/etc configuration in your editor.

Install the library dependencies

/phenotypes$ yarn install

Install at least these VS Code extensions:

Auto-formatting:

esbenp.prettier-vscode

Linting:

Syntax highlighting:

silvenon.mdx

(Not) Updating the /dist folder in your branch

As noted in the directory structure section, /dist holds the compiled Javascript & CSS that is published to NPM. However, the Storybook site does not use those assets—instead, it compiles its own files which are not included in version control. /dist is always updated when publishing a new version of Phenotypes to NPM, so you don't need to update it when making a PR.

However, if you are interested in seeing how your changes impact the compiled JS or CSS, and/or if you feel that your PR reviewer shoud review those changes, you can run this command to rebuild the /dist directory:

/phenotypes$ make dist

Note: if you run this command and there have been other PRs merged into the main branch since the last version of Phenotypes was published, you may see additional changes to the /dist files you weren’t expecting.

Running tests & other checks

The following commands are available for running the checks locally:

make test: run the full suite of tests, type checking, linters, and formatting checks
- make jest: run all of the Jest unit tests
- make jest_watch: run Jest in watch/interactive mode, which will "listen" for changes to the code and automatically re-run the related test cases. It also provides a menu which you can use to filter the test runs down to specific test files or test cases. If at any time you lose the menu, you can type "w" to restore it.
- make tsc: run Typescript type checking
- make eslint: run ESLint (linter for Javascript/Typescript)
- make stylelint: run Stylelint (linter for CSS/SASS)

Modifying NPM dependencies

Always use the yarn command to modify the npm dependencies (using the npm command will not update the yarn.lock file, which is used to "pin" versions of our dependencies & their dependencies).

For example, to add react:

/phenotypes$ yarn add react react-dom

To add a dependency for development/testing purposes only (so, not included in the /dist bundles), use the --dev flag:

/phenotypes$ yarn add --dev @types/react

To learn more about what you can do with yarn:

$ yarn help
$ yarn help add
$ yarn help remove
$ yarn help upgrade
... and so on

Note: dependency changes don't take affect in your local environment until you rebuild:

/phenotypes$ make build

Deploying your branch to preview

http://phenotypes.amino.io is the "preview" site of Phenotypes; you can deploy your branch there if you need to show your changes to a PR reviewer. You’ll need to be on the Amino VPN to visit that domain.

You can deploy your branch to preview via successful builds of two different jobs in Jenkins:

phenotypes-pr: This job is automatically built when you open or update a PR in GitHub.
phenotypes-manual: You can create a one-off build manually using the "Build with Parameters" feature, and entering your branch name.

Regardless of which job is used, if the build passes, it will have a "Deploy to preview" link at the bottom of the build status page in Jenkins. (Click it!)

🚀 Publishing a new version to NPM

To publish a new version of the library for the first time, make sure you're logged into NPM via the command line. If you don't have an NPM account yet, create one on npmjs.com, and request to be added to the @aminohealth organization.

$ npm login

Once you’re logged in, you can proceed.

Based on the current version (shown in package.json), use semver to determine what the new version will be (in the [major].[minor].[patch] format). For the remainder of the instructions, assume you chose 1.2.3 as the new version.
Create a new branch off of the latest main branch (you can use <yourname>/v1.2.3 for the branch name)
Run npm version 1.2.3 to change the version number in package.json. This will automatically create a new commit in your branch.
Run make dist to upgrade the contents of the /dist directory. If there are any changes, commit those to your branch.
Push your branch to GitHub and create a PR to merge back into the main branch.
Once it’s merged, pull down the latest main branch onto your machine.
With the newly-updated main branch checked out (package.json should now contain the updated version), run npm publish. (This will actually push the new version to NPM!)

If there were any changes to the Storybook docs site in this version (such as new/modified content), proceed below to update https://phenotypes.amino.com.

📚 Updating https://phenotypes.amino.com

To update the production documentation site, you’ll need to update the gh-pages branch.

Make sure you have the lastest main and gh-pages branches.
git checkout gh-pages
git rebase origin/main (conflicts should be rare, as most additions in gh-pages are files that don't exist in main)
Always rebuild: make build
Generate the new docs using make docs.
- This will create a new folder inside of /docs, or overwrite an existing one, depending on the version in package.json.
Commit the changes to the gh-pages branch and push it to GitHub.
GitHub will automatically deploy the new content to https://phenotypes.amino.com (it may take a few minutes).