Merge pull request #1424 from uswds/dev-guide-updates_uswds-compile

Dev guide updates uswds compile

_components/icon/guidance/implementation.md

@@ -1,5 +1,5 @@
 - **Don’t alter icons.** You shouldn’t customize, combine, or change the icons (other than updating the color) due to their [license](https://github.com/uswds/uswds/blob/develop/LICENSE.md), as described on GitHub.
-- **Active icons are found in `dist/img/usa-icons`.** The icons in this directory will be packaged into an SVG sprite. The complete set of available icons are located in two directories: `dist/img/material-icons` and `dist/img/uswds-icons`. Copy icons into a `usa-icons` directory within your project images directory and rebuild the SVG sprite using [uswds-gulp](https://github.com/uswds/uswds-gulp/).
+- **Active icons are found in `dist/img/usa-icons`.** The icons in this directory will be packaged into an SVG sprite. The complete set of available icons are located in two directories: `dist/img/material-icons` and `dist/img/uswds-icons`. Copy icons into a `usa-icons` directory within your project images directory, and rebuild the SVG sprite using [uswds-compile](https://github.com/uswds/uswds-compile/).
 - **Using color in icons.** Icons use `currentColor`, so the color of the icon will be the text color of its parent element. Change colors with the [color utility](https://designsystem.digital.gov/utilities/color/).
 - **Relative to font size.** By default, icons will scale with font size. If you want to specify an icon size, use one of the component’s size variants.
 - **Icon names are identifiers.** To use an individual, simply change the identifier after the pound sign in the sprite path to the icon name. For example, to use the `accessibility_new` icon, the path will be `<use xlink:href="/path/to/sprite.svg#accessibility_new">` or to use the `info` icon, the path will be `<use xlink:href="/path/to/sprite.svg#info">`.

pages/documentation/developers.md

@@ -6,7 +6,7 @@ category: How to use USWDS
 lead: USWDS components are built on a solid HTML foundation, progressively enhanced to provide core experiences across browsers. All users will have access to the same critical information and basic experience regardless of their browser, although those experiences will render better in newer browsers. If JavaScript fails users will still get a robust HTML foundation and all the necessary content.
 subnav:
 - text: Installation
-  href: '#download-and-install'
+  href: '#installation'
 - text: CSS architecture
   href: '#css-architecture'
 - text: JS customization

pages/documentation/getting-started-developers/overview.md

@@ -2,7 +2,7 @@
 permalink: /documentation/getting-started-for-developers/
 layout: styleguide
 title: Getting started for developers
-lead: Get started using the design system by installing, compiling, and customizing USWDS code
+lead: Get started using the Design System by installing, compiling, and customizing our code.
 category: How to use USWDS
 type: docs
 subnav:
@@ -14,25 +14,25 @@ redirect_from:
   - /documentation/fundamentals/
 ---
 
-Getting started for developers will lead you, step-by-step, through the process of installing and compiling the Design System and customizing your project using components and design tokens. If you prefer a hands-on demonstration of this process, please check out [our interactive tutorial](https://github.com/uswds/uswds-tutorial), which will take you through the same steps using a pre-made example website.
+Getting started for developers will lead you, step by step, through the process of installing and compiling the U.S. Web Design System and customizing your project using components and design tokens. If you prefer a hands-on demonstration of this process, please check out [our interactive tutorial](https://github.com/uswds/uswds-tutorial), which will take you through the same steps using a pre-made example website.
 
 As always, we're here for you if you have any questions. Please get in touch via GitHub, Slack, or email!
 
 
 ## What you need
-We recommend using the following tools when working with USWDS:
+We recommend using the following tools when working with the Design System:
 - Node (use the version specified in the [.nvmrc file](https://github.com/uswds/uswds/blob/main/.nvmrc); if needed, [download the latest version](https://nodejs.org/en/download/) from Node.js)
 - npm
 - Sass (we use [the latest `sass` package from npm](https://www.npmjs.com/package/sass))
 
-These step-by-step instructions describe how to get started with USWDS using npm (recommended method).
+These step-by-step instructions describe how to get started with the Design System using npm (recommended method).
 
-If npm is not a viable tool for your project, however, you can [download and install the system directly](https://github.com/uswds/uswds#download-and-install) as outlined in GitHub.
+If npm is not a viable tool for your project, however, you can [download and install the Design System directly](https://github.com/uswds/uswds#download-and-install) as outlined in GitHub.
 
-We’ve designed USWDS to support older and newer browsers through [progressive enhancement](https://en.wikipedia.org/wiki/Progressive_enhancement). The design system follows the [2% rule](https://gds.blog.gov.uk/2012/01/25/support-for-browsers/): we officially support any browser above 2% usage as observed by [analytics.usa.gov](https://analytics.usa.gov/). In other words, USWDS version 2.0 supports Chrome, Firefox, Safari, Edge, and Internet Explorer 11 and up. The next major version of USWDS (3.0) will drop support of Internet Explorer 11.
+We’ve built the Design System to support older and newer browsers through [progressive enhancement](https://en.wikipedia.org/wiki/Progressive_enhancement). We follow the [2% rule](https://gds.blog.gov.uk/2012/01/25/support-for-browsers/): we officially support any browser above 2% usage as observed by [analytics.usa.gov](https://analytics.usa.gov/). In other words, Design System version 2.0 supports Chrome, Firefox, Safari, Edge, and Internet Explorer 11 and up. The next major version of the Design System (3.0) will drop support of Internet Explorer 11.
 
 ## Step-by-step
-Get started with USWDS by installing the design system on your project, compiling your project's Sass from the USWDS source, and customizing the design system to fit your project needs as outlined in the following phases:
+Get started by installing the Design System on your project, compiling your project's Sass from the Design System source, and customizing the Design System to fit your project needs as outlined in the following phases:
 
 [**Phase 1: Install**]({{ site.baseurl }}/documentation/getting-started/developers/phase-one-install/) →
 

pages/documentation/getting-started-developers/phase-one.md

@@ -3,7 +3,7 @@ permalink: /documentation/getting-started/developers/phase-one-install/
 layout: styleguide
 title: "Phase 1: Install"
 category: How to use USWDS
-lead: Install design system files and source code into your project
+lead: Install Design System files and source code into your project.
 type: docs
 subnav:
   - text: "Step 1: Install Node and npm"
@@ -14,23 +14,17 @@ subnav:
     href: "#step-3-install-uswds"
 ---
 
-USWDS distributes our source code through npm, a package manager that uses a flavor of JavaScript called Node.js. The best way to add USWDS to your project is with npm via a Terminal window (see tips for using Terminal on a [Mac](https://support.apple.com/guide/terminal/open-or-quit-terminal-apd5265185d-f365-44cb-8b09-71a064a42125/mac) or [Windows](https://www.microsoft.com/en-us/p/windows-terminal/9n0dx20hk701?rtc=1&activetab=pivot:overviewtab)). 
+The U.S. Web Design System distributes our source code through npm, a package manager that uses a flavor of JavaScript called Node.js. The best way to add the Design System to your project is with npm via a Terminal window (check out some tips for using Terminal on a [Mac](https://support.apple.com/guide/terminal/open-or-quit-terminal-apd5265185d-f365-44cb-8b09-71a064a42125/mac) or [Windows](https://www.microsoft.com/en-us/p/windows-terminal/9n0dx20hk701?rtc=1&activetab=pivot:overviewtab)). 
 
-Installing USWDS with Node and npm not only allows you to install all the code the design system needs to compile with just a couple commands, but using npm will version any installed packages, like USWDS, as well — meaning your project code is tied to a specific version of the design system. Confirming what version of the design system you’re using and updating to a newer (or older) version of the design system is straightforward.
+Installing the Design System with Node and npm not only allows you to install all the code the Design System needs to compile with just a couple commands, but will version any installed packages, like USWDS, as well — meaning your project code is tied to a specific version of the Design System. Confirming what version you’re using and updating to a newer (or older) version is straightforward.
 
 ## Step 1: Install Node and npm
-Open your Terminal application and a Terminal window. Check to see if you have the [most recent version of Node](https://github.com/uswds/uswds/blob/develop/.nvmrc) installed with `node -v`. You should see the following message in Terminal:
+Open your Terminal application and a Terminal window. Check to see if you have the [most recent version of Node](https://github.com/uswds/uswds/blob/develop/.nvmrc) installed with `node -v`.
 
-{:.site-terminal}
-```bash
-node -v
-# v12.16.1 [or higher]
-```
-
-If you don’t have Node, install it from [https://nodejs.org/en/download/](https://nodejs.org/en/download/).
+If you don’t have Node, install it from [Node.js](https://nodejs.org/en/download/).
 
 ## Step 2: Initialize your project in Node
-Once you have Node and npm installed, go to the root of your project directory in Terminal. The root is the topmost directory associated with your project, the directory that includes all your project files and directories. The root will appear in Terminal as follows:
+Once you have Node and npm installed, go to the root of your project directory in Terminal. The root is the topmost directory associated with your project, the directory that includes all your project files and directories. In Terminal, the root will read as follows:
 
 {:.site-terminal}
 ```bash
@@ -48,7 +42,7 @@ npm init
 # ...
 ```
 
-This initialization will start a series of prompts at the command line. Usually the defaults (which are noted in parentheses) are okay for a simple project. You can always edit these values later. Once this process is finished, you’ll have a new package.json file in the root, which will appear as follows:
+This initialization will start a series of prompts at the command line. Usually the defaults (which are noted in parentheses) are okay for a simple project. You can always edit these values later. Once this process is finished, you’ll have a new package.json file in the root, which will read as follows:
 
 {:.site-terminal}
 ```bash

pages/documentation/getting-started-developers/phase-three.md

@@ -3,26 +3,28 @@ permalink: /documentation/getting-started/developers/phase-three-customize/
 layout: styleguide
 title: "Phase 3: Customize"
 category: How to use USWDS
-lead: Customize the design system with settings and custom code
+lead: Customize the Design System with settings and custom code.
 type: docs
 ---
 
-Now, equipped with building blocks that are accessible and cohesive, you can get creative. Here is an overview of what you need to know to customize your project: 
+Now, equipped with building blocks that are accessible and cohesive, you can get creative. This phase is an overview of what you need to know to customize your project.
 
-{: .site-note }
-**Note:** If you use `uswds-gulp`, as detailed in Phase 2, this tool adds each of the files mentioned below to the directory you specify in `PROJECT_SASS_SRC`.
-
-USWDS provides extensive support for theming via its theme settings files. The critical files you'll need in your project are the following, which are located in `dist/scss/theme`:
+The U.S. Web Design System provides extensive support for theming via its theme settings files. The files you'll need in your project are the following, which are located in `uswds.paths.dist.theme`:
 -	`_uswds-theme-color.scss` — color settings
 -	`_uswds-theme-components.scss` — component settings
 -	`_uswds-theme-general.scss` — general settings
 -	`_uswds-theme-spacing.scss` — spacing settings
 - `_uswds-theme-typography.scss` — typography settings
 -	`_uswds-theme-utilities.scss` — utility class output settings
 
+{: .site-note }
+**Note:** If you use `uswds-compile`, as detailed in Phase 2, this tool adds each of these files to the directory you specify in `uswds.paths.dist.theme`.
+
+Because `uswds.paths.dist.theme` will be updated as the Design System updates, we recommend copying these files into an "overrides" (or similarly titled) folder and customizing them there.
+
 The [USWDS Settings page]({{ site.baseurl }}/documentation/settings/) describes each of the settings available in the settings files, as well as the values the settings accept. Most settings accept design tokens, visit the [Design tokens section]({{ site.baseurl }}/design-tokens/) of our website for more information on the available tokens for [color]({{ site.baseurl }}/design-tokens/color), [spacing units]({{ site.baseurl }}/design-tokens/spacing-units), [font size]({{ site.baseurl }}/design-tokens/typesetting/font-size/), and more.
 
-You can also use `uswds-gulp` to watch for any changes to your project Sass and recompile the CSS. Watch and recompile with the following command:
+You can also use `uswds-compile` to watch for any changes to your project Sass and recompile the CSS. Watch and recompile with the following command:
 
 {:.site-terminal}
 ```bash
@@ -31,6 +33,6 @@ npx gulp watch
 
 This command will run in your Terminal window. When you want to shut it down, use `control-c`.
 
-Our showcase illustrates how other teams of developers and designers have taken the building blocks USWDS provides and redesigned them for their brand and message.
+Our [showcase](https://designsystem.digital.gov/getting-started/showcase/all/) illustrates how other teams of developers and designers have taken the building blocks the Design System provides and redesigned them for their brand and message. We hope the possibilities inspire your team!
 
 We’re looking forward to hearing about your experience and seeing how USWDS's components look in your project!