Skip to content

Commit c769a11

Browse files
shawnbotshawnbot
committed
Merge branch 'moar_docs' into exact-versions
2 parents a318de1 + c476d93 commit c769a11

File tree

10 files changed

+1005
-5
lines changed

10 files changed

+1005
-5
lines changed

‎modules/primer-layout/docs/grid.md‎

Lines changed: 390 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,390 @@
1+
---
2+
title: Grid
3+
status: New release
4+
status_issue: https://github.com/github/design-systems/issues/88
5+
source: https://github.com/primer/primer-css/blob/master/modules/primer-layout/lib/grid.scss
6+
---
7+
8+
The grid is 12 columns and percentage-based. The number of columns a container spans can be adjusted across breakpoints for responsive layouts. The grid system works with a variety of layout utilities to achieve different results.
9+
10+
{:toc}
11+
12+
## Float based grid
13+
14+
Use `.clearfix` on the container and float utilities with columns for a floated grid layout.
15+
16+
```html
17+
<div class="container-lg clearfix">
18+
<div class="col-4 float-left border p-4">
19+
My column
20+
</div>
21+
<div class="col-4 float-left border p-4">
22+
Looks better
23+
</div>
24+
<div class="col-4 float-left border p-4">
25+
Than your column
26+
</div>
27+
</div>
28+
```
29+
30+
### Reversed grid
31+
32+
To reverse the order of columns, use `float-right` to float columns to the right.
33+
34+
```html
35+
<div class="container-lg clearfix">
36+
<div class="col-4 float-right border p-4">
37+
One
38+
</div>
39+
<div class="col-4 float-right border p-4">
40+
Two
41+
</div>
42+
<div class="col-4 float-right border p-4">
43+
Three
44+
</div>
45+
</div>
46+
```
47+
48+
## Nesting
49+
You can infinitely nest grid layouts within other columns since the column widths are percentage based. With great flexibility comes great responsibility - be sensible with how far you nest!
50+
51+
```html
52+
<div class="clearfix">
53+
<div class="col-6 float-left px-1">
54+
<div class="border p-1">Unnested</div>
55+
</div>
56+
<div class="col-6 float-left">
57+
<div class="clearfix">
58+
<div class="col-6 float-left px-1">
59+
<div class="border p-1">1 x Nested</div>
60+
</div>
61+
<div class="col-6 float-left">
62+
<div class="col-6 float-left px-1">
63+
<div class="border p-1">2 x Nested</div>
64+
</div>
65+
<div class="col-6 float-left px-1">
66+
<div class="border p-1">2 x Nested</div>
67+
</div>
68+
</div>
69+
</div>
70+
</div>
71+
</div>
72+
```
73+
74+
## Centering a column
75+
76+
Use `.mx-auto` to center columns within a container.
77+
```html
78+
<div class="border">
79+
<div class="col-6 p-2 mx-auto border">
80+
This column is the center of my world.
81+
</div>
82+
</div>
83+
```
84+
85+
86+
## Column widths
87+
Column widths can be used with any other block or inline-block elements to add percentage-based widths.
88+
```html
89+
<div>
90+
<div class="col-4 float-right p-2 border text-red">
91+
<%= octicon "heart" %> Don't go bacon my heart.
92+
</div>
93+
<p>T-bone drumstick alcatra ribeye. Strip steak chuck andouille tenderloin bacon tri-tip ball tip beef capicola rump. Meatloaf bresaola drumstick ball tip salami. Drumstick ham bacon alcatra pig porchetta, spare ribs leberkas pork belly.</p>
94+
</div>
95+
```
96+
97+
## Offset columns
98+
99+
Using column offset classes can push a div over X number of columns. They work responsively using the [breakpoints outlined below](/styleguide/css/modules/grid#responsive-grids).
100+
101+
```html
102+
<div class="clearfix">
103+
<div class="offset-1 col-3 border p-3">.offset-1</div>
104+
<div class="offset-2 col-3 border p-3">.offset-2</div>
105+
</div>
106+
```
107+
108+
## Gutters
109+
Use gutter styles or padding utilities to create gutters. You can use the default gutter style, `gutter`, or either of its modifiers, `gutter-condensed` or `gutter-spacious`. Gutter styles also support responsive breakpoint modifiers. Gutter styles add padding to the left and right side of each column and apply a negative margin to the container to ensure content inside each column lines up with content outside of the grid.
110+
111+
```html
112+
<div class="clearfix gutter-md-spacious border">
113+
<div class="col-3 float-left">
114+
<div class="border p-3">.col-md-3</div>
115+
</div>
116+
<div class="col-3 float-left">
117+
<div class="border p-3">.col-md-3</div>
118+
</div>
119+
<div class="col-3 float-left">
120+
<div class="border p-3">.col-md-3</div>
121+
</div>
122+
<div class="col-3 float-left">
123+
<div class="border p-3">.col-md-3</div>
124+
</div>
125+
</div>
126+
```
127+
128+
Use padding utilities to create gutters for more customized layouts.
129+
130+
```html
131+
<div class="container-lg clearfix">
132+
<div class="col-3 float-left pr-2 mb-3">
133+
<div class="border bg-gray-light">.pr-2</div>
134+
</div>
135+
<div class="col-3 float-left px-2 mb-3">
136+
<div class="border bg-gray-light">.px-2</div>
137+
</div>
138+
<div class="col-3 float-left px-2 mb-3">
139+
<div class="border bg-gray-light">.px-2</div>
140+
</div>
141+
<div class="col-3 float-left pl-2 mb-3">
142+
<div class="border bg-gray-light">.pl-2</div>
143+
</div>
144+
</div>
145+
<div class="container-lg clearfix">
146+
<div class="col-3 float-left pr-2">
147+
<div class="border bg-gray-light">.pr-2</div>
148+
</div>
149+
<div class="col-9 float-left pl-2">
150+
<div class="border bg-gray-light">.pl-2</div>
151+
</div>
152+
</div>
153+
```
154+
155+
156+
## Inline-block grids
157+
Use column widths with `d-inline-block` as an alternative to floated grids.
158+
159+
```html
160+
<div>
161+
<div class="col-4 d-inline-block border">
162+
.col-4 .d-inline-block
163+
</div><!--
164+
--><div class="col-4 d-inline-block border">
165+
.col-4 .d-inline-block
166+
</div><!--
167+
--><div class="col-4 d-inline-block border">
168+
.col-4 .d-inline-block
169+
</div>
170+
</div>
171+
```
172+
173+
You can use column widths and other utilities on elements such as lists to create the layout you need while keeping the markup semantically correct.
174+
```html
175+
<ul class="list-style-none">
176+
<li class="d-inline-block col-2 p-2"><img class="width-full avatar" src="/broccolini.png" alt="broccolini" /></li><!--
177+
--><li class="d-inline-block col-2 p-2"><img class="width-full avatar" src="/jonrohan.png" alt="jonrohan" /></li><!--
178+
--><li class="d-inline-block col-2 p-2"><img class="width-full avatar" src="/muan.png" alt="muan" /></li><!--
179+
--><li class="d-inline-block col-2 p-2"><img class="width-full avatar" src="/pmarsceill.png" alt="pmarsceill" /></li><!--
180+
--><li class="d-inline-block col-2 p-2"><img class="width-full avatar" src="/sophshep.png" alt="sophshep" /></li><!--
181+
--><li class="d-inline-block col-2 p-2"><img class="width-full avatar" src="/cmwinters.png" alt="cmwinters" /></li><!--
182+
--><li class="d-inline-block col-2 p-2"><img class="width-full avatar" src="/jeejkang.png" alt="jeejkang" /></li><!--
183+
--><li class="d-inline-block col-2 p-2"><img class="width-full avatar" src="/mdo.png" alt="mdo" /></li>
184+
</ul>
185+
```
186+
187+
188+
## Display table grids
189+
Using [display table utilities](/styleguide/css/utilities/layout#display) with columns gives you some alternative layout options.
190+
191+
A useful example is being able to keep the height of the container equal across a row when the length of content may differ.
192+
193+
```html
194+
<div class="d-table col-12">
195+
<div class="col-4 d-table-cell border p-2">
196+
Bacon ipsum dolor amet leberkas pork pig kielbasa shankle ribeye meatball, salami alcatra venison.
197+
</div><!--
198+
--><div class="col-4 d-table-cell border p-2">
199+
Pork chop cupim cow turkey frankfurter, landjaeger fatback hamburger meatball salami spare ribs. Rump tenderloin salami, hamburger frankfurter landjaeger andouille.
200+
</div><!--
201+
--><div class="col-4 d-table-cell border p-2">
202+
Brisket tongue frankfurter cupim strip steak rump picanha pancetta pork pig kevin pastrami biltong. Shankle venison meatball swine sausage ground round. Tail pork loin ribeye kielbasa short ribs pork chop.
203+
</div>
204+
</div>
205+
```
206+
You can also create an alternative [media object](/styleguide/css/utilities/layout#the-media-object) layout with `.display-table` and column widths.
207+
208+
```html
209+
<div class="d-table col-12">
210+
<div class="col-2 d-table-cell v-align-middle">
211+
<img class="width-full avatar" src="/github.png" alt="github" />
212+
</div>
213+
<div class="col-10 d-table-cell v-align-middle pl-4">
214+
<h1 class="text-normal lh-condensed">GitHub</h1>
215+
<p class="h4 text-gray text-normal mb-2">How people build software.</p>
216+
<a class="text-gray text-small" href="#url">https://github.com/about</a>
217+
</div>
218+
</div>
219+
```
220+
221+
Note that table cells will fill the width of their container even when the total columns doesn't add up to 12.
222+
223+
```html
224+
<div class="d-table col-12">
225+
<div class="col-4 d-table-cell border">
226+
.col-4 .d-table-cell
227+
</div><!--
228+
--><div class="col-4 d-table-cell border">
229+
.col-4 .d-table-cell
230+
</div><!--
231+
--><div class="col-2 d-table-cell border">
232+
.col-2 .d-table-cell
233+
</div>
234+
</div>
235+
```
236+
237+
## Flexbox grids
238+
239+
You can use [flex utilities](/styleguide/css/utilities/flexbox) on the container and columns to create a flexbox grid.
240+
241+
This can be useful for keeping columns the same height, justifying content and vertically aligning items. The flexbox grid is also great for working with responsive layouts.
242+
243+
```html
244+
<div class="d-flex flex-column flex-md-row flex-items-center flex-md-items-center">
245+
<div class="col-2 d-flex flex-items-center flex-items-center flex-md-items-start">
246+
<img class="width-full avatar mb-2 mb-md-0" src="/github.png" alt="github" />
247+
</div>
248+
<div class="col-12 col-md-10 d-flex flex-column flex-justify-center flex-items-center flex-md-items-start pl-md-4">
249+
<h1 class="text-normal lh-condensed">GitHub</h1>
250+
<p class="h4 text-gray text-normal mb-2">How people build software.</p>
251+
<a class="text-gray text-small" href="#url">https://github.com/about</a>
252+
</div>
253+
</div>
254+
```
255+
256+
257+
## Responsive grids
258+
All the column width classes can be set per breakpoint to create responsive grid layouts. Each responsive style is applied to the specified breakpoint and up.
259+
260+
### Breakpoints
261+
We use abbreviations for each breakpoint to keep the class names concise.
262+
263+
| Shorthand | Description |
264+
| --- | --- |
265+
| sm | min-width: 544px |
266+
| md | min-width: 768px |
267+
| lg | min-width: 1004px |
268+
| xl | min-width: 1280px |
269+
270+
**Note:** The `lg` breakpoint matches our current page width of `980px` including left and right padding of `12px`. This is so that content doesn't touch the edges of the window when resized.
271+
272+
<hr />
273+
274+
In this example at the `sm` breakpoint 2 columns will show, at the `md` breakpoint 4 columns will show, and at the `lg` breakpoint 6 columns will show.
275+
276+
```html
277+
<div class="container-lg clearfix">
278+
<div class="col-sm-6 col-md-3 col-lg-2 float-left p-2 border">
279+
.col-sm-6 .col-md-3 .col-lg-2
280+
</div>
281+
<div class="col-sm-6 col-md-3 col-lg-2 float-left p-2 border">
282+
.col-sm-6 .col-md-3 .col-lg-2
283+
</div>
284+
<div class="col-sm-6 col-md-3 col-lg-2 float-left p-2 border">
285+
.col-sm-6 .col-md-3 .col-lg-2
286+
</div>
287+
<div class="col-sm-6 col-md-3 col-lg-2 float-left p-2 border">
288+
.col-sm-6 .col-md-3 .col-lg-2
289+
</div>
290+
<div class="col-sm-6 col-md-3 col-lg-2 float-left p-2 border">
291+
.col-sm-6 .col-md-3 .col-lg-2
292+
</div>
293+
<div class="col-sm-6 col-md-3 col-lg-2 float-left p-2 border">
294+
.col-sm-6 .col-md-3 .col-lg-2
295+
</div>
296+
</div>
297+
```
298+
299+
For demonstration, this is how the above example would look at the `sm` breakpoint.
300+
301+
```html
302+
<div class="container-lg clearfix">
303+
<div class="col-sm-6 float-left p-2 border">
304+
.col-sm-6
305+
</div>
306+
<div class="col-sm-6 float-left p-2 border">
307+
.col-sm-6
308+
</div>
309+
<div class="col-sm-6 float-left p-2 border">
310+
.col-sm-6
311+
</div>
312+
<div class="col-sm-6 float-left p-2 border">
313+
.col-sm-6
314+
</div>
315+
<div class="col-sm-6 float-left p-2 border">
316+
.col-sm-6
317+
</div>
318+
<div class="col-sm-6 float-left p-2 border">
319+
.col-sm-6
320+
</div>
321+
</div>
322+
```
323+
This is how that same example would look at the `md` breakpoint.
324+
325+
```html
326+
<div class="container-lg clearfix">
327+
<div class="col-md-3 float-left p-2 border">
328+
.col-md-3
329+
</div>
330+
<div class="col-md-3 float-left p-2 border">
331+
.col-md-3
332+
</div>
333+
<div class="col-md-3 float-left p-2 border">
334+
.col-md-3
335+
</div>
336+
<div class="col-md-3 float-left p-2 border">
337+
.col-md-3
338+
</div>
339+
<div class="col-md-3 float-left p-2 border">
340+
.col-md-3
341+
</div>
342+
<div class="col-md-3 float-left p-2 border">
343+
.col-md-3
344+
</div>
345+
</div>
346+
```
347+
348+
This is how that example would look at the `lg` breakpoint.
349+
350+
```html
351+
<div class="container-lg clearfix">
352+
<div class="col-lg-2 float-left p-2 border">
353+
.col-lg-2
354+
</div>
355+
<div class="col-lg-2 float-left p-2 border">
356+
.col-lg-2
357+
</div>
358+
<div class="col-lg-2 float-left p-2 border">
359+
.col-lg-2
360+
</div>
361+
<div class="col-lg-2 float-left p-2 border">
362+
.col-lg-2
363+
</div>
364+
<div class="col-lg-2 float-left p-2 border">
365+
.col-lg-2
366+
</div>
367+
<div class="col-lg-2 float-left p-2 border">
368+
.col-lg-2
369+
</div>
370+
</div>
371+
```
372+
373+
## Containers
374+
Container widths match our breakpoints and are available at a `md`, `lg`, and `xl` size. Containers apply a max-width rather than a fixed width for responsive layouts, and they center the container.
375+
376+
```html
377+
<div class="container-md border">
378+
.container-md, max-width 768px
379+
</div>
380+
381+
<div class="container-lg border">
382+
.container-lg, max-width 1012px
383+
</div>
384+
385+
<div class="container-xl border">
386+
.container-xl, max-width 1280px
387+
</div>
388+
```
389+
390+
**Note:** `.container` is being replaced with `.container-lg`. To match the current fixed page width use `.container-lg` with `px-3`. This gives the container padding on smaller screens which works better for responsive layouts.

0 commit comments

Comments
 (0)