Copyedit and sync with current USWDS 2.0 code

_components/typography/typography.md

@@ -19,4 +19,7 @@ subnav:
   href: '#lists'
 ---
 
+<div class="bg-warning padding-1 radius-sm measure-4"><strong>Note:</strong> Typography in USWDS 2.0 has some notable changes from USWDS 1.x that are not yet reflected in this documentation. Updated guidance will appear sometime in October 2018.</div>
+
+
 {% include child-sections.html parent='typography' %}

_components/utilities/border.md

@@ -622,7 +622,7 @@ utilities:
     {% for color in all_colors %}
       <dt class="output-utility">.border-{{ color.token }}</dt>
       <dd class="output-css">
-        <span class="output-rule">border-color: {% if color.var %}<span class="output-token">{{ color.var }}</span>{% else %}{{ color.token }}{% endif %}</span>
+        <span class="output-rule">border-color: <span class="output-token">color('{{ color.token }}')</span></span>
       </dd>
       <dd class="output-variable">
         {% if color.var %}

_components/utilities/color.md

@@ -142,7 +142,7 @@ utilities:
       <h3 class="font-sans-4 margin-top-0 padding-bottom-1 margin-bottom-1 border-gray-10 border-bottom-1px">Project theme colors <a class="utility-examples-helper" href="#0">Read more about project theme colors</a></h3>
       <div class="grid-row">
         {% for color in theme_colors %}
-          <p class="utility-example-container-condensed grid-col-12 display-flex flex-align-center">
+          <p class="utility-example-container-condensed grid-col-12 display-flex flex-align-center measure-none">
             <span class="flex-fill">
               <span class="square-4 radius-sm display-inline-block text-middle margin-right-1 bg-{{ color.token }}"></span>
               <span class="utility-class">.bg-{{ color.token }}</span>
@@ -160,7 +160,7 @@ utilities:
       <h3 class="font-sans-4 margin-top-4 padding-bottom-1 margin-bottom-1 border-gray-10 border-bottom-1px">Grayscale palette <a class="utility-examples-helper" href="#0">Read more about the USWDS grayscale palette</a></h3>
       <div class="grid-row">
         {% for color in grayscale_colors %}
-          <p class="utility-example-container-condensed grid-col-12 display-flex flex-align-center">
+          <p class="utility-example-container-condensed grid-col-12 display-flex flex-align-center measure-none">
             <span class="flex-fill">
               <span class="square-4 radius-sm display-inline-block text-middle margin-right-1 bg-{{ color.token }}"></span>
               <span class="utility-class">.bg-{{ color.token }}</span>
@@ -178,7 +178,7 @@ utilities:
       <h3 class="font-sans-4 margin-top-4 padding-bottom-1 margin-bottom-1 border-gray-10 border-bottom-1px">Basic palette <a class="utility-examples-helper" href="#0">Read more about the USWDS basic palette</a></h3>
       <div class="grid-row">
         {% for color in basic_colors %}
-          <p class="utility-example-container-condensed grid-col-12 display-flex flex-align-center">
+          <p class="utility-example-container-condensed grid-col-12 display-flex flex-align-center measure-none">
             <span class="flex-fill">
               <span class="square-4 radius-sm display-inline-block text-middle margin-right-1 bg-{{ color.token }}"></span>
               <span class="utility-class">.bg-{{ color.token }}</span>
@@ -204,15 +204,15 @@ utilities:
   <dl class="output-list">
     {% for color in all_colors %}
       <dt class="output-utility">.text-{{ color.token }}</dt>
-      <dd class="output-css">color: <span class="output-token">{% if color.var %}{{ color.var }}{% else %}{{ color.token }}{% endif %}</span></dd>
+      <dd class="output-css">color: <span class="output-token">color('{{ color.token }}')</span></dd>
       <dd class="output-variable">
         <span class="display-inline-block bg-{{ color.token }} circle-105 text-baseline margin-right-05"></span>
         {{ color.value }}
       </dd>
     {% endfor %}
     {% for color in all_colors %}
       <dt class="output-utility">.bg-{{ color.token }}</dt>
-      <dd class="output-css">background-color: <span class="output-token">{% if color.var %}{{ color.var }}{% else %}{{ color.token }}{% endif %}</span></dd>
+      <dd class="output-css">background-color: <span class="output-token">color('{{ color.token }}')</span></dd>
       <dd class="output-variable">
         <span class="display-inline-block bg-{{ color.token }} circle-105 text-baseline margin-right-05"></span>
         {{ color.value }}

_components/utilities/display.md

@@ -846,8 +846,8 @@ utilities:
 
     {% for item in site.data.uswds_tokens.opacity %}
       <dt class="output-utility">.opacity-{{ item.token }}</dt>
-      <dd class="output-css"><span>opacity: {{ item.value }}</span></dd>
-      <dd class="output-variable">—</dd>
+      <dd class="output-css"><span>opacity: <span class="output-token">opacity({{ item.token }})</span></span></dd>
+      <dd class="output-variable">{{ item.value }}</dd>
     {% endfor %}
 
     {% assign overflow_modifiers = ", -x, -y"
@@ -970,8 +970,8 @@ utilities:
 
     {% for value in site.data.uswds_tokens.z_index %}
       <dt class="output-utility">.z-{{ value.token }}</dt>
-      <dd class="output-css"><span>z-index: {{ value.value }}</span></dd>
-      <dd class="output-variable">—</dd>
+      <dd class="output-css"><span>z-index: <span class="output-token">z-index({{ value.token }})</span> </span></dd>
+      <dd class="output-variable">{{ value.value }}</dd>
     {% endfor %}
 
   </dl>

_components/utilities/font-size-and-family.md

@@ -268,7 +268,8 @@ utilities:
   [class*='font-serif-'] { font-family: "Merriweather Web" ... serif; }
   [class*='font-alt-'] { font-family: "Source Sans Pro Web" ... sans-serif; }
   [class*='font-heading-'] { font-family: "Merriweather Web" ... serif; }
-  [class*='font-body-'] { font-family: "Merriweather Web" ... serif; }
+  [class*='font-ui-'] { font-family: "Source Sans Pro Web" ... sans-serif; }
+  [class*='font-body-'] { font-family: "Source Sans Pro Web" ... sans-serif; }
   [class*='font-code-'] { font-family: "Roboto Mono Web" ... monospace; }
   ```
   </div>
@@ -289,7 +290,7 @@ utilities:
 
           <dd class="output-css grid-col-5">
             <span>
-                <span class="output-rule">font-size: <span class="output-token">type-scale({{ face.style }}, {{ size[1].token }})</span></span>
+                <span class="output-rule">font-size: <span class="output-token">font-size('{{ face.style }}', '{{ size[1].token }}')</span></span>
             </span>
           </dd>
 
@@ -314,7 +315,7 @@ utilities:
 
             <dd class="output-css grid-col-5">
               <span>
-                  <span class="output-rule">font-size: <span class="output-token">type-scale({{ role }}, {{ size[1].token }})</span></span>
+                  <span class="output-rule">font-size: <span class="output-token">font-size('{{ role }}', '{{ size[1].token }}')</span></span>
               </span>
             </dd>
 
@@ -335,7 +336,7 @@ utilities:
         <dt class="output-utility grid-col-3">.font-family-{{ face.style }}</dt>
         <dd class="output-css grid-col-5">
           <span>
-              <span class="output-rule">font-family: <span class="output-token">$font-stack-{{ face.style }}</span></span>
+              <span class="output-rule">font-family: <span class="output-token">font-family('{{ face.style }}')</span></span>
           </span>
         </dd>
         <dd class="output-variable grid-col-4">{{ face.stack }}</dd>
@@ -348,7 +349,7 @@ utilities:
         <dt class="output-utility grid-col-3">.font-family-{{ role }}</dt>
         <dd class="output-css grid-col-5">
           <span>
-            <span class="output-rule">font-family: <span class="output-token">$font-stack-{{ role }}</span></span>
+            <span class="output-rule">font-family: <span class="output-token">font-family('{{ role }}')</span></span>
           </span>
         </dd>
         <dd class="output-variable grid-col-4">{{ face.stack }}</dd>

_components/utilities/layout-grid.md

@@ -56,17 +56,21 @@ subnav:
 </div>
 
 <div markdown="1">
-The above example creates three equal-width columns on tablet, desktop, and widescreen devices using our predefined grid classes. Those columns are centered in the page with the parent `.grid-container` container.
+The above example creates three equal-width columns on tablet, desktop, and widescreen devices using our predefined grid classes. Those columns are centered in the page with the parent `grid-container` container.
 
 Breaking it down, here's how it works:
 
-- **Containers** `.grid-container` centers the container and gives it a maximum width of 1024px. If you would like the grid to span the full width of the page, do not use `.grid-container`. `grid-container` can also accept any breakpoint width like `grid-container-tablet-lg` or `grid-container-widescreen`.
-- **Rows** Columns must have a `.grid-row` as a parent.
-- **Columns** `.grid-col-[1-12]` indicates the number of columns the item spans out of a possible 12 per row. So, if you want three equal-width columns across, use `.grid-col-4` for each item.
-- With flexbox, grid columns without a specified width will display as equal-width columns. For example, four instances of `.grid-col` will display as one-quarter-width columns across all sizes. See the [auto-layout columns](#auto-layout-columns) section for more examples.
-- Rows and columns don't have any gutters by default, but they can be added by adding `.grid-gap-sm`, `.grid-gap`, or `.grid-gap-lg` at the row level. See [gutters](#gutters) for more info.
+- **Containers** `grid-container` centers the container and gives it a maximum width of `desktop` (1024px). If you would like the grid to span the full width of the page, do not use `grid-container`.
+
+  `grid-container` can also accept any breakpoint width like `grid-container-tablet-lg` or `grid-container-widescreen`. Set the default max width with `$theme-site-max-width` in `uswds-theme-spacing.scss`.
+
+  By default, `grid-container`s have padding-x of 2 units, with a padding-x of 4 units at `desktop` and wider. Control these values with the values of `$theme-site-margins-mobile-width`, `$theme-site-margins-width` and `$theme-site-margins-beakpoint` in `uswds-theme-spacing.scss`.
+- **Rows** Columns must have a `grid-row` as a parent.
+- **Columns** `grid-col-[1-12]` indicates the number of columns the item spans out of a possible 12 per row. So, if you want three equal-width columns across, use `grid-col-4` for each item.
+- With flexbox, grid columns without a specified width will display as equal-width columns. For example, four instances of `grid-col` will display as one-quarter-width columns across all sizes. See the [auto-layout columns](#auto-layout-columns) section for more examples.
+- Rows and columns don't have any gutters by default, but they can be added by adding `grid-gap-sm`, `grid-gap`, or `grid-gap-lg` at the row level. See [gutters](#gutters) for more info.
 - Grid breakpoints are based on minimum width media queries, meaning they apply to that specific width and all greater widths (e.g., `tablet:col-4` applies to tablet, desktop, and widescreen devices, but not at `mobile-lg` or any width below the tablet breakpoint). See [responsive variants](#responsive-variants) for full list.
-- You can use predefined grid classes (like `.grid-col-4`) for presentational markup or [Sass mixins](#sass-mixins) for more semantic markup.
+- You can use predefined grid classes (like `grid-col-4`) for presentational markup or [Sass mixins](#sass-mixins) for more semantic markup.
 
 </div>
 
@@ -114,8 +118,8 @@ Breaking it down, here's how it works:
 
 <h2 id="auto-layout-columns">Auto layout columns</h2>
 <h3>Variable width content</h3>
-<p><code class="docs-inline-code">.grid-col-auto</code> items fit the natural width of their content.</p>
-<p><code class="docs-inline-code">.grid-col</code> and <code class="docs-inline-code">.grid-col-fill</code> items flex to fill the available space.</p>
+<p><code>.grid-col-auto</code> items fit the natural width of their content.</p>
+<p><code>.grid-col</code> and <code>.grid-col-fill</code> items flex to fill the available space.</p>
 
 
 <div class="docs-grid-example">
@@ -145,8 +149,8 @@ Breaking it down, here's how it works:
 
 <h2 id="responsive-classes">Responsive classes</h2>
 <h3>Same at all breakpoints</h3>
-<p>For columns that should maintain the same proportion at any viewport width, use the <code class="docs-inline-code">.grid-col</code> and <code class="docs-inline-code">.grid-col-*</code> classes. Specify a numbered class when you need a column of a specific width; otherwise, use <code class="docs-inline-code">.grid-col</code>.</p>
-<p><code class="docs-inline-code">.grid-col-[1-12]</code> set a fixed width of [n] grid-columns in a 12-column grid.</p>
+<p>For columns that should maintain the same proportion at any viewport width, use the <code>.grid-col</code> and <code>.grid-col-*</code> classes. Specify a numbered class when you need a column of a specific width; otherwise, use <code>.grid-col</code>.</p>
+<p><code>.grid-col-[1-12]</code> set a fixed width of [n] grid-columns in a 12-column grid.</p>
 
 {% capture grid-markers %}
 <div class="grid-row margin-top-1 font-sans-2">
@@ -221,7 +225,7 @@ Breaking it down, here's how it works:
 </div>
 
 <h3>Stacked columns at narrow widths</h3>
-<p>Columns are full-width until the narrowest breakpoint specified in a <code class="docs-inline-code">.grid-col</code> class. For instance, using a single set of <code class="docs-inline-code">tablet:grid-col-*</code> classes, you can create a basic grid system that starts out stacked before displaying as columns at the tablet breakpoint (<code class="docs-inline-code">tablet:</code>).</p>
+<p>Columns are full-width until the narrowest breakpoint specified in a <code>.grid-col</code> class. For instance, using a single set of <code>tablet:grid-col-*</code> classes, you can create a basic grid system that starts out stacked before displaying as columns at the tablet breakpoint (<code>tablet:</code>).</p>
 
 <div class="docs-grid-example">
 {% capture grid-stacked %}
@@ -288,7 +292,7 @@ Breaking it down, here's how it works:
 </div>
 
 <h2 id="offsetting-columns">Offsetting columns</h2>
-<p><code class="docs-inline-code">.grid-offset-[1-12]</code> offsets the item by the specified number of grid columns.</p>
+<p><code>.grid-offset-[1-12]</code> offsets the item by the specified number of grid columns.</p>
 {{ grid-markers }}
 
 <div class="docs-grid-example">
@@ -339,11 +343,11 @@ Breaking it down, here's how it works:
 
 <h2 id="gutters">Gutters</h2>
 
-<h3>Default gutter</h3>
-<p>Add <code class="docs-inline-code">.grid-gap</code> to a grid row to add a gap (or gutter) between each column in the row. The default gap width is 16px (2 spacing units). Customize the width of the gap by adjusting the value of <code class="docs-inline-code">$theme-column-gap</code> in project settings.</p>
-{{ grid-markers }}
+### Default gutter
+Add `grid-gap` to a grid row to add a gap (or gutter) between each column in the row. The default gap width is 2 units and 4 units at `desktop` and higher. Customize the width of the gap by adjusting the value of `$theme-column-gap` in project settings.
 
-<div class="docs-grid-example">
+{{ grid-markers }}
+<div class="docs-grid-example margin-top-2">
 {% capture grid-gutters %}
 <div class="grid-row grid-gap">
   <div class="grid-col-4">
@@ -372,16 +376,16 @@ Breaking it down, here's how it works:
 </div>
 
 <h3>Large gutter</h3>
-<p><code class="docs-inline-code">.grid-gap-lg</code> adds a larger gap (or gutter) between each column in a row. The default large gap width is 32px (4 spacing units). Customize the width of the large gap by adjusting the value of <code class="docs-inline-code">$theme-column-gap-lg</code> in project settings. There is also a <code class="docs-inline-code">.grid-gap-sm</code> (2px) set with <code class="docs-inline-code">$theme-column-gap-sm</code>. Also, you can add the following system values with <code class="docs-inline-code">.grid-gap</code>:</p>
+<p><code>grid-gap-lg</code> adds a larger gap (or gutter) between each column in a row. The default large gap width is 32px (4 spacing units). Customize the width of the large gap by adjusting the value of <code>$theme-column-gap-lg</code> in project settings. There is also a <code>.grid-gap-sm</code> (2px) set with <code>$theme-column-gap-sm</code>. Also, you can add the following system values with <code>grid-gap</code>:</p>
 <div markdown="1">
-- `.grid-gap-2px`
-- `.grid-gap-05`
-- `.grid-gap-1`
-- `.grid-gap-2`
-- `.grid-gap-3`
-- `.grid-gap-4`
-- `.grid-gap-5`
-- `.grid-gap-6`
+- `grid-gap-2px`
+- `grid-gap-05`
+- `grid-gap-1`
+- `grid-gap-2`
+- `grid-gap-3`
+- `grid-gap-4`
+- `grid-gap-5`
+- `grid-gap-6`
 </div>
 {{ grid-markers }}
 
@@ -421,12 +425,30 @@ When generating your CSS from USWDS source files, you have the option of customi
 ### Variables
 Variables and maps determine the number of columns, the gutter width, and the media query point at which to begin floating columns. We use these to generate the predefined grid classes documented above, as well as for the custom mixins listed below.
 
+{:.font-mono-xs}
+#### uswds-theme-spacing.scss
+
 ```scss
-$theme-column-gap:     16px;
-$theme-column-gap-lg:  32px;
+// Values are set as units tokens.
+
+$theme-column-gap-sm:               2px;
+$theme-column-gap-md:               2;
+$theme-column-gap-lg:               3;
+$theme-column-gap-mobile:           2;
+$theme-column-gap-desktop:          4;
+$theme-grid-container-max-width:    'desktop';
+$theme-site-max-width:              'desktop';
+$theme-site-margins-breakpoint:     'desktop';
+$theme-site-margins-width:          4;
+$theme-site-margins-mobile-width:   2;
+```
+
+{:.font-mono-xs}
+#### uswds-theme-utilities.scss
 
+```scss
 // Turn on or off breakpoints
-$theme-output-breakpoints: (
+$theme-utility-breakpoints: (
   'card':              false,   // 160px
   'card-lg':           false,   // 240px
   'mobile':            false,   // 320px
@@ -437,8 +459,6 @@ $theme-output-breakpoints: (
   'desktop-lg':        false,   // 1200px
   'widescreen':        false,   // 1400px
 );
-
-$theme-grid-container-max-width: desktop;
 ```
 
 ### Mixins

_components/utilities/overview.md

@@ -17,17 +17,17 @@ USWDS provides useful default set of utilities that developers can extended and
 
 ## Utility naming
 
-Most USWDS utilities are built to assign a single CSS property a single value. Our utilities are named `.[base]-[value]` where `[base]` is almost always the name of the CSS property the utility targets, with the parts separated by a hyphen. Our utility classes are designed to make sense at a glance to anyone familiar with standard CSS selectors.
+Most USWDS utilities are built to assign a single CSS property a single value. Our utilities are named `.[base]-[value]` where `[base]` is almost always the name of the CSS property the utility targets, with the parts separated by a hyphen. Our utility classes are designed to make sense at a glance to anyone familiar with standard CSS properties.
 
 The utility values are drawn from your project theme's settings tokens, but can be extended to include additional values drawn from our palette of common units (like px, em, ch, and percentages) as well as the broader USWDS system palette of colors, grid spacing, and font scale. (See Utility settings for more on customization.)
 
 ### Examples
 
-USWDS utility | CSS
+USWDS utility | Sass
 --- | ---
-`.background-color-primary-darker` | `{ background-color: $color-primary-darker; }`
-`.background-color-red-50v` | `{ background-color: $color-red-50v }`
+`.background-color-primary-darker` | `{ background-color: color('primary-darker'); }`
+`.background-color-red-50v` | `{ background-color: color('red-50v'); }`
 `.text-decoration-underline` | `{ text-decoration: underline; }`
 `.margin-x-auto` | `{ margin-left: auto; margin-right: auto; }`
-`.padding-bottom-1` | `{ padding-bottom: 8px }`
+`.padding-bottom-1` | `{ padding-bottom: units(1); }`
 {: .usa-table-borderless}