diff --git a/modules/primer-utilities/docs/animations.md b/modules/primer-utilities/docs/animations.md
new file mode 100644
index 00000000..8ee6b0d9
--- /dev/null
+++ b/modules/primer-utilities/docs/animations.md
@@ -0,0 +1,57 @@
+---
+title: Animations
+example_layout: toggle
+status: Stable
+---
+
+Animations are reusable animation classes that you can use to emphasize an element. All of these animations will animate if you toggle their visibility using the "Toggle" button.
+
+{:toc}
+
+## Fade In
+
+The `.anim-fade-in` class is used to fade in an element on the page. This will run once when the element is revealed.
+
+```html
+<%= octicon("mark-github", :height => 32, :class => "v-align-middle mr-2") %> Hello from GitHub!
+```
+
+## Fade Up
+
+The `.anim-fade-up` class is used to reveal an element on the page by sliding it up from below the fold. You should use this in a container with `overflow: hidden;` or on the bottom of the page.
+
+```html
+
+```
+
+## Fade Down
+
+The `.anim-fade-down` class is used to slide an element down hiding it. You should use this in a container with `overflow: hidden;` or on the bottom of the page.
+
+```html
+
+```
+
+## Scale In
+
+The `.anim-scale-in` class will scale the element in. This is useful on menus when you want them to appear more friendly.
+
+```html
+
<%= octicon("mark-github") %>
+```
+
+## Grow X
+
+The `.anim-grow-x` class will grow an element width from 0-:100: real quick.
+
+```html
+
+```
+
+## Pulse
+
+The `.anim-pulse` class will pulse an element infinitely.
+
+```html
+<%= octicon("mark-github", :class => "anim-pulse") %>
+```
diff --git a/modules/primer-utilities/docs/borders.md b/modules/primer-utilities/docs/borders.md
new file mode 100644
index 00000000..b20eff9e
--- /dev/null
+++ b/modules/primer-utilities/docs/borders.md
@@ -0,0 +1,124 @@
+---
+title: Borders
+status: New release
+status_issue: https://github.com/github/design-systems/issues/72
+---
+
+Utilities for borders, border radius, and box shadows.
+
+{:toc}
+
+## Default border
+
+The default border utility applies a solid, 1px border, with a default gray color.
+
+```html
+
+ .border
+
+```
+
+Borders can be applied to a specific edge or to the Y axis.
+
+```html
+
+
+ .border-left
+
+
+ .border-top
+
+
+ .border-bottom
+
+
+ .border-right
+
+
+
+ .border-y
+
+```
+
+Remove borders from all sides or a single side with `.border-0`, `.border-top-0`, `.border-right-0`, `.border-bottom-0`, `.border-left-0`.
+
+```html
+
+ .border-top-0
+
+```
+
+## Border colors
+
+Override default border colors with blue, green, red, purple, yellow, and gray border color utilities.
+
+```html
+
+ .border-blue
+
+
+ .border-blue-light
+
+
+ .border-green
+
+
+ .border-green-light
+
+
+ .border-red
+
+
+ .border-red-light
+
+
+ .border-purple
+
+
+ .border-yellow
+
+
+ .border-gray-light
+
+
+ .border-gray-dark
+
+```
+
+### Borders with alpha transparency
+Use `border-black-fade` to add an rgba black border with an alpha transparency of `0.15`. This is useful when you want a border that tints the background color. The shade of black we use matches the hue of the GitHub dark header and our gray color palette: `rgba(27,31,35, 0.15)`.
+
+```html
+
+ .border-black-fade .bg-blue-light
+
+
+ .border-black-fade .bg-red-light
+
+```
+
+## Border style
+
+Use `border-dashed` to give an element a dashed border.
+
+```html
+
+ .border-dashed
+
+```
+
+## Rounded corners
+
+Add or remove rounded corners: `rounded-0` removes rounded corners, `rounded-1` applies a border radius of 3px, `rounded-2` applies a border radius of 6px.
+
+```html
+
+ .rounded-0
+
+
+ .rounded-1
+
+
+ .rounded-2
+
+```
diff --git a/modules/primer-utilities/docs/box-shadow.md b/modules/primer-utilities/docs/box-shadow.md
new file mode 100644
index 00000000..b7805b1e
--- /dev/null
+++ b/modules/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
+
+ .box-shadow
+
+```
+
+These types of shadows are typically applied to elements with borders, like [`Box`](/styleguide/css/styles/core/components/box).
+
+```html
+
+
+
+
Organization
+
+
+
+ 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.
+
+
+
+
+
+
+
+```
+
+## Medium
+
+Medium box shadows are more diffused and slightly larger than small box shadows.
+
+```html
+
+ .box-shadow-medium
+
+```
+
+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
+
+```
+
+## Large
+
+Large box shadows are very diffused and used sparingly in the product UI.
+
+```html
+
+ .box-shadow-large
+
+```
+
+These shadows are used for marketing content, UI screenshots, and content that appears on top of other page elements.
+
+```html
+
+ " class="img-responsive" alt="NASA is on GitHub">
+
+```
+
+## Extra Large
+
+Extra large box shadows are even more diffused.
+
+```html
+
+ .box-shadow-extra-large
+
+```
+
+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
+
+ .box-shadow-none
+
+```
diff --git a/modules/primer-utilities/docs/colors.md b/modules/primer-utilities/docs/colors.md
new file mode 100644
index 00000000..d66842fb
--- /dev/null
+++ b/modules/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
+
+
+
+
.bg-gray
+ #f5f5f5, $bg-gray
+
+
+
+
+
+
.bg-gray-dark
+ #333, $bg-gray-dark
+
+
+
+
.bg-gray-light
+ #fafafa, $bg-gray-light
+
+
+
+
+
+
+### Blue
+
+
+
+
.bg-blue
+ #4078c0, $bg-blue
+
+
+
+
+
.bg-blue-light
+ #f2f8fa, $bg-blue-light
+
+
+
+
+
+### Yellow
+
+
+
+
.bg-yellow
+ #ffd36b, $bg-yellow
+
+
+
+
+
.bg-yellow-light
+ #fff9ea, $bg-yellow-light
+
+
+
+
+
+### Red
+
+
+
+
.bg-red
+ #bd2c00, $bg-red
+
+
+
+
+
.bg-red-light
+ #fcdede, $bg-red-light
+
+
+
+
+
+### Green
+
+
+
+
.bg-green
+ #6cc644, $bg-green
+
+
+
+
+
.bg-green-light
+ #eaffea, $bg-green-light
+
+
+
+
+
+
+### Purple
+
+
+
+
.bg-purple
+ #6e5494, $bg-purple
+
+
+
+
+
.bg-purple-light
+ #f5f0ff, $bg-purple-light
+
+
+
+
+
+## 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
+
+ .text-blue on white
+
+
+ .text-gray-dark on white
+
+
+ .text-gray on white
+
+
+ .text-red on white
+
+
+ .text-orange on white
+
+<%= octicon("alert") %>
+
+ .text-orange-light on white
+
+<%= octicon("alert") %>
+
+ .text-green on white
+
+
+ .text-purple on white
+
+```
+
+### Text on colored backgrounds
+
+```html
+
+ .text-white on .bg-blue
+
+
+ .text-gray-dark on .bg-blue-light
+
+
+ .text-white on .bg-red
+
+
+ .text-red on .bg-red-light
+
+
+ .text-gray-dark on .bg-green-light
+
+
+ .text-gray-dark on .bg-yellow
+
+
+ .text-gray-dark on .bg-yellow-light
+
+
+ .text-white on .bg-purple
+
+
+ .text-white on .bg-gray-dark
+
+
+ .text-gray-dark on .bg-gray
+
+```
+
+## 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
+link-gray
+```
+
+Use `link-gray-dark` to turn the link color to `$text-gray-dark` and remain hover on blue.
+
+```html
+link-gray-dark
+```
+
+Use `.muted-link` to turn the link light gray in color, and blue on hover or focus with no underline.
+
+```html
+muted-link
+```
+
+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 link with only part of it is blue on hover.
+
+```
+
+## Border colors
+
+Border colors are documented on the [border utilities page](/styleguide/css/styles/core/utilities/borders#border-width-style-and-color-utilities).
diff --git a/modules/primer-utilities/docs/flexbox.md b/modules/primer-utilities/docs/flexbox.md
new file mode 100644
index 00000000..653d57b7
--- /dev/null
+++ b/modules/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 item 1
+
flex item 2
+
flex item 3
+
+```
+
+#### Example using `.d-inline-flex`
+
+```html
+
+
+
flex item 1
+
flex item 2
+
flex item 3
+
+```
+
+## 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
+
+
Item 1
+
Item 2
+
Item 3
+
+```
+
+#### 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
+
+
Item 1
+
Item 2
+
Item 3
+
+```
+
+#### 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
+
+
Item 1
+
Item 2
+
Item 3
+
+```
+
+## 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
+
+
1
+
2
+
3
+
4
+
5
+
6
+
7
+
8
+
9
+
+```
+
+#### `flex-nowrap` example
+
+```html
+
+
1
+
2
+
3
+
4
+
5
+
6
+
7
+
8
+
9
+
+```
+
+## 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
+
+
1
+
2
+
3
+
+```
+
+#### 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
+
+
1
+
2
+
3
+
+```
+
+#### flex-justify-center
+
+Use `.flex-justify-center` to align items in the middle of the container.
+
+```html
+
+
1
+
2
+
3
+
+```
+
+#### 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
+
+
1
+
2
+
3
+
+```
+
+#### 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
+
+
1
+
2
+
3
+
+```
+
+## 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
+
+
1
+
2
+
3
+
4
+
+```
+
+#### flex-items-end
+
+```html
+
+
1
+
2
+
3
+
4
+
+```
+
+#### flex-items-center
+
+```html
+
+
1
+
2
+
3
+
4
+
+```
+
+#### flex-items-baseline
+
+With `.flex-items-baseline`, items will be aligned along their baselines even if they have different font sizes.
+
+```html
+
+
1
+
2
+
3
+
4
+
+```
+
+#### flex-items-stretch
+
+```html
+
+
1
+
2
+
3
+
4
+
+```
+
+## 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
+
+
1
+
2
+
3
+
4
+
5
+
6
+
7
+
8
+
9
+
10
+
11
+
12
+
+```
+
+#### flex-content-end
+
+```html
+
+
1
+
2
+
3
+
4
+
5
+
6
+
7
+
8
+
9
+
10
+
11
+
12
+
+```
+
+#### flex-content-center
+
+```html
+
+
1
+
2
+
3
+
4
+
5
+
6
+
7
+
8
+
9
+
10
+
11
+
12
+
+```
+
+#### flex-content-between
+
+```html
+
+
1
+
2
+
3
+
4
+
5
+
6
+
7
+
8
+
9
+
10
+
11
+
12
+
+```
+
+#### flex-content-around
+
+```html
+
+
1
+
2
+
3
+
4
+
5
+
6
+
7
+
8
+
9
+
10
+
11
+
12
+
+```
+
+#### flex-content-stretch
+
+```html
+
+
1
+
2
+
3
+
4
+
5
+
6
+
7
+
8
+
9
+
10
+
11
+
12
+
+```
+
+## 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
+
+
.flex-auto
+
.flex-auto
+
.flex-auto
+
+```
+
+## 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
+
+
.flex-self-auto
+
+
+
+```
+
+#### flex-self-start
+
+```html
+
+
.flex-self-start
+
+
+
+```
+
+#### flex-self-end
+
+```html
+
+
.flex-self-end
+
+
+
+```
+
+#### flex-self-center
+
+```html
+
+
.flex-self-center
+
+
+
+```
+
+#### flex-self-baseline
+
+```html
+
+
.flex-self-baseline
+
item
+
item
+
+```
+
+#### flex-self-stretch
+
+```html
+
+
.flex-self-stretch
+
+
+
+```
+
+## 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
+
+```
+
+## 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
+
+
image
+
Body Bacon ipsum dolor sit amet chuck prosciutto landjaeger ham hock filet mignon shoulder hamburger pig venison.
+
+```
+
+### 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
+
+
+
+
+
+
Body Bacon ipsum dolor sit amet chuck prosciutto landjaeger ham hock filet mignon shoulder hamburger pig venison.
+
+
+ <%= octicon "mark-github", :height => '32' %>
+
+
+```
+
+## 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).
diff --git a/modules/primer-utilities/docs/layout.md b/modules/primer-utilities/docs/layout.md
new file mode 100644
index 00000000..521683ee
--- /dev/null
+++ b/modules/primer-utilities/docs/layout.md
@@ -0,0 +1,290 @@
+---
+title: Layout
+status: Stable
+---
+
+Change the document layout with display, float, alignment, and other utilities.
+
+{:toc}
+
+## Display
+Adjust the display of an element with `.d-block`, `.d-none`, `.d-inline`, `.d-inline-block`, `.d-table`, `.d-table-cell` utilities.
+
+```html
+
+ .d-inline
+
+ .d-inline-block
+
+ .d-block
+
+
+ .d-table-cell
+
+
+
+ .d-table-cell
+
+
+ .d-none
+
+
+```
+
+There are known issues with using `display:table` and wrapping long strings, particularly in Firefox. You may need to use `table-fixed` on elements with `d-table` and apply column widths to table cells, which you can do with our [column width styles](/styleguide/css/modules/grid#column-widths).
+
+```html
+
+
+ .d-table-cell
+
+
+ d-table-cell .col-10
+
+
+```
+
+### Responsive display
+A selection of display utilities are able to be applied or changed per [breakpoint](/styleguide/css/modules/grid#breakpoints). `.d-block`, `.d-none`, `.d-inline`, and `.d-inline-block` are available as responsive utilities using the following formula: `d-[breakpoint]-[property]`. For example: `d-md-inline-block`. Each responsive display utility is applied to the specified breakpoint and up.
+
+In the following example, the `ul` element switches from `display: block` on mobile to `display: inline-block` at the `md` breakpoint, while the list items remain inline.
+
+```html
+
.d-md-inline-block
+
+
.d-inline
+
.d-inline
+
+```
+
+### Responsive hide
+Hide utilities are able to be applied or changed per breakpoint using the following formula: `hide-[breakpoint]`, for example: `hide-sm`. Hide utilities act differently from other responsive styles and are applied to each **breakpoint-range only**.
+
+| Shorthand | Range |
+| --- | --- |
+| -sm | 0—544px |
+| -md | 544px—768px |
+| -lg | 768px—1004px |
+| -xl | 1004px and above |
+
+```html
+
+```
+
+### Text direction
+`.direction-ltr` or `.direction-rtl` can be used to change the text direction. This is especially helpful when paired with `.d-table`, `.d-table-cell`, and `.v-align-middle` to create equal height, vertically centered, alternating content.
+
+## Visibility
+Adjust the visibility of an element with `.v-hidden` and `.v-visible`.
+
+## Overflow
+Adjust element overflow with `.overflow-hidden`, `.overflow-scroll`, and `.overflow-auto`. `.overflow-hidden` can also be used to create a new [block formatting context](https://developer.mozilla.org/en-US/docs/Web/Guide/CSS/Block_formatting_context) or clear floats.
+
+## Floats
+Use `.float-left` and `.float-right` to set floats, and `.clearfix` to clear.
+```html
+
+
+ .float-left
+
+
+ .float-right
+
+
+```
+### Responsive floats
+Float utilities can be applied or changed per [breakpoint](/styleguide/css/modules/grid#breakpoints). This can be useful for responsive layouts when you want an element to be full width on mobile but floated at a larger breakpoint.
+
+Each responsive float utility is applied to the specified breakpoint and up, using the following formula: `float-[breakpoint]-[property]`. For example: `float-md-left`. Remember to use `.clearfix` to clear.
+
+```html
+
+
+ .float-md-left
+
+
+ .float-md-right
+
+
+```
+
+## Alignment
+Adjust the alignment of an element with `.v-align-baseline`, `.v-align-top`, `.v-align-middle` or `.v-align-bottom`. The vertical-align property only applies to inline or table-cell boxes.
+
+```html
+
+
Potatoes
+
.v-align-baseline
+
.v-align-top
+
.v-align-middle
+
.v-align-bottom
+
+```
+
+Use `v-align-text-top` or `v-align-text-bottom` to adjust the alignment of an element with the top or bottom of the parent element's font.
+
+```html
+
+```
+
+## Position
+Position utilities can be used to alter the default document flow. **Be careful when using positioning, it's often unnecessary and commonly misused.**
+
+Use `.position-relative` to create a new stacking context.
+
+_Note how the other elements are displayed as if "Two" were in its normal position and taking up space._
+```html
+
+ One
+
+
+ Two
+
+
+ Three
+
+
+ Four
+
+```
+
+Use `.position-absolute` to take elements out of the normal document flow.
+
+```html
+
+```
+
+Use `.position-fixed` to position an element relative to the viewport. **Be careful when using fixed positioning. It is tricky to use and can lead to unwanted side effects.**
+
+_Note: fixed positioning has been disabled here for demonstration only._
+
+```html
+
+ .position-fixed
+
+```
+
+Use `top-0`, `right-0`, `bottom-0`, and `left-0` with `position-absolute`, `position-fixed`, or `position-relative` to further specify an elements position.
+
+```html
+
+
+ .top-0 .left-0
+
+
+ .top-0 .right-0
+
+
+ .bottom-0 .right-0
+
+
+ .bottom-0 .left-0
+
+
+```
+
+To fill an entire width or height, use opposing directions.
+
+_Note: fixed positioning has been disabled here for demonstration only._
+
+```html
+
+ .position-fixed .left-0 .right-0
+
+```
+
+### Screen reader only
+
+Use `.sr-only` to position an element outside of the viewport for screen reader access only. **Even though the element can't be seen, make sure it still has a sensible tab order.**
+
+```html
+
+
+
+
+ Button activated!
+
+
+```
+
+## The media object
+
+Create a media object with utilities.
+
+```html
+
+
+ Image
+
+
+
Body Bacon ipsum dolor amet shankle rump tenderloin pork chop meatball strip steak bresaola doner sirloin capicola biltong shank pig. Alcatra frankfurter ham hock, ribeye prosciutto hamburger kevin brisket chuck burgdoggen short loin.
+
+
+```
+Create a double-sided media object for a container with a flexible center.
+
+```html
+
+
+ Image
+
+
+ Image
+
+
+
Body Bacon ipsum dolor amet shankle rump tenderloin pork chop meatball strip steak bresaola doner sirloin capicola biltong shank pig. Alcatra frankfurter ham hock, ribeye prosciutto hamburger kevin brisket chuck burgdoggen short loin.
+
+
+```
+
+You can also create a media object with [flexbox utilities](./flexbox#media-object) instead of floats which can be useful for changing the vertical alignment.
diff --git a/modules/primer-utilities/docs/margin.md b/modules/primer-utilities/docs/margin.md
new file mode 100644
index 00000000..ed1447a2
--- /dev/null
+++ b/modules/primer-utilities/docs/margin.md
@@ -0,0 +1,126 @@
+---
+title: Margin
+status: Stable
+---
+
+Margin utilities are based on a global [spacing scale](/styleguide/css/styles/core/support/spacing) which helps keep horizontal and vertical spacing consistent. These utilities help us reduce the amount of custom CSS that share the same properties, and allows to achieve many different page layouts using the same styles.
+
+{:toc}
+
+## Naming convention
+
+Since margin utilities have many variations and will be used in many places, we use a shorthand naming convention to help keep class names succinct.
+
+
+| Shorthand | Description |
+| --- | --- |
+| m | margin |
+| t | top |
+| r | right |
+| b | bottom |
+| l | left |
+| x | horizontal, left & right |
+| y | vertical, top & bottom |
+| 0 | 0 |
+| 1 | 4px |
+| 2 | 8px |
+| 3 | 16px |
+| 4 | 24px |
+| 5 | 32px |
+| 6 | 40px |
+
+_**Note:** The blue in the examples represents the element, and the orange represents the margin_
+
+## Uniform spacing
+
+Use uniform spacing utilities to apply equal margin to all sides of an element. These utilities can change or override default margins, and can be used with a spacing scale from 0-6.
+
+```html
+
+
.m-0
+
+
+
.m-1
+
+
+
.m-2
+
+
+
.m-3
+
+
+
.m-4
+
+
+
.m-5
+
+
+
.m-6
+
+```
+
+## Directional spacing
+
+Use directional utilities to apply margin to an individual side, or the X and Y axis of an element. Directional utilities can change or override default margins, and can be used with a spacing scale of 0-6.
+
+```html
+
+
.mt-3
+
+
+
.mr-3
+
+
+
.mb-3
+
+
+
.ml-3
+
+
+
.my-3
+
+
+
.mx-3
+
+```
+
+## Center elements
+
+Use `mx-auto`to center block elements with a set width.
+
+```html
+
+
.mx-auto
+
+```
+
+## Reset margins
+Reset margins built into typography elements or other components with `m-0`, `mt-0`, `mr-0`, `mb-0`, `ml-0`, `mx-0`, and `my-0`.
+
+```html
+
No bottom margin on this paragraph.
+```
+
+## Responsive margins
+
+All margin utilities, except `mx-auto`, can be adjusted per [breakpoint](/styleguide/css/modules/grid#breakpoints) using the following formula: `m[direction]-[breakpoint]-[spacer]`. Each responsive style is applied to the specified breakpoint and up.
+
+```html
+
+
+ .mx-sm-2 .mx-lg-4
+
+
+```
+
+## Negative margins
+
+You can add negative margins to the top, right, bottom, or left of an item by adding a negative margin utility. The formula for this is: `m[direction]-n[spacer]`. This also works responsively, with the following formula: `m[direction]-[breakpoint]-n[spacer]`.
+
+```html
+
+
+ .mt-n4 .mr-lg-n6
+
+
+```
diff --git a/modules/primer-utilities/docs/padding.md b/modules/primer-utilities/docs/padding.md
new file mode 100644
index 00000000..94289f01
--- /dev/null
+++ b/modules/primer-utilities/docs/padding.md
@@ -0,0 +1,110 @@
+---
+title: Padding
+status: Stable
+---
+
+Padding utilities are based on a global [spacing scale](/styleguide/css/styles/core/support/spacing) which helps keep horizontal and vertical spacing consistent. These utilities help us reduce the amount of custom CSS that could share the same properties, and allows to achieve many different page layouts using the same styles.
+
+{:toc}
+
+## Shorthand
+
+Since padding utilities have many variations and will be used in many places, we use a shorthand naming convention to help keep class names succinct.
+
+| Shorthand | Description |
+| --- | --- |
+| p | padding |
+| t | top |
+| r | right |
+| b | bottom |
+| l | left |
+| x | horizontal, left & right |
+| y | vertical, top & bottom |
+| 0 | 0 |
+| 1 | 4px |
+| 2 | 8px |
+| 3 | 16px |
+| 4 | 24px |
+| 5 | 32px |
+| 6 | 40px |
+
+_**Note:** The blue in the examples below represents the element, and the green represents the padding._
+
+## Uniform spacing
+
+Use uniform spacing utilities to apply equal padding to all sides of an element. These utilities can be used with a spacing scale from 0-6.
+
+```html
+
+
.p-0
+
+
+
.p-1
+
+
+
.p-2
+
+
+
.p-3
+
+
+
.p-4
+
+
+
.p-5
+
+
+
.p-6
+
+```
+
+## Directional spacing
+
+Use directional utilities to apply padding to an individual side, or the X and Y axis of an element. Directional utilities can change or override default padding, and can be used with a spacing scale of 0-6.
+
+```html
+
+
.pt-3
+
+
+
.pr-3
+
+
+
.pb-3
+
+
+
.pl-3
+
+
+
.py-3
+
+
+
.px-3
+
+```
+
+## Responsive padding
+
+All padding utilities can be adjusted per [breakpoint](/styleguide/css/styles/core/support/breakpoints) using the following formula: `p-[direction]-[breakpoint]-[spacer]`. Each responsive style is applied to the specified breakpoint and up.
+
+```html
+
+
+ .px-sm-2 .px-lg-4
+
+
+```
+
+## Responsive container padding
+
+`.p-responsive` is a padding class that adds padding on the left and right sides of an element. On small screens, it gives the element padding of `$spacer-3`, on mid-sized screens it gives the element padding of `$spacer-6`, and on large screens, it gives the element padding of `$spacer-3`.
+
+It is intended to be used with [container styles](/styleguide/css/styles/core/objects/grid#containers)
+
+```html
+
+
+ .container-lg .p-responsive
+
+
+```
diff --git a/modules/primer-utilities/docs/typography.md b/modules/primer-utilities/docs/typography.md
new file mode 100644
index 00000000..eb829726
--- /dev/null
+++ b/modules/primer-utilities/docs/typography.md
@@ -0,0 +1,138 @@
+---
+title: Typography
+status: Stable
+---
+
+Type utilities are designed to work in combination with line-height utilities so as to result in more sensible numbers wherever possible. These also exist as [variables](/styleguide/css/styles/core/support/typography#typography-variables) that you can use in components or custom CSS.
+
+{:toc}
+
+Font sizes are smaller on mobile and scale up at the `md` [breakpoint](/styleguide/css/styles/core/support/breakpoints) to be larger on desktop.
+
+| Scale | Font size: mobile | Font size: desktop | 1.25 line height | 1.5 line height |
+| --- | --- | --- | --- | --- |
+| 00 | 40px | 48px | 60 | 72 |
+| 0 | 32px | 40px | 50 | 60 |
+| 1 | 26px | 32px | 40 | 48 |
+| 2 | 22px | 24px | 30 | 36 |
+| 3 | 18px | 20px | 25 | 30 |
+| 4 | 16px | 16px | 20 | 24 |
+| 5 | 14px | 14px | 17.5 | 21 |
+| 6 | 12px | 12px | 15 | 18 |
+
+
+## Heading utilities
+
+Use `.h1` – `.h6` to change an elements font size and weight to match our heading styles.
+
+```html
+
Pizza 1
+
Pizza 2
+
Pizza 3
+
Pizza 4
+
Pizza 5
+
Pizza 6
+```
+
+These are particularly useful for changing the visual appearance while keeping the markup semantically correct. Be sure you keep the hierarchy appropriate for the page.
+
+```html
+
Looks like a heading 1, semantically a heading 2
+```
+
+## Type scale utilities
+
+Use `.f1` – `.f6` to change an elements font size while keeping inline with our type scale.
+
+```html
+
Focaccia
+
Focaccia
+
Focaccia
+
Focaccia
+
Focaccia
+
Focaccia
+```
+
+Lighter font-weight utilities are available in a limited range. Lighter font-weights reduce the legibility of text, particularly at small font sizes, so the scale only goes down to `f3` at 20px. The larger sizes`f0` and `f00` allow for lighter and larger type that is in keeping with our marketing styles.
+
+```html
+
Potato chips
+
Potato chips
+
Potato chips
+
Potato chips
+
Potato chips
+```
+
+## Line height styles
+Change the line height density with these utilities.
+
+```html
+
+```
+
+## Text alignment
+
+ Use text alignment utilities to left align, center, or right align text.
+
+```html
+
Left align
+
Center
+
Right align
+```
+## Responsive text alignment
+
+Use the following formula to make a text alignment utility responsive: `.text-[breakpoint]-[alignment]`
+
+```html
+
Left in a small viewport, centered in mid-sized viewports, and right aligned in larger viewports
+```
+
+## List styles
+
+Remove bullets from an unordered list or numbers from an ordered list by applying `.list-style-none` to the `
`.
+
+```html
+
+
First list item
+
Second list item
+
Third list item
+
+```
+
+## Text Shadows
+
+Text shadows can be used to help readability and to add some depth on colored backgrounds.
+
+```html
+
+
.text-shadow-dark helps white text stand out on dark or photographic backgrounds
+
+
+
.text-shadow-light creates an embossed effect for dark text
+