Merge branch 'master' into next

Author: simurai

MIGRATING.md

@@ -60,6 +60,10 @@ If you've installed Primer CSS with npm, you very likely already have `node_modu
 
 If you've installed Primer CSS with something _other than_ npm, or you don't know how it was installed, consult the documentation for your setup first, then [let us know][help] if you still can't figure it out.
 
+## Compiled CSS files
+
+The compiled CSS files can be found under `/dist` in case you want to directly link to them.
+
 ## Fonts
 The marketing-specific font files published in the [`fonts` directory](https://unpkg.com/[email protected]/fonts/) of `[email protected]` are published in the `fonts` directory of `@primer/css`. If you use these fonts, you'll need to do the following:
 

docs/content/components/box-overlay.md

@@ -56,23 +56,4 @@ Box overlays come in three widths. The default `Box--overlay` is 440px wide, `Bo
 <link href="https://unpkg.com/@github/details-dialog-element/index.css" rel="stylesheet" />
 ```
 
-In github.com there is a shared dialog partial. You will only have to pass in the modal content:
-
-```erb
-<%= render layout: "shared/details_dialog", locals: {
-  button_text: "Delete account",
-  title: "Are you sure you want to delete this account?",
-  button_class: "btn btn-danger"
-} do %>
-  <div class="Box-body overflow-auto">
-    <p>
-      This action is irreversible.
-    </p>
-    <button type="button" class="btn btn-block btn-danger mt-2" data-close-dialog>
-      Delete
-    </button>
-  </div>
-<% end %>
-```
-
 [aria attributes]: https://www.w3.org/TR/html-aria/#allowed-aria-roles-states-and-properties

docs/content/components/box.md

@@ -287,7 +287,7 @@ Use `Box-row--focus-gray` or `Box-row--focus-blue` when using along-side `naviga
 
 ### Box row unread
 
-Use `.Box-row-unread` to apply a blue vertical line highlight for indicating a row contains unread items.
+Use `.Box-row--unread` to apply a blue vertical line highlight for indicating a row contains unread items.
 
 ```html live
 <div class="Box">

docs/content/components/header.md

@@ -6,13 +6,11 @@ source: 'https://github.com/primer/css/tree/master/src/header'
 bundle: header
 ---
 
-Use the Header component to create a header that has all of it's items aligned vertically with consistent horizontal spacing.
-
-## Table of Contents
+Use the Header component to create a header that has all of its items aligned vertically with consistent horizontal spacing.
 
 ## Header
 
-The `.Header` class is the wrapping class that aligns all the items properly and gives the header it's dark background. Each direct child of the `.Header` component is expected to be a `.Header-item` component. The component utilizes flexbox CSS to align all these items properly and applies spacing scale margin.
+The `.Header` class is the wrapping class that aligns all the items properly and gives the header its dark background. Each direct child of the `.Header` component is expected to be a `.Header-item` component. The component utilizes flexbox CSS to align all these items properly and applies spacing scale margin.
 
 ```html live
 <div class="Header">

docs/content/components/labels.md

@@ -7,7 +7,7 @@ source: 'https://github.com/primer/css/tree/master/src/labels'
 bundle: labels
 ---
 
-Labels add metatdata or indicate status of items and navigational elements. Three different types of labels are available: [Labels](#default-label-styles) for adding metadata, [States](#states) for indicating status, and [Counters](#counters) for showing the count for a number of items.
+Labels add metadata or indicate status of items and navigational elements. Three different types of labels are available: [Labels](#default-label-styles) for adding metadata, [States](#states) for indicating status, and [Counters](#counters) for showing the count for a number of items.
 
 ## Labels
 
@@ -21,7 +21,7 @@ The base `Label` style does not apply a background color and only uses the defau
 <span class="Label" title="Label: design">design</span>
 ```
 
-**Note:** Be sure to include a title attribute on labels, it's helpful for people using screen-readers to differentiate a label from other text. I.e. without the title attribute, the following example would read as _"New select component design"_, rather than identifying `design` as a label.
+**Note:** Be sure to include a title attribute on labels, as it's helpful for people using screen-readers to differentiate a label from other text. For example, without the title attribute, the following case would read as _"New select component design"_, rather than identifying `design` as a label.
 
 ```html live
 <!-- Don't do this -->
@@ -60,9 +60,9 @@ Labels come in a few different themes. Use a theme that helps communicate the co
 
 Note: Avoid using `Label--orange` next to `Label--red` since most people will find it hard to tell the difference.
 
-## Issue Labels
+## Issue labels
 
-Issue Labels are used for adding labels to issues and pull requests. They also come with emoji support.
+Issue labels are used for adding labels to issues and pull requests. They also come with emoji support.
 
 ```html live
 <span class="IssueLabel bg-blue text-white mr-1" title="Label: Primer">Primer</span>
@@ -71,7 +71,7 @@ Issue Labels are used for adding labels to issues and pull requests. They also c
 <span class="IssueLabel bg-yellow text-gray-dark mr-1" title="Label: deploy: train">🚂 deploy: train</span>
 ```
 
-If an Issue Label needs to be bigger, add the `.IssueLabel--big` modifier.
+If an issue label needs to be bigger, add the `.IssueLabel--big` modifier.
 
 ```html live
 <span class="IssueLabel IssueLabel--big bg-blue text-white mr-1" title="Label: Primer">Primer</span>
@@ -133,7 +133,7 @@ Use `State--small` for a state label with reduced padding a smaller font size. T
 
 ## Counters
 
-Use the `Counter` component to add a count to navigational elements and buttons. Counters come in 3 variations: the default `Counter` with a light gray background, the `Counter--gray-light` with a lighter text color, and `Counter--gray` with a dark-gray background and inverse white text. When a counter is empty, it's visibility will be hidden.
+Use the `Counter` component to add a count to navigational elements and buttons. Counters come in 3 variations: the default `Counter` with a light gray background, the `Counter--gray-light` with a lighter text color, and `Counter--gray` with a dark-gray background and inverse white text. When a counter is empty, its visibility will be hidden.
 
 ```html live
 <span class="Counter mr-1">1</span>
@@ -194,7 +194,7 @@ Diffstats show how many deletions or additions a diff has. It's typically a row
 </span>
 ```
 
-Use the `text-green` and `text-red` utilities to add addtitional information about the size of the diff.
+Use the `text-green` and `text-red` utilities to add additional information about the size of the diff.
 
 ```html live
 <span class="diffstat">

docs/content/support/breakpoints.md

@@ -6,20 +6,50 @@ source: 'https://github.com/primer/css/blob/master/src/support/variables/layout.
 bundle: support
 ---
 
-Our breakpoints are based on screen widths where our content starts to break. Since most of GitHub is currently a fixed-width with we use pixel widths to make it easy for us to match page widths for responsive and non-responsive pages. **Our breakpoints may change as we move more of the product into responsive layouts.**
+Our breakpoints are based on screen widths where our content starts to break. **Our breakpoints may change as we move more of the product into responsive layouts.**
 
-We use abbreviations for each breakpoint to keep the class names concise. This abbreviated syntax is used consistently across responsive styles. Responsive styles allow you to change the styles properties at each breakpoint. For example, when using column widths for grid layouts, you can change specify that the width is 12 columns wide at the small breakpoint, and 6 columns wide from the large breakpoint: `<div class="col-sm-12 col-lg-6">...</div>`
+We use abbreviations for each breakpoint to keep the class names concise. This abbreviated syntax is used consistently across responsive styles. Responsive styles allow you to change the styles properties at each breakpoint. For example, when using column widths for grid layouts, you can specify that the width is 12 columns wide by default, 8 columns from the medium breakpoint, and 4 columns wide from the extra large breakpoint: `<div class="col-12 col-md-8 col-xl-4">...</div>`.
 
-| Breakpoint  | Syntax | Description       |
-| ----------- | ------ | ----------------- |
-| Small       | sm     | min-width: 544px  |
-| Medium      | md     | min-width: 768px  |
-| Large       | lg     | min-width: 1012px |
-| Extra-large | xl     | min-width: 1280px |
+| Breakpoint  | Syntax | Breaks at |
+| ----------- | ------ | ----------|
+| Small       | sm     | `544px`   |
+| Medium      | md     | `768px`   |
+| Large       | lg     | `1012px`  |
+| Extra-large | xl     | `1280px`  |
 
-**Note:** The `lg` breakpoint matches our current page width of `980px` including left and right padding of `16px` (`$spacer-3`). This is so that content doesn't touch the edges of the window when resized.
+Responsive styles are available for [margin](/utilities/margin#responsive-margins), [padding](/utilities/padding#responsive-padding), [layout](/utilities/layout), [flexbox](/utilities/flexbox#responsive-flex-utilities), the [grid](/objects/grid#responsive-grids) system, and many more.
 
-Responsive styles are available for [margin](/utilities/margin#responsive-margins), [padding](/utilities/padding#responsive-padding), [layout](/utilities/layout), [flexbox](/utilities/flexbox#responsive-flex-utilities), and the [grid](/objects/grid#responsive-grids) system.
+## Breakpoint and up... 🛫
+
+In most cases, breakpoints get used with the `min-width` media query. This means that when using a responsive utility class, the class becomes "enabled" from the breakpoint on upwards. Or from the browser's perspective, when the browser's width **is** the breakpoint or **wider**.
+
+| Breakpoint  | Syntax | Is enabled...            |
+| ----------- | ------ | -------------------------|
+| None        |        | from `0px` upwards ->    |
+| Small       | sm     | from `544px` upwards ->  |
+| Medium      | md     | from `768px` upwards ->  |
+| Large       | lg     | from `1012px` upwards -> |
+| Extra-large | xl     | from `1280px` upwards -> |
+
+A responsive utility class stays enabled **unless** it gets overridden with another responsive utility class that has a higher breakpoint. Here the example from above `<div class="col-12 col-md-8 col-xl-4">...</div>` visualized: 
+
+```
+| 0px -> 
+         | 544px ->  
+         | sm
+                    | 768px ->  
+                    | md 
+                               | 1012px ->  
+                               | lg
+                                           | 1280px ->
+                                           | xl
+
+| col-12 ---------> | col-md-8 ----------> | col-xl-4 ->
+```
+
+Using breakpoints with the `min-width` media query works great for "mobile first". Design for mobile devices as a default, then if needed, tweak it for wider desktop screens using responsive utility classes.
+
+Note: The [responsive hide](/utilities/layout#responsive-hide) utilities are an exception and use a range between two breakpoints. They also go the other direction "breakpoint and down... 🛬". For example `.hide-md` hides an element if the browser's width is between `sm <-> md` (`544px - 767px`).
 
 ## Breakpoint variables
 
@@ -49,7 +79,7 @@ $breakpoints: (
 
 Use media query mixins when you want to change CSS properties at a particular breakpoint. The media query mixin works by passing in a breakpoint value, such as `breakpoint(md)`.
 
-Media queries are scoped from each breakpoint and upwards. In the example below, the font size is `28px` until the viewport size meets the `lg` breakpoint, from there upwards—including through the `xl` breakpoint—the font size will be `32px`.
+Media queries are scoped from each breakpoint and upwards. In the example below, the font size is `28px` until the viewport size meets the `md` breakpoint, from there upwards—including through the `xl` breakpoint—the font size will be `32px`.
 
 ```scss
 .styles {

docs/content/support/color-system.mdx

@@ -2,7 +2,8 @@
 title: Color system
 description: 'Sass variables, mixins, and functions for use in our components.'
 status: Stable
-status_issue: 'https://github.com/github/design-systems/issues/301'
+source: 'https://github.com/primer/css/blob/master/src/support/variables/color-system.scss'
+bundle: support
 ---
 
 import colors from 'primer-colors'

docs/content/support/spacing.md

@@ -41,4 +41,4 @@ We aim for whole numbers, however, GitHub's body font-size is 14px which is diff
 | `$em-spacer-5` | 1/2      | .5             | 35                               | 40                   |
 | `$em-spacer-6` | 3/4      | .75            | 42                               | 48                   |
 
-The variables listed above are preferred for use within components and custom CSS. To calculate values with other font-sizes or em values, we suggest using [Formula](http://jxnblk.com/formula).
+The variables listed above are preferred for use within components and custom CSS. To calculate values with other font-sizes or em values, we suggest using [Formula](https://jxnblk.github.io/formula/).

docs/content/utilities/borders.mdx

@@ -12,8 +12,6 @@ import {PaletteTable, PaletteCell, PaletteValue} from '../../src/color-system'
 
 Utilities for borders, border radius, and box shadows.
 
-## Table of Contents
-
 ## Default border
 
 The default border utility applies a solid, 1px border, with a default gray color.