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
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.