This package has been deprecated

Author message:

Use @arrow-ds/ds-components package instead

@bitdepth/ds-components

Arrow

Arrow is a Design System. A design system provides a central source for, among other things, design assets, UX guidelines and reusuable components as code. This repository contains reusuable React components and styles for use when building React web apps. You can also find useful links, guidelines and information on how to follow best practices when building web apps.

If you are reading this document in the component browser, you can browse the available React components using the navigation on the left. The Design Tokens section has guidelines and information on available styles and CSS.

Getting Started

Node requirements

The library is built and tested with node LTS (8.x). We recommend using the latest LTS version.

Component consumption

Here's an example of using the Button component. First, you specify the component library into your project as a dependency using npm:

npm install @bitdepth/ds-components

Then you can use it in your React projects like this:

import React from 'react';
import IconButton from '@bitdepth/ds-components';

export default (
  <IconButton
    icon="home"
    fill
    border
    label="Home"
  />
);

Style consumption

You will need to link the styles as these are currently not baked into the components. There are a couple of ways to do that and the styles are provided as both CSS and SCSS. If you are using the provided components and only need to work with basic styles in you app you should generally be able to simply link the compiled CSS file. However, if you need to do more detailed work you can import the SCSS files to make use of the available design tokens, mixins and other utility functions.

CSS

To use the compiled CSS simply link or import lib.css.

SCSS

The SCSS file are currently under src/scss. You can import all the styles via src/scss/lib.scss. Alternatively browse that directory to see what is available in each file.

Component specific SCSS files should reside in the component folder alongside other coding assets: src/components/Button/Button.scss.
These files will be imported into the root SCSS file at src/scss/libs.scss.

Component specific storybook presentation SCSS should also reside in the component folder alongside other coding assets: src/components/Button/Button.stories.scss.
These files will be imported into the root storybook SCSS file at src/scss/storybook.scss. This css is not published with the library.

TODO: Needs more info.

CSS Namespacing

All published CSS classes should be prefixed with ds-.
All CSS classes used for storybook presentation should be prefixed with sb-.

Typescript definitions

If you are using Typescript in your project you will need to use the supplied Typescript definition file, index.t.ds.

Using from the source

If you want to build from source to test things or to contribute start by cloning the git repo from here.

NPM scripts

To build the code:

npm install
npm run fetch:assets
npm run build

Fetch brand-ai assets

Fetch latest brand-ai assets into /assets directory

npm run fetch:assets

Storybook

Storybook is used to display the components. Just run npm run storybook and open http://localhost:3000 in a browser.

Linting

Run SCSS and Javascript linting using stylelint and eslint + prettier

npm run lint

Fix common JS linting issues

npm run lint:js:fix

Testing

Run unit and integration tests using Jest + Enzyme

npm run test

To run individual tests with Jest + Enzyme

npm run test ./src/components/Dropdown/Dropdown.test.jsx

Run end to end and visual regression tests using nightwatch

npm run e2e

To run individual e2e tests use

npm run e2e -- --test test/e2e/components.js --testcase 'VRT Icon'

Jenkins e2e

The end to end tests on our Jenkins QA Job run against BrowserStack. These currently target IE, Chrome, Firefox and Safari (Mac). A first point of call after a CI build failure for the e2e tests should be BrowserStack Automate where you can replay video of the tests to try to identify the cause of failure.

Build for release

Build component library for production release using webpack to /dist directory

npm run build

Analyze webpack build

npm run build:analyze

Accessibility

To test the accessibility of the DSM components, run the PA11Y script. PA11Y loops through all the DSM components then compiles a report of any accessibility errors that appear. It will then make recommendations of how to fix the issue.

npm run test-accessibility

The config file can be found here: ds-components/config/pa11y/config.js

Additional Info

A pre-commit hook is in place to automatically run linting and tests on staged files to ensure only clean commits are made to the repository.

A CI pipeline is in place to checks merges to the Release branch to build an instance of storybook to http://ds-components-qa.s3-website-eu-west-1.amazonaws.com/ for QA.

Once QA has been completed, the publish script can be run which will merge the Release branch into the Master branch and publish the library to NPM.

npm run release [minor, major, patch x.x.x]

The CI pipeline will then build storybook from the Master branch and deploy to http://ds-components-prod.s3-website-eu-west-1.amazonaws.com/.

Jenkins e2e

The end to end tests on our Jenkins QA Job run against BrowserStack. These currently target IE, Chrome, Firefox and Safari (Mac). A first point of call after a CI build failure for the e2e tests should be BrowserStack Automate where you can replay video of the tests to try to identify the cause of failure.

A temporary version of the site is published to s3 where BrowserStack can access it. You can run the e2e tests from your local machine against this build by typing npm run e2e:ci which will give you console access to the test failure report.

You can also baseline the VRT tests by running the VRT App with npm run e2e:vrt:ui and navigating to the http://localhost:8000

Contributing and help

See the guidelines in CONTRIBUTING.md.

Links

Production QA VRT

Jenkins CI

Release process

To ensure a smooth release process follow the steps below

• Ensure all PR's for release branch are merged with no conflicts
• Checkout the release branch locally and pull the latest changes
• Update the CHANGELOG.md with the tickets from last sprint
• npm run release ensuring you pass in the correct version

The release script will publish the package to NPM and push the latest changes to the release branch. Finally it will checkout master and merge the latest changes from release before pushing a tagged release to the master branch.