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 React = require('react');
const { default: Button } = require('../button');

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