@aminohealth/phenotypes

Amino's design language and front-end component library

Downloads in past

Stats

StarsIssuesVersionUpdatedCreatedSize
@aminohealth/phenotypes
17.2.0a month ago7 years agoMinified + gzip package size for @aminohealth/phenotypes in KB

Popular Searches

Readme

Phenotypes
!NPM versionnpm-version-imagenpm-url Storybook
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:
of React componenents + a CSS/SASS library of layout & utility classes 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 folderdist.
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 docstheming-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)

  1. Have Docker installed
  2. Clone this repo and cd into it
  3. Run make build
  4. Run make run
  5. 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.
  1. Install the library dependencies

/phenotypes$ yarn install

  1. Install at least these VS Code extensions:

Auto-formatting:

Linting:

Syntax highlighting:

(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:
This job is automatically built when you open or update a PR in GitHub. 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.
  1. Based on the current version (shown in package.json), use
[semver](https://semver.org/) 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.
  1. Create a new branch off of the latest main branch (you can use
`<yourname>/v1.2.3` for the branch name)
  1. Run npm version 1.2.3 to change the version number in package.json. This
will automatically create a new commit in your branch.
  1. Run make dist to upgrade the contents of the /dist directory. If there
are any changes, commit those to your branch.
  1. Push your branch to GitHub and create a PR to merge back into the main
branch.
  1. Once it’s merged, pull down the latest main branch onto your machine.
  2. 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.
  1. Make sure you have the lastest main and gh-pages branches.
  2. git checkout gh-pages
  3. git rebase origin/main (conflicts should be rare, as most additions in
`gh-pages` are files that don't exist in `main`)
  1. Always rebuild: make build
  2. 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`.
  1. Commit the changes to the gh-pages branch and push it to GitHub.
  2. GitHub will automatically deploy the new content to
https://phenotypes.amino.com (it may take a few minutes).