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?
