Ethos Design System

A collection of reusable React components, patterns, and design guidelines we use at Ethos to build our digital products.

Setup

See package.json for node engines – you need to have that version of node installed specifically, e.g. via nvm:

nvm install v10.16.3  # then do `nvm list` to ensure version is available
nvm use               # use the version specified in `.nvmrc`, if installed

Download fonts.zip from Google Drive and unzip it.
Copy the contents to src/fonts, e.g.:

$ mkdir -p ethos-design-system/src/fonts/
$ cp -a ~/Downloads/fonts/ ethos-design-system/src/fonts/

Development

Run yarn css:develop if you're editing global CSS (optional).
Run the live style guide with yarn styleguide.
Open http://localhost:9008 in your browser.

Tests

yarn test

Run an individual test:

yarn test -t "valid single keys do not throw"

Debug console.log and debugger statements in Chrome:

yarn test:debug

Then do following to setup debugging in Chrome:

Open Chrome and type following in the address bar: chrome://inspect
Click on "Open dedicated DevTools for Node"

Cypress E2E

Our end to end integration tests use Cypress. To run Cypress locally do:

yarn e2e:dev

The Cypress application will open up and it should be self evident how to run the specs by just clicking around the Cypress interface.

Our CI/CD is setup via Travis—you can find its configuration at .travis.yml

Usage

To use a release downstream, update your app's package.json as follows:

  "ethos-design-system": "github:getethos/ethos-design-system#v1.2.3",

Releases

TLDR: Run yarn version and git push origin tagname when your PR is ready.

Each PR that merges to master should update the package.json version one way or another, and ideally create a corresponding git tag. One way to do this is to run yarn version in your branch and push. This will:

Prompt you for the new version number
Update package.json with the version number
Commit the change in a new commit

To create and push a git tag, run git tag v1.2.3 && git push origin v1.2.3. You can skip this if the release isn't specifically needed downstream yet.

For more granular control:

$ git tag v1.2.3 [-f]               # add a lightweight tag locally
$ git tag -d v1.2.3                 # delete tag v1.2.3 locally
$ git push origin v1.2.3            # push tag v1.2.3
$ git push -d origin v1.2.3         # delete tag v1.2.3 remotely

Design patterns

JS concepts

The repo is set up to import individual components as necessary.
Preference for hooks and functional components over classes.
Please try to avoid using <Media> and <Spacer> components for now, they are deprecated. For media queries, import @include rules from the media scss file as described below.

CSS/SCSS concepts

CSS variables are the core of styling in the EDS.
- All CSS variables are available on all pages in both monorepo and cms; they are the single source of truth for brand colors, breakpoints, and other commonly reused bits of css.
The EDS is (to an extent) designed as a set of immutable components in terms of interior JS logic as well as styling. New styling of existing components should be handled by PR's on the EDS, not by writing local overrides in files.
We encourage a limited subset of SCSS features for the EDS.
- The primary reason for using scss is to import @include statements from the media scss file for reusable media queries, like this:
  - @import '~ethos-design-system/src/components/Media/Media.scss';
  - @include for-phone-and-tablet {
- CSS variables don't always work nicely with scss; we have a preference for calc over scss math operations.

kenning/ethos-design-system