joyent-portal/packages/ui-toolkit/src/baseline/readme.md

In the mockups, the spacing between elements is done through a baseline grid.

What that means is that spacing is measured in `units` over a `base`. I.e. `1.5 unit` where the base is `6px` corresponds to `9px`.

{insert image from sketch}

To allow a declarative way of defining spacing in every component in our UI framework, a composer was written that styles each component instance with based on the props passed to it. E.g.:

```html
<Button margin='2'>Hello World</Button>
```

Is going to translate into a `<Button />` that has `12px` of margin.

What enables this is the [`Baseline` composer](https://github.com/yldio/joyent-portal/blob/a5774063ed8caf2569aff2905af2d7dca7a01a52/ui/src/shared/composers/index.js#L51). 

The Baseline composer is essentially an [HOC](https://medium.com/@dan_abramov/mixins-are-dead-long-live-higher-order-components-94a0d2f9e750): It exposes a function that accepts a Component as a parameter. That component is then wrapped in a [styled-component](https://github.com/styled-components/styled-components#overriding-component-styles). 

The `styled-component` that wraps the Component just goes through a list of supported rules - see list below. From each rule it does the match to the corresponding prop and calculates the `rem`.

List of supported props:

 - `border`
 - `margin`
 - `marginTop`
 - `marginRight`
 - `marginBottom`
 - `marginLeft`
 - `padding`
 - `paddingTop`
 - `paddingRight`
 - `paddingBottom`
 - `paddingLeft`
 - `borderTopWidth`
 - `borderRightWidth`
 - `borderBottomWidth`
 - `borderLeftWidth`

To use this composer, you just do it as you would with any other HOC:

```js static
// component implementation
const Button = (props) => (
  <button>my button</button>
);

// export Button wrapped
export default Baseline(Button);
```

Whoever required that `<Button />`, will be able to declare any of the properties especified above and have the style of the component be applied accordingly.


#### examples

```
const Button = require('../button').default;

<span>
  <Button marginRight='1'>margin-right: 1</Button>
  <Button marginRight='2'>margin-right: 2</Button>
  <Button marginRight='3'>margin-right: 3</Button>
  <Button marginRight='4'>margin-right: 4</Button>
  <Button>hello</Button>
</span>
```