Skip to content
Permalink
Browse files

fix(grid): Adjust docs to avoid confusion on columns and vertical ali…

…gnment (#3265)
  • Loading branch information...
Ayesha Mazumdar
Ayesha Mazumdar committed May 14, 2018
1 parent cbe5dcf commit 1b1763900e2f22b292d3884768444cd888e020d6
Showing with 84 additions and 64 deletions.
  1. +84 −64 ui/utilities/grid/docs.mdx
@@ -207,7 +207,7 @@ You can visually reorder columns independently from their position in the markup

## Column Nesting

Nesting columns is simple and can add more flexibility in your designs. In a column, you can add a nested grid by creating another `slds-grid` container and as many `slds-col` elements inside of that container as you need..
Nesting columns is simple and can add more flexibility in your designs. In a column, you can add a nested grid by creating another `slds-grid` container and as many `slds-col` elements inside of that container as you need.

<Example title="Grid Column Nesting">
<Grid className="slds-wrap">
@@ -219,20 +219,57 @@ Nesting columns is simple and can add more flexibility in your designs. In a col
</Grid>
</Example>

## Page Containers
## Grid Flow

Optionally, you can contain your page content by adding the class `slds-container_width` to a top level element in your page structure.
Once an `slds-grid` has been set, you can change things like flow. By *default*, a grid flows left to right on the main horizontal axis. You can easily switch your grid to flow top to bottom on a vertical axis by adding `slds-grid_vertical` to the `slds-grid` container.

Containers come in 4 widths, __small__, __medium__, __large__ and __x-large__. They are rendered using `max-width`. This means your content will be a fluid width until it reaches the width the modifier has set on the container.
### Left to Right

Class|Width
---|---
`slds-container_small`|480px
`slds-container_medium`|768px
`slds-container_large`|1024px
`slds-container_x-large`|1280px
The default flow is left to right on the horizontal axis

Additionally, you can center the content of your page by adding `slds-container_center`.
<Example title="Grid Default Left to Right">
<Grid columns="3" />
</Example>

### Top to Bottom

To switch the grid to flow top to bottom on the vertical axis, add `slds-grid_vertical` to the `slds-grid` container.

<Example title="Grid Vertical Align">
<Grid className="slds-grid_vertical">
<Column>1</Column>
<Column>2</Column>
<Column>3</Column>
</Grid>
</Example>

### Reversed

There may be times you find yourself in a situation to reverse the visual flow of your columns. You can do this both horizontally and vertically.

#### Right to Left

To reverse the horizontal flow, add the class `slds-grid_reverse` to the `slds-grid` container.

<Example title="Grid Horizontal Reversed">
<Grid className="slds-grid_reverse">
<Column>1</Column>
<Column>2</Column>
<Column>3</Column>
</Grid>
</Example>

#### Bottom to Top

To reverse the vertical flow, add the class `slds-grid_vertical-reverse` to the `slds-grid` container.

<Example title="Grid Vertical Align Reversed">
<Grid className="slds-grid_vertical-reverse" style={{height: '200px'}}>
<Column>1</Column>
<Column>2</Column>
<Column>3</Column>
</Grid>
</Example>

## Creating Responsive Layouts

@@ -259,7 +296,7 @@ Below is an overview table outlining the default behavior for columns and how th
Note: To make sure columns wrap as they exceed a total column count of 12, responsive layouts require <code className="doc">slds-wrap</code> to be added to the <code className="doc">slds-grid</code> container.
</Blockquote>

### Mobile/Desktop Example
#### Mobile/Desktop Example

Since we build on the concept of mobile first, let's set a layout for mobile and override for desktop directly in our HTML. We do this by setting a mobile, in this case default widths to our columns and override the layout when we meet the criteria of a desktop viewport size.

@@ -272,9 +309,9 @@ Since we build on the concept of mobile first, let's set a layout for mobile and

In the above example, we are setting a stacked layout for mobile/tablet devices and then when our viewport exceeds a width of 1024px we redraw our layout to be a nice two column where the primary content area takes up 8 columns and the secondary content area takes up 4 columns.

### Mobile/Tablet/Desktop Example
#### Mobile/Tablet/Desktop Example

If our designs need a bit more flexibility, we can accomplish that by establishing different layouts for mobile, tablets and desktops.
If our designs need a bit more flexibility, we can accomplish that by establishing different layouts for mobile, tablet, and desktop.

<Example title="Grid Responsive 2 col mobile tablet desktop">
<Grid className="slds-wrap">
@@ -285,7 +322,7 @@ If our designs need a bit more flexibility, we can accomplish that by establishi

In this above example, we are setting our default stacked layout and when our browser exceeds a viewport width of 768px, we adjust the layout for each column to take up 50% or 6 columns of the slds-grid container. Then once we exceed a viewport width of 1024px, we again redraw a layout to be a nice 66% or 8 columns for the primary content area and 33% or 4 columns for the secondary content area.

### Responsive Layout - Column Reordering
#### Conditional Column Reordering

With flexbox it's easy to reorder your columns visually. Luckily with the SLDS grid system it's easy to reorder visually in a responsive manner! Following the same naming convention as sizing, we'll want to prefix `slds-order` with our breakpoint name and pass in an integer for where you want it visually. The lowest value is the first in order. If no order is defined, standard ordering is applied. This means that a column with no order class will render before `slds-order_1`.

@@ -298,11 +335,13 @@ With flexbox it's easy to reorder your columns visually. Luckily with the SLDS g

In the above example, we're setting our first column to be last in the order of 3. Then once your viewport exceeds a width of 1024px, we're changing the visual order of our first column back to 1. Now this seemed rather long winded to move 1 column. Below is an easy way of letting the column know you only want to reorder the first column if it's in a viewport smaller than 480px. This breaks the convention of mobile first and should be used sparingly.

## Horizontal Alignment
## Alignment

Since the grids are built on flexbox, they allow us to do some interesting things with alignment on both a horizontal axis and vertical axis. You can add an alignment utility to the `slds-grid` container.

### Content centered
### Horizontal Axis

#### Content centered

If you want your columns to grow from the the center of the horizontal axis, apply the class `slds-grid_align-center`.

@@ -314,7 +353,7 @@ If you want your columns to grow from the the center of the horizontal axis, app
</Grid>
</Example>

### Setting variable widths based on content
#### Setting variable widths based on content

Another powerful technique is letting a column shrink to the width of the content inside of it, while explicitly setting widths to other columns. This is achieved by using the `slds-shrink-none` or `slds-grow-none` utility classes or simply removing the `slds-col` class from the column element.

@@ -326,7 +365,7 @@ Another powerful technique is letting a column shrink to the width of the conten
</Grid>
</Example>

### Content evenly spaced out
#### Content evenly spaced out

To evenly distribute columns on the horizontal axis with an equal amount of white space separating the columns, apply the class `slds-grid_align-space`.

@@ -338,7 +377,7 @@ To evenly distribute columns on the horizontal axis with an equal amount of whit
</Grid>
</Example>

### Content evenly spread out from edges
#### Content evenly spread out from edges

To spread out your columns on the horizontal axis, with the first column starting at the start of your main axis and last item ending at the far end of your main axis, apply the class `slds-grid_align-spread`.

@@ -350,7 +389,7 @@ To spread out your columns on the horizontal axis, with the first column startin
</Grid>
</Example>

### Content right justified
#### Content right justified

If you want your columns to grow from the end of the horizontal axis, apply the class `slds-grid_align-end`.

@@ -362,7 +401,7 @@ If you want your columns to grow from the end of the horizontal axis, apply the
</Grid>
</Example>

### Content alignment with bump
#### Content alignment with bump

To "bump" a single or multiple grid items, apply the class `slds-col_bump-{direction}`, with `{direction}` being either left, right, top or bottom, to a grid item.

@@ -396,35 +435,13 @@ In the example below, applying the right bump class to item 5 bumps item 6 to th
</Grid>
</Example>

### Reversed

There may be times you find yourself in a situation to reverse the visual flow of your columns, you can do this both horizontally and vertically. To reverse the horizontal flow, add the class `slds-grid_reverse` to the `slds-grid` container. To reverse the vertical flow, add the class `slds-grid_vertical-reverse` to the `slds-grid` container.

<Example title="Grid Horizontal Reversed">
<Grid className="slds-grid_reverse">
<Column>1</Column>
<Column>2</Column>
<Column>3</Column>
</Grid>
</Example>

## Vertical Alignment

Once an `slds-grid` has been set, you can change things like flow. By default, a grid flows left to right on the main horizontal axis. You can easily switch your grid to flow top to bottom on a vertical axis by adding `slds-grid_vertical` to the `slds-grid` container.
### Vertical Axis

<Example title="Grid Vertical Align">
<Grid className="slds-grid_vertical">
<Column>1</Column>
<Column>2</Column>
<Column>3</Column>
</Grid>
</Example>

<Blockquote>
Note, to vertically align elements on a cross-axis of a `slds-grid` container, the elements need available vertical white space. This is usually achieved by having a height applied to the `slds-grid` container.
<Blockquote type="note" header="Implementation Note">
To vertically align elements on a cross-axis of a `slds-grid` container, the elements need available vertical white space. This is usually achieved by having a height applied to the `slds-grid` container.
</Blockquote>

### Content top
#### Content top

To align a single row or multi-line rows to the beginning of the cross axis, apply the class `slds-grid_vertical-align-start`.

@@ -436,7 +453,7 @@ To align a single row or multi-line rows to the beginning of the cross axis, app
</Grid>
</Example>

### Content centered
#### Content centered

To vertically center align a single row or multi-line rows to the height of a `slds-grid` container, apply the class `slds-grid_vertical-align-center`. When `slds-grid_vertical-align-center` is used in conjunction with `slds-grid_align-center`, the outcome would horizontally and vertically center align your content in the center of the `slds-grid` container.

@@ -448,7 +465,7 @@ To vertically center align a single row or multi-line rows to the height of a `s
</Grid>
</Example>

### Content bottom
#### Content bottom

To align a single row or multi-line rows to the end of the cross axis, apply the class `slds-grid_vertical-align-end`.

@@ -460,7 +477,7 @@ To align a single row or multi-line rows to the end of the cross axis, apply the
</Grid>
</Example>

### Content absolutely centered
#### Content absolutely centered

<Example title="Grid Vertical Align absolute center">
<Grid className="slds-grid_vertical-align-center slds-grid_align-center" style={{height: '200px'}}>
@@ -470,19 +487,7 @@ To align a single row or multi-line rows to the end of the cross axis, apply the
</Grid>
</Example>

### Reversed

To reverse the vertical flow, add the class `slds-grid_vertical-reverse` to the `slds-grid` container.

<Example title="Grid Vertical Align reversed">
<Grid className="slds-grid_vertical-reverse" style={{height: '200px'}}>
<Column>1</Column>
<Column>2</Column>
<Column>3</Column>
</Grid>
</Example>

### Individual alignment
#### Individual alignment

To specify the vertical placement of grid items on the cross axis, you can apply `slds-align-top`, `slds-align-middle`, and `slds-align-bottom` to a `slds-col` element.

@@ -493,3 +498,18 @@ To specify the vertical placement of grid items on the cross axis, you can apply
<Column className="slds-align-bottom">3</Column>
</Grid>
</Example>

## Page Containers

Optionally, you can contain your page content by adding the class `slds-container_width` to a top level element in your page structure.

Containers come in 4 widths, __small__, __medium__, __large__ and __x-large__. They are rendered using `max-width`. This means your content will be a fluid width until it reaches the width the modifier has set on the container.

Class|Width
---|---
`slds-container_small`|480px
`slds-container_medium`|768px
`slds-container_large`|1024px
`slds-container_x-large`|1280px

Additionally, you can center the content of your page by adding `slds-container_center`.

0 comments on commit 1b17639

Please sign in to comment.
You can’t perform that action at this time.