jekyll-theme-primer 0.5.2 → 0.5.3

data/_sass/primer-utilities/docs/box-shadow.md

@@ -0,0 +1,107 @@
+---
+title: Box shadow
+status: New release
+status_issue: https://github.com/github/design-systems/issues/269
+---
+
+Box shadows are used to make content appear elevated. They are typically applied to containers of content that users need to pay attention to or content that appears on top of (overlapping) other elements on the page (like a pop-over or modal).
+
+{:toc}
+
+## Default
+
+Default shadows are mainly used on things that need to appear slightly elevated, like pricing cards or UI elements containing important information.
+
+```html
+<div class="box-shadow p-3">
+  .box-shadow
+</div>
+```
+
+These types of shadows are typically applied to elements with borders, like [`Box`](/styleguide/css/styles/core/components/box).
+
+```html
+<div class="col-5">
+  <div class="Box box-shadow">
+    <div class="Box-row">
+      <h3 class="mb-0">Organization</h3>
+    </div>
+    <div class="Box-row">
+      <p class="mb-0 alt-text-small text-gray">
+        Taxidermy live-edge mixtape, keytar tumeric locavore meh selvage deep v letterpress vexillologist lo-fi tousled church-key thundercats. Brooklyn bicycle rights tousled, marfa actually.
+      </p>
+    </div>
+    <div class="Box-row">
+      <button type="button" name="Create an organization" class="btn btn-primary btn-block">Create an organization</button>
+    </div>
+  </div>
+</div>
+```
+
+## Medium
+
+Medium box shadows are more diffused and slightly larger than small box shadows.
+
+```html
+<div class="box-shadow-medium p-3">
+  .box-shadow-medium
+</div>
+```
+
+Medium box shadows are typically used on editorialized content that needs to appear elevated. Most of the time, the elements using this level of shadow will be clickable.
+
+```html
+<div class="col-6">
+  <a class="d-block box-shadow-medium px-3 pt-4 pb-6 position-relative rounded-1 overflow-hidden no-underline" href="#">
+    <div class="bg-blue position-absolute top-0 left-0 py-1 width-full"></div>
+    <h3 class="text-gray-dark">Serverless architecture</h3>
+    <p class="alt-text-small text-gray">
+      Build powerful, event-driven, serverless architectures with these open-source libraries and frameworks.
+    </p>
+    <ul class="position-absolute bottom-0 pb-3 text-small text-gray list-style-none ">
+      <li class="d-inline-block mr-1"><%= octicon "repo", :class => "mr-1" %>12 Repositories</li>
+      <li class="d-inline-block"><%= octicon "code", :class => "mr-1" %>5 Languages</li>
+    </ul>
+  </a>
+</div>
+```
+
+## Large
+
+Large box shadows are very diffused and used sparingly in the product UI.
+
+```html
+<div class="box-shadow-large p-3">
+  .box-shadow-large
+</div>
+```
+
+These shadows are used for marketing content, UI screenshots, and content that appears on top of other page elements.
+
+```html
+<div class="box-shadow-large rounded-2 overflow-hidden">
+  <img src="<%= image_path "modules/site/org_example_nasa.png" %>" class="img-responsive" alt="NASA is on GitHub">
+</div>
+```
+
+## Extra Large
+
+Extra large box shadows are even more diffused.
+
+```html
+<div class="box-shadow-extra-large p-3">
+  .box-shadow-extra-large
+</div>
+```
+
+These shadows are used for marketing content and content that appears on top of other page elements.
+
+## Remove a box shadow
+
+Additionally there is a `box-shadow-none` class that removes `box-shadow`:
+
+```html
+<div class="box-shadow-large box-shadow-none p-3">
+  .box-shadow-none
+</div>
+```

data/_sass/primer-utilities/docs/colors.md

@@ -0,0 +1,232 @@
+---
+title: Colors
+status: New release
+status_issue: https://github.com/github/design-systems/issues/97
+---
+
+Use color utilities to apply color to the background of elements, text, and borders.
+
+* [Background colors](#background-colors)
+* [Text colors](#text-colors)
+* [Link colors](#link-colors)
+* [Border colors](#border-colors)
+
+## Background colors
+
+Background colors are most commonly used for filling large blocks of content or areas with a color. When selecting a background color, make sure the foreground color contrast passes a minimum WCAG accessibility rating of [level AA](https://www.w3.org/TR/UNDERSTANDING-WCAG20/visual-audio-contrast-contrast.html). Meeting these standards ensures that content is accessible by everyone, regardless of disability or user device. You can [check your color combination with this demo site](http://jxnblk.com/colorable/demos/text/). For more information, read our [accessibility standards](/styleguide/css/principles/accessibility).
+
+### Gray
+
+<div class="container-lg clearfix mb-4">
+  <div class="col-3 float-left pr-4">
+    <div class="h4">.bg-gray</div>
+    <code>#f5f5f5, $bg-gray</code>
+    <div class="mt-2 bg-gray" style="height: 60px;"></div>
+  </div>
+  <div class="col-9 float-left">
+    <div class="container-lg clearfix">
+      <div class="col-6 float-left">
+        <div class="h4">.bg-gray-dark</div>
+        <code>#333, $bg-gray-dark</code>
+        <div class="mt-2 bg-gray-dark border-right-0" style="height: 60px;"></div>
+      </div>
+      <div class="col-6 float-left">
+        <div class="h4">.bg-gray-light</div>
+        <code>#fafafa, $bg-gray-light</code>
+        <div class="mt-2 bg-gray-light" style="height: 60px;"></div>
+      </div>
+    </div>
+  </div>
+</div>
+
+### Blue
+
+<div class="container-lg clearfix mb-4">
+  <div class="col-3 float-left pr-4">
+    <div class="h4">.bg-blue</div>
+    <code>#4078c0, $bg-blue</code>
+    <div class="mt-2 bg-blue" style="height: 60px;"></div>
+  </div>
+  <div class="col-9 float-left">
+    <div class="container-lg clearfix">
+      <div class="h4">.bg-blue-light</div>
+      <code>#f2f8fa, $bg-blue-light</code>
+      <div class="mt-2 bg-blue-light" style="height: 60px;"></div>
+    </div>
+  </div>
+</div>
+
+### Yellow
+
+<div class="container-lg clearfix mb-4">
+  <div class="col-3 float-left pr-4">
+    <div class="h4">.bg-yellow</div>
+    <code>#ffd36b, $bg-yellow</code>
+    <div class="mt-2 bg-yellow" style="height: 60px;"></div>
+  </div>
+  <div class="col-9 float-left">
+    <div class="container-lg clearfix">
+      <div class="h4">.bg-yellow-light</div>
+      <code>#fff9ea, $bg-yellow-light</code>
+      <div class="mt-2 bg-yellow-light" style="height: 60px;"></div>
+    </div>
+  </div>
+</div>
+
+### Red
+
+<div class="container-lg clearfix mb-4">
+  <div class="col-3 float-left pr-4">
+    <div class="h4">.bg-red</div>
+    <code>#bd2c00, $bg-red</code>
+    <div class="mt-2 bg-red" style="height: 60px;"></div>
+  </div>
+  <div class="col-9 float-left">
+    <div class="container-lg clearfix">
+      <div class="h4">.bg-red-light</div>
+      <code>#fcdede, $bg-red-light</code>
+      <div class="mt-2 bg-red-light" style="height: 60px;"></div>
+    </div>
+  </div>
+</div>
+
+### Green
+
+<div class="container-lg clearfix mb-4">
+  <div class="col-3 float-left pr-4">
+    <div class="h4">.bg-green</div>
+    <code>#6cc644, $bg-green</code>
+    <div class="mt-2 bg-green" style="height: 60px;"></div>
+  </div>
+  <div class="col-9 float-left">
+    <div class="container-lg clearfix">
+      <div class="h4">.bg-green-light</div>
+      <code>#eaffea, $bg-green-light</code>
+      <div class="mt-2 bg-green-light" style="height: 60px;"></div>
+    </div>
+  </div>
+</div>
+
+
+### Purple
+
+<div class="container-lg clearfix mb-4">
+  <div class="col-3 float-left pr-4">
+    <div class="h4">.bg-purple</div>
+    <code>#6e5494, $bg-purple</code>
+    <div class="mt-2 bg-purple" style="height: 60px;"></div>
+  </div>
+  <div class="col-9 float-left">
+    <div class="container-lg clearfix">
+      <div class="h4">.bg-purple-light</div>
+      <code>#f5f0ff, $bg-purple-light</code>
+      <div class="mt-2 bg-purple-light" style="height: 60px;"></div>
+    </div>
+  </div>
+</div>
+
+## Text colors
+
+Use text color utilities to set text or [octicons](/styleguide/css/styles/core/components/octicons) to a specific color. Color contrast must pass a minimum WCAG accessibility rating of [level AA](https://www.w3.org/TR/UNDERSTANDING-WCAG20/visual-audio-contrast-contrast.html). This ensures that viewers who cannot see the full color spectrum are able to read the text. To customize outside of the suggested combinations below, we recommend using this [color contrast testing tool](http://jxnblk.com/colorable/demos/text/). For more information, read our [accessibility standards](/styleguide/css/principles/accessibility).
+
+These are our most common text with background color combinations. They don't all pass accessibility standards currently, but will be updated in the future. **Any of the combinations with a warning icon must be used with caution**.
+
+### Text on white background
+
+```html
+<div class="text-blue mb-2">
+  .text-blue on white
+</div>
+<div class="text-gray-dark mb-2">
+  .text-gray-dark on white
+</div>
+<div class="text-gray mb-2">
+  .text-gray on white
+</div>
+<div class="text-red mb-2">
+  .text-red on white
+</div>
+<div class="text-orange mb-2">
+  .text-orange on white
+</div>
+<span class="float-left text-red tooltipped tooltipped-n" aria-label="Does not meet accessibility standards"><%= octicon("alert") %></span>
+<div class="text-orange-light mb-2">
+  .text-orange-light on white
+</div>
+<span class="float-left text-red tooltipped tooltipped-n" aria-label="Does not meet accessibility standards"><%= octicon("alert") %></span>
+<div class="text-green mb-2 ml-4">
+  .text-green on white
+</div>
+<div class="text-purple mb-2">
+  .text-purple on white
+</div>
+```
+
+### Text on colored backgrounds
+
+```html
+<div class="text-white bg-blue mb-2">
+  .text-white on .bg-blue
+</div>
+<div class="bg-blue-light mb-2">
+  .text-gray-dark on .bg-blue-light
+</div>
+<div class="text-white bg-red mb-2">
+  .text-white on .bg-red
+</div>
+<div class="text-red bg-red-light mb-2">
+  .text-red on .bg-red-light
+</div>
+<div class="bg-green-light mb-2">
+  .text-gray-dark on .bg-green-light
+</div>
+<div class="bg-yellow mb-2">
+  .text-gray-dark on .bg-yellow
+</div>
+<div class="bg-yellow-light mb-2">
+  .text-gray-dark on .bg-yellow-light
+</div>
+<div class="text-white bg-purple mb-2">
+  .text-white on .bg-purple
+</div>
+<div class="text-white bg-gray-dark mb-2">
+  .text-white on .bg-gray-dark
+</div>
+<div class="bg-gray">
+  .text-gray-dark on .bg-gray
+</div>
+```
+
+## Link colors
+
+Base link styles turn links blue and apply an underline on hover. You can override the base link styles with text color utilities and the following link utilities. **Bear in mind that link styles are easier for more people to see and interact with when the changes in styles do not rely on color alone.**
+
+Use `link-gray` to turn the link color to `$text-gray` and remain hover on blue.
+
+```html
+<a class="link-gray" href="#url">link-gray</a>
+```
+
+Use `link-gray-dark` to turn the link color to `$text-gray-dark` and remain hover on blue.
+
+```html
+<a class="link-gray-dark"  href="#url">link-gray-dark</a>
+```
+
+Use `.muted-link` to turn the link light gray in color, and blue on hover or focus with no underline.
+
+```html
+<a class="muted-link" href="#url">muted-link</a>
+```
+
+Use `link-hover-blue` to make any text color used with links to turn blue on hover. This is useful when you want only part of a link to turn blue on hover.
+
+```html
+<a class="text-gray-dark no-underline" href="#url">
+  A link with only part of it is <span class="link-hover-blue">blue on hover</span>.
+</a>
+```
+
+## Border colors
+
+Border colors are documented on the [border utilities page](/styleguide/css/styles/core/utilities/borders#border-width-style-and-color-utilities).

data/_sass/primer-utilities/docs/flexbox.md

@@ -0,0 +1,665 @@
+---
+title: Flexbox
+status: New release
+source: /app/assets/stylesheets/primer-core/utilities/lib/layout.scss
+status_issue: https://github.com/github/design-systems/issues/157
+---
+
+Flex utilities can be used to apply `flexbox` behaviors to elements by using utility classes.
+
+{:toc}
+
+## Required reading
+
+Before using these utilities, **you should be familiar with CSS3 Flexible Box spec**. If you are not, check out MDN's guide:
+
+:book: **[Using CSS Flexible Boxes](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Flexible_Box_Layout/Using_CSS_flexible_boxes)**
+
+## Flex container
+
+Use these classes to make an element lay out its content using the flexbox model. Each **direct** child of the flex container will become a flex item.
+
+#### CSS
+
+```css
+.d-flex { display: flex; }
+.d-inline-flex { display: inline-flex; }
+```
+
+#### Classes
+
+| Class | Description |
+| --- | --- |
+| `.d-flex` | The element behaves like a block and lays out its content using the flexbox model. |
+| `.d-inline-flex` | The element behaves like an inline element and lays out its content using the flexbox model. |
+
+#### Example using `.d-flex`
+
+```html
+<!-- flex container -->
+<div class="border d-flex">
+  <div class="p-5 border bg-gray-light">flex item 1</div>
+  <div class="p-5 border bg-gray-light">flex item 2</div>
+  <div class="p-5 border bg-gray-light">flex item 3</div>
+</div>
+```
+
+#### Example using `.d-inline-flex`
+
+```html
+<!-- inline-flex container -->
+<div class="border d-inline-flex">
+  <div class="p-5 border bg-gray-light">flex item 1</div>
+  <div class="p-5 border bg-gray-light">flex item 2</div>
+  <div class="p-5 border bg-gray-light">flex item 3</div>
+</div>
+```
+
+## Flex direction
+
+Use these classes to define the orientation of the main axis (`row` or `column`). By default, flex items will display in a row. Use `.flex-column` to change the direction of the main axis to vertical.
+
+#### CSS
+
+```css
+.flex-row         { flex-direction: row; }
+.flex-row-reverse { flex-direction: row-reverse; }
+.flex-column      { flex-direction: column; }
+```
+
+#### Classes
+
+| Class | Description |
+| --- | --- |
+| `.flex-row` | The main axis runs left to right (default). |
+| `.flex-row-reverse` | The main axis runs right to left. |
+| `.flex-column` | The main axis runs top to bottom. |
+
+#### Example using `.flex-column`
+
+```html
+<div class="border d-flex flex-column">
+  <div class="p-5 border bg-gray-light">Item 1</div>
+  <div class="p-5 border bg-gray-light">Item 2</div>
+  <div class="p-5 border bg-gray-light">Item 3</div>
+</div>
+```
+
+#### Example using `.flex-row`
+
+This example uses the responsive variant `.flex-md-row` to override `.flex-column` Learn more about responsive flexbox utilities **[here](#responsive-flex-utilities)**.
+
+```html
+<div class="border d-flex flex-column flex-md-row">
+  <div class="p-5 border bg-gray-light">Item 1</div>
+  <div class="p-5 border bg-gray-light">Item 2</div>
+  <div class="p-5 border bg-gray-light">Item 3</div>
+</div>
+```
+
+#### Example using `.flex-row-reverse`
+
+This example uses the responsive variant `.flex-md-row-reverse` to override `.flex-column` Learn more about responsive flexbox utilities **[here](#responsive-flex-utilities)**.
+
+```html
+<div class="border d-flex flex-column flex-md-row-reverse">
+  <div class="p-5 border bg-gray-light">Item 1</div>
+  <div class="p-5 border bg-gray-light">Item 2</div>
+  <div class="p-5 border bg-gray-light">Item 3</div>
+</div>
+```
+
+## Flex wrap
+
+You can choose whether flex items are forced into a single line or wrapped onto multiple lines.
+
+#### CSS
+
+```css
+.flex-wrap     { flex-wrap: wrap; }
+.flex-nowrap   { flex-wrap: nowrap; }
+```
+
+#### Classes
+
+| Class | Description |
+| --- | --- |
+| `.flex-wrap` | Flex items will break onto multiple lines (default) |
+| `.flex-nowrap` | Flex items are laid out in a single line, even if they overflow |
+
+#### `flex-wrap` example
+
+```html
+<div class="border d-flex flex-wrap">
+  <div class="p-5 px-6 border bg-gray-light">1</div>
+  <div class="p-5 px-6 border bg-gray-light">2</div>
+  <div class="p-5 px-6 border bg-gray-light">3</div>
+  <div class="p-5 px-6 border bg-gray-light">4</div>
+  <div class="p-5 px-6 border bg-gray-light">5</div>
+  <div class="p-5 px-6 border bg-gray-light">6</div>
+  <div class="p-5 px-6 border bg-gray-light">7</div>
+  <div class="p-5 px-6 border bg-gray-light">8</div>
+  <div class="p-5 px-6 border bg-gray-light">9</div>
+</div>
+```
+
+#### `flex-nowrap` example
+
+```html
+<div class="border d-flex flex-nowrap">
+  <div class="p-5 px-6 border bg-gray-light">1</div>
+  <div class="p-5 px-6 border bg-gray-light">2</div>
+  <div class="p-5 px-6 border bg-gray-light">3</div>
+  <div class="p-5 px-6 border bg-gray-light">4</div>
+  <div class="p-5 px-6 border bg-gray-light">5</div>
+  <div class="p-5 px-6 border bg-gray-light">6</div>
+  <div class="p-5 px-6 border bg-gray-light">7</div>
+  <div class="p-5 px-6 border bg-gray-light">8</div>
+  <div class="p-5 px-6 border bg-gray-light">9</div>
+</div>
+```
+
+## Justify content
+
+Use these classes to distribute space between and around flex items along the **main axis** of the container.
+
+#### CSS
+
+```CSS
+.flex-justify-start    { justify-content: flex-start; }
+.flex-justify-end      { justify-content: flex-end; }
+.flex-justify-center   { justify-content: center; }
+.flex-justify-between  { justify-content: space-between; }
+.flex-justify-around   { justify-content: space-around; }
+```
+
+#### Classes
+
+| Class | Default behavior |
+| --- | --- |
+| `.flex-justify-start` | Justify all items to the left |
+| `.flex-justify-end` | Justify all items to the right |
+| `.flex-justify-center` | Justify items to the center of the container |
+| `.flex-justify-between` | Distribute items evenly. First item is on the start line, last item is on the end line. |
+| `.flex-justify-around` | Distribute items evenly with equal space around them |
+
+#### flex-justify-start
+
+Use `.flex-justify-start` to align items to the start line. By default this will be on the left side of the container. If you are using `.flex-column`, the end line will be at the top of the container.
+
+```html
+<div class="border d-flex flex-justify-start">
+  <div class="p-5 border bg-gray-light">1</div>
+  <div class="p-5 border bg-gray-light">2</div>
+  <div class="p-5 border bg-gray-light">3</div>
+</div>
+```
+
+#### flex-justify-end
+
+Use `.flex-justify-end` to align items to the end line. By default this will be on the right side of the container. If you are using `.flex-column`, the end line will be at the bottom of the container.
+
+```html
+<div class="border d-flex flex-justify-end">
+ <div class="p-5 border bg-gray-light">1</div>
+ <div class="p-5 border bg-gray-light">2</div>
+ <div class="p-5 border bg-gray-light">3</div>
+</div>
+```
+
+#### flex-justify-center
+
+Use `.flex-justify-center` to align items in the middle of the container.
+
+```html
+<div class="border d-flex flex-justify-center">
+ <div class="p-5 border bg-gray-light">1</div>
+ <div class="p-5 border bg-gray-light">2</div>
+ <div class="p-5 border bg-gray-light">3</div>
+</div>
+```
+
+#### flex-justify-between
+
+Use `.flex-justify-between` to distribute items evenly in the container. The first items will be on the start line and the last item will be on the end line.
+
+```html
+<div class="border d-flex flex-justify-between">
+ <div class="p-5 border bg-gray-light">1</div>
+ <div class="p-5 border bg-gray-light">2</div>
+ <div class="p-5 border bg-gray-light">3</div>
+</div>
+```
+
+#### flex-justify-around
+
+Use `.flex-justify-around` to distribute items evenly, with an equal amount of space around them. Visually the spaces won't look equal, since each item has the same unit of space around it. For example, the first item only has one unit of space between it and the start line, but it has two units of space between it and the next item.
+
+```html
+<div class="border d-flex flex-justify-around">
+ <div class="p-5 border bg-gray-light">1</div>
+ <div class="p-5 border bg-gray-light">2</div>
+ <div class="p-5 border bg-gray-light">3</div>
+</div>
+```
+
+## Align items
+
+Use these classes to align items on the **cross axis**.
+
+The cross axis runs perpendicular to the main axis. By default the main axis runs horizontally, so your items will align vertically on the cross axis. If you use [flex-column](#flex-direction) to make the main axis run vertically, your items will be aligned horizontally.
+
+#### CSS
+
+```css
+.flex-items-start      { align-items: flex-start; }
+.flex-items-end        { align-items: flex-end; }
+.flex-items-center     { align-items: center; }
+.flex-items-baseline   { align-items: baseline; }
+.flex-items-stretch    { align-items: stretch; }
+```
+
+#### Classes
+
+| Class | Behavior |
+| --- | --- |
+| `.flex-items-start` | Align items to the start of the cross axis  |
+| `.flex-items-end` | Align items to the end of the cross axis |
+| `.flex-items-center` | Align items to the center of the cross axis |
+| `.flex-items-baseline` | Align items along their baselines |
+| `.flex-items-stretch` | Stretch items from start of cross axis to end of cross axis |
+
+#### flex-items-start
+
+```html
+<div  style="min-height: 150px;" class="border d-flex flex-items-start">
+  <div class="p-5 border bg-gray-light">1</div>
+  <div class="p-5 border bg-gray-light">2</div>
+  <div class="p-5 border bg-gray-light">3</div>
+  <div class="p-5 border bg-gray-light">4</div>
+</div>
+```
+
+#### flex-items-end
+
+```html
+<div  style="min-height: 150px;" class="border d-flex flex-items-end">
+  <div class="p-5 border bg-gray-light">1</div>
+  <div class="p-5 border bg-gray-light">2</div>
+  <div class="p-5 border bg-gray-light">3</div>
+  <div class="p-5 border bg-gray-light">4</div>
+</div>
+```
+
+#### flex-items-center
+
+```html
+<div  style="min-height: 150px;" class="border d-flex flex-items-center">
+  <div class="p-5 border bg-gray-light">1</div>
+  <div class="p-5 border bg-gray-light">2</div>
+  <div class="p-5 border bg-gray-light">3</div>
+  <div class="p-5 border bg-gray-light">4</div>
+</div>
+```
+
+#### flex-items-baseline
+
+With `.flex-items-baseline`, items will be aligned along their baselines even if they have different font sizes.
+
+```html
+<div  style="min-height: 150px;" class="border d-flex flex-items-baseline">
+  <div class="p-5 border bg-gray-light f1">1</div>
+  <div class="p-5 border bg-gray-light">2</div>
+  <div class="p-5 border bg-gray-light f3">3</div>
+  <div class="p-5 border bg-gray-light">4</div>
+</div>
+```
+
+#### flex-items-stretch
+
+```html
+<div  style="min-height: 150px;" class="border d-flex flex-items-stretch">
+  <div class="p-5 border bg-gray-light">1</div>
+  <div class="p-5 border bg-gray-light">2</div>
+  <div class="p-5 border bg-gray-light">3</div>
+  <div class="p-5 border bg-gray-light">4</div>
+</div>
+```
+
+## Align content
+
+When the main axis wraps, this creates multiple main axis lines and adds extra space in the cross axis. Use these classes to align the lines of the main axis on the cross axis.
+
+#### CSS
+
+```css
+.flex-content-start    { align-content: flex-start; }
+.flex-content-end      { align-content: flex-end; }
+.flex-content-center   { align-content: center; }
+.flex-content-between  { align-content: space-between; }
+.flex-content-around   { align-content: space-around; }
+.flex-content-stretch  { align-content: stretch; }
+```
+
+#### Classes
+
+| Class | Description |
+| --- | --- |
+| `.flex-content-start` | Align content to the start of the cross axis  |
+| `.flex-content-end` | Align content to the end of the cross axis |
+| `.flex-content-center` | Align content to the center of the cross axis |
+| `.flex-content-between` | Distribute content evenly. First line is on the start of the cross axis, last line is on the end of the cross axis.  |
+| `.flex-content-around` | Stretch items from the start of the cross axis to the end of the cross axis. |
+| `.flex-content-stretch` | Lines stretch to occupy available space.  |
+
+#### flex-content-start
+
+```html
+<div style="min-height: 300px;" class="border d-flex flex-wrap flex-content-start">
+  <div class="p-5 border bg-gray-light">1</div>
+  <div class="p-5 border bg-gray-light">2</div>
+  <div class="p-5 border bg-gray-light">3</div>
+  <div class="p-5 border bg-gray-light">4</div>
+  <div class="p-5 border bg-gray-light">5</div>
+  <div class="p-5 border bg-gray-light">6</div>
+  <div class="p-5 border bg-gray-light">7</div>
+  <div class="p-5 border bg-gray-light">8</div>
+  <div class="p-5 border bg-gray-light">9</div>
+  <div class="p-5 border bg-gray-light">10</div>
+  <div class="p-5 border bg-gray-light">11</div>
+  <div class="p-5 border bg-gray-light">12</div>
+</div>
+```
+
+#### flex-content-end
+
+```html
+<div style="min-height: 300px;" class="border d-flex flex-wrap flex-content-end">
+  <div class="p-5 border bg-gray-light">1</div>
+  <div class="p-5 border bg-gray-light">2</div>
+  <div class="p-5 border bg-gray-light">3</div>
+  <div class="p-5 border bg-gray-light">4</div>
+  <div class="p-5 border bg-gray-light">5</div>
+  <div class="p-5 border bg-gray-light">6</div>
+  <div class="p-5 border bg-gray-light">7</div>
+  <div class="p-5 border bg-gray-light">8</div>
+  <div class="p-5 border bg-gray-light">9</div>
+  <div class="p-5 border bg-gray-light">10</div>
+  <div class="p-5 border bg-gray-light">11</div>
+  <div class="p-5 border bg-gray-light">12</div>
+</div>
+```
+
+#### flex-content-center
+
+```html
+<div style="min-height: 300px;" class="border d-flex flex-wrap flex-content-center">
+  <div class="p-5 border bg-gray-light">1</div>
+  <div class="p-5 border bg-gray-light">2</div>
+  <div class="p-5 border bg-gray-light">3</div>
+  <div class="p-5 border bg-gray-light">4</div>
+  <div class="p-5 border bg-gray-light">5</div>
+  <div class="p-5 border bg-gray-light">6</div>
+  <div class="p-5 border bg-gray-light">7</div>
+  <div class="p-5 border bg-gray-light">8</div>
+  <div class="p-5 border bg-gray-light">9</div>
+  <div class="p-5 border bg-gray-light">10</div>
+  <div class="p-5 border bg-gray-light">11</div>
+  <div class="p-5 border bg-gray-light">12</div>
+</div>
+```
+
+#### flex-content-between
+
+```html
+<div style="min-height: 300px;" class="border d-flex flex-wrap flex-content-between">
+  <div class="p-5 border bg-gray-light">1</div>
+  <div class="p-5 border bg-gray-light">2</div>
+  <div class="p-5 border bg-gray-light">3</div>
+  <div class="p-5 border bg-gray-light">4</div>
+  <div class="p-5 border bg-gray-light">5</div>
+  <div class="p-5 border bg-gray-light">6</div>
+  <div class="p-5 border bg-gray-light">7</div>
+  <div class="p-5 border bg-gray-light">8</div>
+  <div class="p-5 border bg-gray-light">9</div>
+  <div class="p-5 border bg-gray-light">10</div>
+  <div class="p-5 border bg-gray-light">11</div>
+  <div class="p-5 border bg-gray-light">12</div>
+</div>
+```
+
+#### flex-content-around
+
+```html
+<div style="min-height: 300px;" class="border d-flex flex-wrap flex-content-around">
+  <div class="p-5 border bg-gray-light">1</div>
+  <div class="p-5 border bg-gray-light">2</div>
+  <div class="p-5 border bg-gray-light">3</div>
+  <div class="p-5 border bg-gray-light">4</div>
+  <div class="p-5 border bg-gray-light">5</div>
+  <div class="p-5 border bg-gray-light">6</div>
+  <div class="p-5 border bg-gray-light">7</div>
+  <div class="p-5 border bg-gray-light">8</div>
+  <div class="p-5 border bg-gray-light">9</div>
+  <div class="p-5 border bg-gray-light">10</div>
+  <div class="p-5 border bg-gray-light">11</div>
+  <div class="p-5 border bg-gray-light">12</div>
+</div>
+```
+
+#### flex-content-stretch
+
+```html
+<div style="min-height: 300px;" class="border d-flex flex-wrap flex-content-stretch">
+  <div class="p-5 border bg-gray-light">1</div>
+  <div class="p-5 border bg-gray-light">2</div>
+  <div class="p-5 border bg-gray-light">3</div>
+  <div class="p-5 border bg-gray-light">4</div>
+  <div class="p-5 border bg-gray-light">5</div>
+  <div class="p-5 border bg-gray-light">6</div>
+  <div class="p-5 border bg-gray-light">7</div>
+  <div class="p-5 border bg-gray-light">8</div>
+  <div class="p-5 border bg-gray-light">9</div>
+  <div class="p-5 border bg-gray-light">10</div>
+  <div class="p-5 border bg-gray-light">11</div>
+  <div class="p-5 border bg-gray-light">12</div>
+</div>
+```
+
+## Flex
+
+Use this class to specify the ability of a flex item to alter its dimensions to fill available space.
+
+```CSS
+.flex-auto    { flex: 1 1 auto; }
+```
+
+| Class | Description |
+| --- | --- |
+| `.flex-auto` | Sets default values for  `flex-grow` (1), `flex-shrink` (1) and `flex-basis` (auto)  |
+
+#### flex-auto
+
+```html
+<div class="border d-flex">
+  <div class="p-5 border bg-gray-light flex-auto">.flex-auto</div>
+  <div class="p-5 border bg-gray-light flex-auto">.flex-auto</div>
+  <div class="p-5 border bg-gray-light flex-auto">.flex-auto</div>
+</div>
+```
+
+## Align self
+
+Use these classes to adjust the alignment of an individual flex item on the cross axis. This overrides any `align-items` property applied to the flex container.
+
+#### CSS
+
+```css
+.flex-self-auto        { align-self: auto; }
+.flex-self-start       { align-self: flex-start; }
+.flex-self-end         { align-self: flex-end; }
+.flex-self-center      { align-self: center; }
+.flex-self-baseline    { align-self: baseline; }
+.flex-self-stretch     { align-self: stretch; }
+```
+
+#### Classes
+
+| Class | Description |
+| --- | --- |
+| `.flex-self-auto` | Inherit alignment from parent |
+| `.flex-self-start` | Align to the start of the cross axis  |
+| `.flex-self-end` | Align to the end of the cross axis |
+| `.flex-self-center` | Align to center of cross axis |
+| `.flex-self-baseline` | Align baseline to the start of the cross axis |
+| `.flex-self-stretch` | Stretch item from start of cross axis to end of cross axis. |
+
+#### flex-self-auto
+
+```html
+<div style="min-height: 150px;" class="border d-flex">
+  <div class="p-5 border bg-gray-light flex-self-auto">.flex-self-auto</div>
+  <div class="p-5 border bg-gray-light">&nbsp;</div>
+  <div class="p-5 border bg-gray-light">&nbsp;</div>
+</div>
+```
+
+#### flex-self-start
+
+```html
+<div style="min-height: 150px;" class="border d-flex">
+  <div class="p-5 border bg-gray-light flex-self-start">.flex-self-start</div>
+  <div class="p-5 border bg-gray-light">&nbsp;</div>
+  <div class="p-5 border bg-gray-light">&nbsp;</div>
+</div>
+```
+
+#### flex-self-end
+
+```html
+<div style="min-height: 150px;" class="border d-flex">
+  <div class="p-5 border bg-gray-light flex-self-end">.flex-self-end</div>
+  <div class="p-5 border bg-gray-light">&nbsp;</div>
+  <div class="p-5 border bg-gray-light">&nbsp;</div>
+</div>
+```
+
+#### flex-self-center
+
+```html
+<div style="min-height: 150px;" class="border d-flex">
+  <div class="p-5 border bg-gray-light flex-self-center">.flex-self-center</div>
+  <div class="p-5 border bg-gray-light">&nbsp;</div>
+  <div class="p-5 border bg-gray-light">&nbsp;</div>
+</div>
+```
+
+#### flex-self-baseline
+
+```html
+<div style="min-height: 150px;" class="border d-flex flex-items-end">
+  <div class="p-5 border bg-gray-light flex-self-baseline f4">.flex-self-baseline</div>
+  <div class="p-5 border bg-gray-light f1">item</div>
+  <div class="p-5 border bg-gray-light f00">item</div>
+</div>
+```
+
+#### flex-self-stretch
+
+```html
+<div style="min-height: 150px;" class="border d-flex flex-items-start">
+  <div class="p-5 border bg-gray-light flex-self-stretch">.flex-self-stretch</div>
+  <div class="p-5 border bg-gray-light">&nbsp;</div>
+  <div class="p-5 border bg-gray-light">&nbsp;</div>
+</div>
+```
+
+## Responsive flex utilities
+
+All flexbox utilities can be adjust per [breakpoint](/styleguide/css/modules/grid#breakpoints) using the following formulas:
+
+- `d-[breakpoint]-[property]` for `display`
+- `flex-[breakpoint]-[property]-[behavior]` for various flex properties
+- `flex-[breakpoint]-item-equal` for equal width and equal height flex items
+
+Each responsive style is applied to the specified breakpoint and up.
+
+#### Example classes
+
+```css
+/* Example classes */
+
+.d-sm-flex {}
+.d-md-inline-flex {}
+
+.flex-lg-row {}
+.flex-xl-column {}
+
+.flex-sm-wrap {}
+.flex-lg-nowrap {}
+
+.flex-lg-self-start {}
+
+.flex-md-item-equal {}
+```
+
+#### Example usage
+
+Mixing flex properties:
+
+```html
+<div style="min-height: 150px;" class="border d-flex flex-items-start flex-md-items-center flex-justify-start flex-lg-justify-between">
+  <div class="p-5 border bg-gray-light flex-md-self-stretch">.flex-self-stretch</div>
+  <div class="p-5 border bg-gray-light">&nbsp;</div>
+  <div class="p-5 border bg-gray-light">&nbsp;</div>
+</div>
+```
+
+Using the equal width, equal height utilities:
+
+```html
+<div class="border d-flex">
+  <div class="flex-md-item-equal p-3 border bg-gray-light">Stuff and things</div>
+  <div class="flex-md-item-equal p-3 border bg-gray-light">More stuff<br> on multiple lines</div>
+  <div class="flex-md-item-equal p-3 border bg-gray-light">Hi mom</div>
+</div>
+```
+
+## Example components
+
+The flex utilities can be used to create a number of components. Here are some examples.
+
+### Media object
+
+You can use flex utilities to make a simple media object, like this:
+
+```html
+<div class="border d-flex flex-items-center p-4">
+  <div class="p-5 border bg-gray-light">image</div>
+  <p class="pl-4 m-0"><b>Body</b> Bacon ipsum dolor sit amet chuck prosciutto landjaeger ham hock filet mignon shoulder hamburger pig venison.</p>
+</div>
+```
+
+### Responsive media object
+
+Here is an example of a media object that is **vertically centered on large screens**, but converts to a stacked column layout on small screens.
+
+```html
+<div class="border p-3 d-flex flex-column flex-md-row flex-md-items-center">
+  <div class="pr-0 pr-md-3 mb-3 mb-md-0 d-flex flex-justify-center flex-md-justify-start">
+    <img style="max-width:100px; max-height:100px;" src="/images/gravatars/gravatar-user-420.png" />
+  </div>
+  <div class="d-flex text-center text-md-left">
+    <p><b>Body</b> Bacon ipsum dolor sit amet chuck prosciutto landjaeger ham hock filet mignon shoulder hamburger pig venison.</p>
+  </div>
+  <div class="ml-md-3 d-flex flex-justify-center">
+    <%= octicon "mark-github", :height => '32' %>
+  </div>
+</div>
+```
+
+## Flexbox bugs
+
+This section lists flexbox bugs that affect browsers we [currently support](.../styles#user-content-browser-support).
+
+**1. Minimum content sizing of flex items not honored:** Some browsers don't respect flex item size. Instead of respecting the minimum content size, items shrink below their minimum size which can create some undesirable results, such as overflowing text. The workaround is to apply `flex-shrink: 0;` to the items using `d-flex`. This can be applied with the `flex-shrink-0` utility. For more information read [philipwalton/flexbugs](https://github.com/philipwalton/flexbugs#1-minimum-content-sizing-of-flex-items-not-honored).