Skip to content

Commit 1b17639

Browse files
author
Ayesha Mazumdar
authored
fix(grid): Adjust docs to avoid confusion on columns and vertical alignment (#3265)
1 parent cbe5dcf commit 1b17639

File tree

1 file changed

+84
-64
lines changed

1 file changed

+84
-64
lines changed

Diff for: ui/utilities/grid/docs.mdx

+84-64
Original file line numberDiff line numberDiff line change
@@ -207,7 +207,7 @@ You can visually reorder columns independently from their position in the markup
207207

208208
## Column Nesting
209209

210-
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..
210+
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.
211211

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

222-
## Page Containers
222+
## Grid Flow
223223

224-
Optionally, you can contain your page content by adding the class `slds-container_width` to a top level element in your page structure.
224+
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.
225225

226-
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.
226+
### Left to Right
227227

228-
Class|Width
229-
---|---
230-
`slds-container_small`|480px
231-
`slds-container_medium`|768px
232-
`slds-container_large`|1024px
233-
`slds-container_x-large`|1280px
228+
The default flow is left to right on the horizontal axis
234229

235-
Additionally, you can center the content of your page by adding `slds-container_center`.
230+
<Example title="Grid Default Left to Right">
231+
<Grid columns="3" />
232+
</Example>
233+
234+
### Top to Bottom
235+
236+
To switch the grid to flow top to bottom on the vertical axis, add `slds-grid_vertical` to the `slds-grid` container.
237+
238+
<Example title="Grid Vertical Align">
239+
<Grid className="slds-grid_vertical">
240+
<Column>1</Column>
241+
<Column>2</Column>
242+
<Column>3</Column>
243+
</Grid>
244+
</Example>
245+
246+
### Reversed
247+
248+
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.
249+
250+
#### Right to Left
251+
252+
To reverse the horizontal flow, add the class `slds-grid_reverse` to the `slds-grid` container.
253+
254+
<Example title="Grid Horizontal Reversed">
255+
<Grid className="slds-grid_reverse">
256+
<Column>1</Column>
257+
<Column>2</Column>
258+
<Column>3</Column>
259+
</Grid>
260+
</Example>
261+
262+
#### Bottom to Top
263+
264+
To reverse the vertical flow, add the class `slds-grid_vertical-reverse` to the `slds-grid` container.
265+
266+
<Example title="Grid Vertical Align Reversed">
267+
<Grid className="slds-grid_vertical-reverse" style={{height: '200px'}}>
268+
<Column>1</Column>
269+
<Column>2</Column>
270+
<Column>3</Column>
271+
</Grid>
272+
</Example>
236273

237274
## Creating Responsive Layouts
238275

@@ -259,7 +296,7 @@ Below is an overview table outlining the default behavior for columns and how th
259296
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.
260297
</Blockquote>
261298

262-
### Mobile/Desktop Example
299+
#### Mobile/Desktop Example
263300

264301
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.
265302

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

273310
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.
274311

275-
### Mobile/Tablet/Desktop Example
312+
#### Mobile/Tablet/Desktop Example
276313

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

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

286323
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.
287324

288-
### Responsive Layout - Column Reordering
325+
#### Conditional Column Reordering
289326

290327
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`.
291328

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

299336
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.
300337

301-
## Horizontal Alignment
338+
## Alignment
302339

303340
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.
304341

305-
### Content centered
342+
### Horizontal Axis
343+
344+
#### Content centered
306345

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

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

317-
### Setting variable widths based on content
356+
#### Setting variable widths based on content
318357

319358
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.
320359

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

329-
### Content evenly spaced out
368+
#### Content evenly spaced out
330369

331370
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`.
332371

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

341-
### Content evenly spread out from edges
380+
#### Content evenly spread out from edges
342381

343382
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`.
344383

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

353-
### Content right justified
392+
#### Content right justified
354393

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

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

365-
### Content alignment with bump
404+
#### Content alignment with bump
366405

367406
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.
368407

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

399-
### Reversed
400-
401-
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.
402-
403-
<Example title="Grid Horizontal Reversed">
404-
<Grid className="slds-grid_reverse">
405-
<Column>1</Column>
406-
<Column>2</Column>
407-
<Column>3</Column>
408-
</Grid>
409-
</Example>
410-
411-
## Vertical Alignment
412-
413-
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.
438+
### Vertical Axis
414439

415-
<Example title="Grid Vertical Align">
416-
<Grid className="slds-grid_vertical">
417-
<Column>1</Column>
418-
<Column>2</Column>
419-
<Column>3</Column>
420-
</Grid>
421-
</Example>
422-
423-
<Blockquote>
424-
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.
440+
<Blockquote type="note" header="Implementation Note">
441+
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.
425442
</Blockquote>
426443

427-
### Content top
444+
#### Content top
428445

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

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

439-
### Content centered
456+
#### Content centered
440457

441458
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.
442459

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

451-
### Content bottom
468+
#### Content bottom
452469

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

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

463-
### Content absolutely centered
480+
#### Content absolutely centered
464481

465482
<Example title="Grid Vertical Align absolute center">
466483
<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
470487
</Grid>
471488
</Example>
472489

473-
### Reversed
474-
475-
To reverse the vertical flow, add the class `slds-grid_vertical-reverse` to the `slds-grid` container.
476-
477-
<Example title="Grid Vertical Align reversed">
478-
<Grid className="slds-grid_vertical-reverse" style={{height: '200px'}}>
479-
<Column>1</Column>
480-
<Column>2</Column>
481-
<Column>3</Column>
482-
</Grid>
483-
</Example>
484-
485-
### Individual alignment
490+
#### Individual alignment
486491

487492
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.
488493

@@ -493,3 +498,18 @@ To specify the vertical placement of grid items on the cross axis, you can apply
493498
<Column className="slds-align-bottom">3</Column>
494499
</Grid>
495500
</Example>
501+
502+
## Page Containers
503+
504+
Optionally, you can contain your page content by adding the class `slds-container_width` to a top level element in your page structure.
505+
506+
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.
507+
508+
Class|Width
509+
---|---
510+
`slds-container_small`|480px
511+
`slds-container_medium`|768px
512+
`slds-container_large`|1024px
513+
`slds-container_x-large`|1280px
514+
515+
Additionally, you can center the content of your page by adding `slds-container_center`.

0 commit comments

Comments
 (0)