[![Coverage Status](https://coveralls.io/repos/github/wealthsimple/patchwork/badge.svg?branch=master&t=keO380)](https://coveralls.io/github/wealthsimple/patchwork?branch=master)
[![Dependabot Status](https://api.dependabot.com/badges/status?host=github&repo=wealthsimple/patchwork&identifier=128153819)](https://dependabot.com)

# Patchwork - Wealthsimple React Component Library

## Purpose:

Patchwork is Wealthsimple's UI Component library for React applications.

It aims to provide a first class DSL for building user interfaces that can:

- Reduce the amount of DOM and CSS you have to write,
- Help ensure that all your UI is themeable,
- Help ensure that all your UI is accessible.

## Patchwork User's Guide

Are you a developer trying to use patchwork to implement features in your application? Check out the [Users' Guide](./docs/users-guide/INTRO.mkd).

## Patchwork Implementer's Guide

Are you a designer or a developer adding features to patchwork itself? Check out the [Implementers' Guide](./docs/implementers-guide/INTRO.mkd).

## Stack

- [React](https://reactjs.org/)
- [Styled-components](https://www.styled-components.com)
- [Storybook](https://storybook.js.org/)
- [Flow](https://flow.org/)

## Architectural Decision Records

Wonder why something is implemented a certain way? Curious about the reasoning behind this code-base's conventions?

Decisions of this nature are recorded in this repo as [Architectural Decision Records (ADRs)](./docs/adr/README.md).

## Consuming components in your project

You can consume this project one of two ways:

#### Babel 7+ With Flow

For compatibility with our internal toolchain, I just expose the ES6+Flow source code for now.
That means you'll need a compatible babel config + bundler setup in your project. Check this project's
`.babel.config.js` for the specific configuration.

Then import things from `@wealthsimple/patchwork` to use them:

```js
import { Box } from '@wealthsimple/patchwork';
```

#### ES5/UMD

Not running a transpiler? Running a transpiler that's not Babel (e.g. TypeScript)? Not using Flow?

No problem. We also expose a UMD-ified ES5 version of this library in the `dist` folder:

ES6/TypeScript:

```js
import { Box } from '@wealthsimple/patchwork/dist';
```

CommonJS:

```js
const { Box } = require('@wealthsimple/patchwork/dist');
```

## Running locally

To run patchwork locally run ( on port 9001):

```
yarn storybook
```

If using a compatible IDE ( RubyMine ) you can display flow errors by linking the flow library:

- Language & Frameworks / JavaScript
- Select language version: Flow
- Select executable flow library "... patchwork/node_modules/flow-bin/flow-osx-v0.78.0/flow"

## Accessibility Testing

As of [January 2021](https://www.ontario.ca/page/how-make-websites-accessible), Wealthsimple is legally required to make any of our websites [WCAG 2.0 Level AA](https://www.w3.org/WAI/standards-guidelines/wcag/) compliant. Accessibility is sometimes forgotten about when developing fast features in web, but it’s extremely important in providing all of our clients the same, equal-level of access to our services. Patchwork must be accessible because it serves as the building blocks for our entire application.

In order to test accessibility, we have some scanning jobs in CI that will flag things like missing screenreader labels, insufficient text/background colour contrasts.

_Note_: Automated testing can't catch everything. When you make changes or create a new component, before you launch it to the public you should run it by the [Web a11y testing guidelines](https://wealthsimple.quip.com/SOTJAKAU2wQA/A11y-Manual-Testing-Guide-Web-Edition).
