Skip to content

Commit

Permalink
Updated readme.
Browse files Browse the repository at this point in the history
  • Loading branch information
@mattvox
mattvox committed Jun 25, 2018
1 parent 6e1d39e commit a915a29
Showing 1 changed file with 46 additions and 36 deletions.
82 changes: 46 additions & 36 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,7 @@ npm install --save brickworks
Brickworks makes use of a modest list of peer dependencies, including Prop Types and Styled Components. Make sure to install those too.

```bash
yarn add react prop-types styled-components
yarn add prop-types styled-components
# or with npm
npm install --save prop-types styled-components
```
Expand All @@ -57,7 +57,7 @@ npm install --save prop-types styled-components

#### The most basic grid setup

Creates a basic grid with one row and three columns. By default, Brickworks makes no assumptions when it comes to padding or margin. Without any props, you simply get the Flexbox defaults, with Grid representing a container, and the child Col components its items.
Creates a grid with one row of equally-spaced columns.

```jsx
import React, { Component } from 'react';
Expand All @@ -67,9 +67,11 @@ class Example extends Component {
render() {
return (
<Grid>
<Col />
<Col />
<Col />
<Row>
<Col>1</Col>
<Col>2</Col>
<Col>3</Col>
</Row>
</Grid>
);
}
Expand All @@ -78,28 +80,31 @@ class Example extends Component {

#### Responsive three-column layout with gutters

The `Row` component can be added to introduce another level of control over its child `Col` components, enabling quick and easy creation of more complex layouts. With a few props we now have three equal-width columns with a `1em` gutter.
Creates a grid with one row of exactly three columns. Since this example grid has six total column components, they will wrap, creating a stacked layout.

```jsx
<Grid>
<Row columns={3}>
<Col />
<Col />
<Col />
<Col>1</Col>
<Col>2</Col>
<Col>3</Col>
<Col>4</Col>
<Col>5</Col>
<Col>6</Col>
</Row>
</Grid>
```

#### Responsive three-column layout with gutters, but centered with a maximum width
#### Responsive three-column layout with a maximum width

We can also give our grid a max width and center it automatically by passing it the `maxWidth` and `centered` prop.
We can also give our grid a max width. It's child components are centered by default.

```jsx
<Grid centered maxWidth={1000}>
<Grid maxWidth={800}>
<Row columns={3}>
<Col />
<Col />
<Col />
<Col>1</Col>
<Col>2</Col>
<Col>3</Col>
</Row>
</Grid>
```
Expand All @@ -111,18 +116,28 @@ Brickworks also makes working with different breakpoints a breeze. Our basic gri
By default, child `Col` components will stack or wrap based on the column count at each breakpoint. In this example with six columns, we'll get two rows of equally-spaced `Col` components on medium-sized screens or larger, three rows of two columns on small screens, and six rows of one column on extra small screens.

```jsx
<Grid centered maxWidth={1000}>
<Grid>
<Row xs={1} sm={2} md={3}>
<Col />
<Col />
<Col />
<Col />
<Col />
<Col />
<Col>1</Col>
<Col>2</Col>
<Col>3</Col>
<Col>4</Col>
<Col>5</Col>
<Col>6</Col>
</Row>
</Grid>
```

## Building Layouts with Brickworks

Brickworks enforces a grid > row > columns convention (similar to Bootstrap and Semantic), and its defaults are based on this implementation pattern. It's built with flexbox and is fully responsive right out of the box.

`Grid` components function as containers for your layout, effectively managing the padding and margin of their child `Row` and `Col` components. They should exist as high up the component tree as possible and not be nested within each other, or other `Row` or `Col` components.

`Row` components serve as wrappers for columns. They can control the width of their child columns through props and media breakpoints.

`Col` components serve as wrappers for your content. Content should never be placed directly inside a `Grid` or `Row`.

## Props

Brickworks layout components are configured through props. It aims to make available all the configuration necessary to create beautiful and complex layouts without any additional 'clutter'. All Brickworks components are composed with a base set of 'style' props available any component in the library.
Expand All @@ -142,20 +157,15 @@ Brickworks layout components are configured through props. It aims to make avail

Grid is a container component, typically managing a combination of rows and columns.

| Prop | Default | Type | Description |
| -------------- | --------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `flow` | `inherit` | enum | shorthand for flex-direction and flex-wrap, which define the container's axes<br> `row` `row-reverse` `column` `column-reverse` `nowrap` `wrap` `wrap-reverse` `row nowrap` `row wrap` `row wrap-reverse` `row-reverse nowrap` `row-reverse wrap` `row-reverse wrap-reverse` `column nowrap` `column wrap` `column wrap-reverse` `column-reverse nowrap` `column-reverse wrap` `column-reverse wrap-reverse` `initial` `inherit` |
| `justify` | `inherit` | enum | sets alignment of items along the main axis<br> `flex-start` `flex-end` `center` `space-around` `space-between` `space-evenly` `initial` `inherit` |
| `alignContent` | `inherit` | enum | sets alignment of the container's lines along the cross-axis<br> `flex-start` `flex-end` `center` `space-around` `space-between` `stretch` `initial` `inherit` |
| `alignItems` | `inherit` | enum | sets alignment of items along the cross-axis<br> `flex-start` `flex-end` `center` `baseline` `stretch` `initial` `inherit` |
| `spacing` | `1em` | bool / number / string | A grid can be spaced, which creates equally-spaced gutters both horizontally and vertically. `spacing` can be used simply as a boolean to apply the default padding, or as a number or string which is a valid css value with a unit, i.e. `'20px'`, `'1.5rem'` |
| `columns` | | number | A grid can specify its column count. |
| `xs` | | number | A grid can specify its column count for extra-small screens. Brickworks' mobile-first approach makes this the default, so no media query exists for the smallest setting. This is effectively equal to setting the `columns` prop, but provides a more semantic and readable option when utilizing other sizing props on the same component. |
| `sm` | | number | A grid can specify its column count for small screens. default: `(min-width: 576px)` |
| `md` | | number | A grid can specify its column count for medium-sized screens. default `(min-width: 768px)` |
| `lg` | | number | A grid can specify its column count for large screens. default: `(min-width: 992px)` |
| `xl` | | number | A grid can specify its column count for small screens. default: `(min-width: 1200px)` |
| `breakpoints` | | object | A grid can specify its own breakpoints to be used within various media queries. _needs more docs_ |
| Prop | Default | Type | Description |
| -------------- | ---------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `flow` | `row wrap` | enum | shorthand for flex-direction and flex-wrap, which define the container's axes<br> `row` `row-reverse` `column` `column-reverse` `nowrap` `wrap` `wrap-reverse` `row nowrap` `row wrap` `row wrap-reverse` `row-reverse nowrap` `row-reverse wrap` `row-reverse wrap-reverse` `column nowrap` `column wrap` `column wrap-reverse` `column-reverse nowrap` `column-reverse wrap` `column-reverse wrap-reverse` `initial` `inherit` |
| `justify` | `center` | enum | sets alignment of items along the main axis<br> `flex-start` `flex-end` `center` `space-around` `space-between` `space-evenly` `initial` `inherit` |
| `alignContent` | | enum | sets alignment of the container's lines along the cross-axis<br> `flex-start` `flex-end` `center` `space-around` `space-between` `stretch` `initial` `inherit` |
| `alignItems` | | enum | sets alignment of items along the cross-axis<br> `flex-start` `flex-end` `center` `baseline` `stretch` `initial` `inherit` |
| `spacing` | `1em` | bool / number / string | A grid can be spaced, which creates equally-spaced gutters both horizontally and vertically. `spacing` can be used simply as a boolean to apply the default padding, or as a number or string which is a valid css value with a unit, i.e. `'20px'`, `'1.5rem'` |
| `noSpacing` | | bool | Removes/overwrites any spacing applied by default or through the `spacing` prop on ALL child rows and columns. |
| `breakpoints` | | object | A grid can specify its own breakpoints to be used within various media queries. _needs more docs_ |

## `<Row />`

Expand Down

0 comments on commit a915a29

Please sign in to comment.