import { Meta } from '@storybook/addon-docs/blocks';

<Meta title="Manual|2 - User's Guide" />

# Using Patchwork

Broadly speaking, there are three types of UI features that you are likely to be working on:

- Greenfield: User-facing, new UI implemented from the Design Team's widget library in Abstract
- Legacy/One-off: User-facing UI, either being ported from AngularJS to React without a design update, or from designs not satisfied by the widget library in Abstract.
- Internal/Experimental: not user facing, no input from the design team.

Patchwork can satisfy all these use cases, but you'll be using it differently in each case.

## Greenfield

This is the optimal case, and where we want to spend most of our time going forward.

In this situation, you

- Have a sketch design from the design team
- The majority of the bits and pieces of that design are accounted for in the design team's widget library in Abstract.

In this case, you can build your UI with the high-level components in the `/core` folder, gluing them together with the Patchwork Grid system and the spacing and stacking properties provided by the `/primitives` components.

You will find yourself writing **almost no CSS** outside of Patchwork in this case.

You may use CSS inside Patchwork as you implement new `/core` components.

## Legacy/One-off

In the short term, you will find yourself working in this mode while the design team builds out their widget library.

In this situation, you

- are porting AngularJS code into a React micro app in order to clean it up, but have no mandate to update the visual design, or
- you have been given a highly custom design that for visual interest or other reasons doesn't follow the constraints of the widget library in Abstract.

In this case you can also build your UI with the high-level components in the `/legacy` and/or `/one-off` folders, gluing them together with the Patchwork grid system, the `/legacy` grid system, or custom CSS as necessary.

You will find yourself writing **a small-to-medium amount of CSS**. However, try to prefer Patchwork `/primitives` where possible.

All Patchwork components can have their CSS extended using the `.extend` tagged-template function:

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

const OneOffText = Text.extend`
  text-decoration: 'strikethrough';
`;
```

## Internal/Experimental

Frequently we are asked to build things for internal consumption, either as operational tooling or as experimental work to prove the value of a possible feature. In this case you usually have no input from design until the work is productized for external consumption.

In this case, you will be building stuff almost exclusively using the components in `/primitives`. Fine tuning spacing and typography is typically not a requirement here and the defaults provided by Patchwork's space and type scales are sufficient to strike a balance between development speed and 'reasonable-looking-ness'.

You will find yourself writing **almost no CSS** in this case.

## WARNING:

In none of these cases should you use a custom color. Custom colors will cause whitelabeling to break, which will make the Enterprise team sad. You don't want them to be sad do you?

# Patchwork Concepts

Patchwork components are grouped into four folders:

## Primitives

Components in this folder are low-level building blocks, suitable for all use cases.

#### Color

They give you limited access to theme colors, using the `variant`, `fade`, and `inverted` properties. [See here for an in-depth discussion of how patchwork handles colors.](https://github.com/wealthsimple/patchwork/blob/master/src/mixins/branding/BRANDING.mkd).

#### Margins/Padding

These components also implement a strategy for consistent margins and padding, using the `spacing` property. Read more about the [space scale here](https://github.com/wealthsimple/patchwork/blob/master/src/mixins/spacing/SPACING.mkd).

#### Typography

Some primitives give you control over typography. Check out the stories to the left for `Head`, `Span`, and `Text` components.

#### Layout

`Box` also exposes a subset of flexbox via the `stacking` for your enjoyment. [Read about it here](https://github.com/wealthsimple/patchwork/blob/master/src/mixins/stacking/STACKING.mkd).

## Legacy

These are straight up ports of our legacy design system, [Fabric](https://fabric.wealthsimple.com/)/[WS-Directives](https://github.com/wealthsimple/ws-directives), to React. When you are porting AngularJS code to React without a design refresh, you will be using (and perhaps adding to) these components extensively.

## One-off

Sometimes, we get designs that are special. The odd piece of surprising UI allows for visual interest and expermentation from the design team. Any shared components from these designs end up here.

## Core

The new hotness. Components here should have a 1 to 1 mapping to the widget library the design team is building out in Sketch/Abstract.
