diff --git a/_components/icon/guidance/implementation.md b/_components/icon/guidance/implementation.md index 931e664e8..262b1311c 100644 --- a/_components/icon/guidance/implementation.md +++ b/_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 `` or to use the `info` icon, the path will be ``. diff --git a/pages/documentation/developers.md b/pages/documentation/developers.md index ccf316545..32056378d 100644 --- a/pages/documentation/developers.md +++ b/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 diff --git a/pages/documentation/getting-started-developers/overview.md b/pages/documentation/getting-started-developers/overview.md index 1b91f054f..c7aaef22f 100644 --- a/pages/documentation/getting-started-developers/overview.md +++ b/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/) → diff --git a/pages/documentation/getting-started-developers/phase-one.md b/pages/documentation/getting-started-developers/phase-one.md index 027dc6634..e7f6e1eba 100644 --- a/pages/documentation/getting-started-developers/phase-one.md +++ b/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 diff --git a/pages/documentation/getting-started-developers/phase-three.md b/pages/documentation/getting-started-developers/phase-three.md index 45ffcfa7a..dc1e1d18a 100644 --- a/pages/documentation/getting-started-developers/phase-three.md +++ b/pages/documentation/getting-started-developers/phase-three.md @@ -3,16 +3,13 @@ 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 @@ -20,9 +17,14 @@ USWDS provides extensive support for theming via its theme settings files. The c - `_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! diff --git a/pages/documentation/getting-started-developers/phase-two.md b/pages/documentation/getting-started-developers/phase-two.md index 58bde32f7..538746776 100644 --- a/pages/documentation/getting-started-developers/phase-two.md +++ b/pages/documentation/getting-started-developers/phase-two.md @@ -3,34 +3,32 @@ permalink: /documentation/getting-started/developers/phase-two-compile/ layout: styleguide title: "Phase 2: Compile" category: How to use USWDS -lead: Compile design system source code into browser-readable files +lead: Compile Design System source code into browser-readable files. type: docs subnav: - text: "Step 1: Set up your project’s Sass entry point" href: "#step-1-set-up-your-projects-sass-entry-point" - - text: "Step 2: Install uswds-gulp" - href: "#step-2-install-uswds-gulp" - - text: "Step 3: Add configuration files" - href: "#step-3-add-configuration-files" - - text: "Step 4: Configure Gulp" - href: "#step-4-configure-gulp" + - text: "Step 2: Install uswds-compile" + href: "#step-2-install-uswds-compile" + - text: "Step 3: Create a gulpfile" + href: "#step-3-create-a-gulpfile" + - text: "Step 4: Create path settings and export compile functions" + href: "#step-4-create-path-settings-and-export-compile-functions" - text: "Step 5: Initialize your project" href: "#step-5-initialize-your-project" - text: "Step 6: Verify successful installation" href: "#step-6-verify-successful-installation" --- -USWDS source code is written in [Sass](https://sass-lang.com/), a powerful stylesheet language that builds automation, functions, and logic into CSS. Browsers can’t read native Sass files, so these files need to be compiled into CSS — usually a single CSS file — before we can use them. Basically, when you develop with USWDS, you do all your stylesheet work in Sass, then use a compiler to convert that Sass into CSS. We use [Gulp](https://gulpjs.com/), a task manager, to watch our directories for changes and compile our CSS whenever a change occurs. +U.S. Web Design System source code is written in Sass, a powerful stylesheet language that builds automation, functions, and logic into CSS. Browsers can’t read native Sass files, so these files need to be compiled into CSS — usually a single CSS file — before we can use them. Basically, when you develop with the Design System, you do all your stylesheet work in Sass then use a compiler to convert that Sass into CSS. -We’ve developed [`uswds-gulp`](https://github.com/uswds/uswds-gulp), a tool hosted on GitHub, to help teams install Gulp and get up and running as quickly as possible. In addition to compiling, `uswds-gulp` will also [autoprefix]({{ site.baseurl }}/documentation/developers/#sass-compilation-requirements) your CSS, minify it for performance, and add sourcemaps for easier debugging. If you project doesn't already have a Sass-compiling workflow in place, check out `uswds-gulp`. +We’ve developed `uswds-compile`, a tool hosted on GitHub, to help teams copy USWDS static assets and transform USWDS Sass into browser-readable CSS. [Step 2](#step-2-install-uswds-compile) describes how to install this tool. When you use `uswds-compile`, we will apply Autoprefixer to all compiled code. -The following steps use `uswds-gulp` to compile USWDS Sass. +{: .site-note } +**Note:** If you want `uswds-compile` to set up a Sass entry point for you, skip directly to [Step 2](#step-2-install-uswds-compile). We provide Step 1 for context: why you need a Sass entry point, what it needs to include, and how to set one up manually. ## Step 1: Set up your project’s Sass entry point -{: .site-note } -**Note:** If you want `uswds-gulp` to set up a Sass entry point for you, you don't need to set up any files in Step 1 and can skip directly to [Step 2, below](#step-2-install-uswds-gulp). Step 1 gives some important context: why you need a Sass entry point, what it needs to include, and how to set one up manually. - A project often has many Sass files, but typically, there’s a single file that serves as the root — the “homepage” of the Sass — that links out to the others. This root file is also known as the “Sass entry point.” The Sass entry point is the most important stylesheet file in your project because it tells the compiler what source files make up your Sass codebase. Your project’s Sass entry point is a simple file that only needs to do the following three tasks: @@ -38,18 +36,18 @@ Your project’s Sass entry point is a simple file that only needs to do the fol 2. Include the USWDS source code 3. Include your project’s custom Sass -Create an entry point called something like `index.scss` or `styles.scss`. Your entry point should look like the following example: +Create an entry point called something like `index.scss` or `styles.scss`. Your entry point should read like the following example: {:.site-terminal} ```scss // Include a USWDS settings file (required) -@include "uswds-settings.scss"; +@import "uswds-settings.scss"; // Point to the USWDS source code (required) -@include "./path/to/source/uswds"; +@import "./path/to/source/uswds"; // Include your project's custom Sass (optional) -@include "project-custom.scss"; +@import "project-custom.scss"; ``` In plain language, this code says: @@ -79,79 +77,98 @@ In plain language, this code says: The USWDS source code is the core of the design system. It contains all the styles for USWDS components as well as the design language of Sass tokens and functions used to build those components. USWDS source code has its own Sass entry point, which lives in the `node_modules` directory when you install USWDS with npm. - The entry point itself is called `uswds.scss`, and it’s found in the `/dist/scss` directory of the USWDS npm package. When you install with npm, the complete path looks something is typically `./node_modules/uswds/dist/scss/uswds.scss`. +The entry point itself is called `uswds.scss`, and it’s found in the `/dist/scss` directory of the USWDS npm package. When you install with npm, the complete path looks something is typically `./node_modules/uswds/dist/scss/uswds.scss`. - **Build new work on top of that foundation**: Finally, add any custom project styles built from design system code. - After you import the USWDS source code, you can build new styles with USWDS design tokens, functions, and mixins. For the purposes of this guide, we won’t get into custom code, but the important thing to understand is that any custom code should follow the settings and USWDS source code in your Sass entry point. +After you import the USWDS source code, you can build new styles with USWDS design tokens, functions, and mixins. For the purposes of this guide, we won’t get into custom code, but the important thing to understand is that any custom code should follow the settings and USWDS source code in your Sass entry point. -## Step 2: Install uswds-gulp -From your project’s root, run the following command to install `uswds-gulp` and all its dependencies: +## Step 2: Install uswds-compile +From your project’s root, run the following command to install `uswds-compile`: {:.site-terminal} ```bash -npm install autoprefixer gulp gulp-replace sass del gulp-sass gulp-sourcemaps gulp-rename gulp-svg-sprite gulp-postcss postcss postcss-csso uswds uswds-gulp@github:uswds/uswds-gulp --save-dev +npm install @uswds/compile --save-dev ``` -## Step 3: Add configuration files -Gulp needs the following two files to compile USWDS properly: -- **`gulpfile.js`**: This file tells Gulp where to look for your files and what to do with them. -- **`.browserslistrc`**: This file tells Gulp how to build the CSS so it works in all the browsers that USWDS supports. +## Step 3: Create a gulpfile +Create a file called `gulpfile.js` at the root of your project by running the command `touch gulpfile.js` (alternatively, use an existing gulpfile if one already exists). This file needs to do the following: +- import the `@uswds/compile` package +- set any project settings +- export the functions and/or tasks you need -We include these files in the `uswds-gulp` package. Install them in your project by copying them from the package into your project root. From the project root, run the following two commands separately: +Your `gulpfile.js` may read as follows: -{:.site-terminal} -```bash -cp node_modules/uswds-gulp/gulpfile.js . -cp node_modules/uswds-gulp/.browserslistrc . -``` + {:.site-terminal} + ```scss +/* gulpfile.js */ -## Step 4: Configure Gulp -Now, edit `gulpfile.js` to configure it for your project. Starting at line 37 in `gulpfile.js`, update the following settings — each of which needs a valid project directory (note: the sixth setting, `const SITE_CSS_DEST`, is only relevant if you are using Jekyll): +const uswds = require("@uswds/compile"); -{:.site-terminal} -```js -// Project Sass source directory -// Where should we put the USWDS Sass theme files? -// Ex: PROJECT_SASS_SRC = "./stylesheets" -const PROJECT_SASS_SRC = "./path/to/project/sass"; - -// Images destination -// Where should we save USWDS image assets? -// Ex: IMG_DEST = "./assets/uswds/img" -const IMG_DEST = "./path/to/images/destination"; - -// Fonts destination -// Where should we save USWDS fonts? -// Ex: FONTS_DEST = "./assets/uswds/fonts" -const FONTS_DEST = "./path/to/fonts/destination"; - -// Javascript destination -// Where should we save USWDS javascript? -// Ex: JS_DEST = "./assets/uswds/js" -const JS_DEST = "./path/to/js/destination"; - -// Compiled CSS destination -// Where should we save compiled USWDS CSS? -// Ex: CSS_DEST = "./assets/uswds/css" -const CSS_DEST = "./path/to/css/destination"; - -// Site CSS destination -// Like the _site/assets/css directory in Jekyll, if necessary. -// If using, uncomment line 106 -// Ex: SITE_CSS_DEST = "./_site/assets/uswds/css" -const SITE_CSS_DEST = "./path/to/site/css/destination"; -``` +/** + * Path settings + * Set as many as you need + */ -Don’t include a trailing slash in any of these paths. +uswds.paths.dist.css = './assets/css'; +uswds.paths.dist.sass = './sass'; -Save this file, and you’re ready to get started. +/** + * Exports + * Add as many as you need + */ -## Step 5: Initialize your project -Initialize your project to copy all the necessary image, font, and Javascript assets from the source code. Initialization will also add a Sass entry point called `styles.scss` in the directory you set as `PROJECT_SASS_SRC` (as outlined in Step 3) for your project. +exports.init = uswds.init; +exports.compile = uswds.compile; + ``` + +## Step 4: Create path settings and export compile functions +Now, create your path settings using the following table: + +
+ +{: .usa-table } +Setting | Default | Description +--- | --- | --- +`paths.src.uswds` | `"./node_modules/uswds/dist"` | Source location of the `uswds` package +`paths.src.sass` | `"./node_modules/uswds/dist/scss"` | Source location of the USWDS Sass +`paths.src.theme` | `"./node_modules/uswds/dist/scss/theme"` | Source location of the USWDS theme files (Sass entry point and starter settings files) +`paths.src.fonts` | `"./node_modules/uswds/dist/fonts"` | Source location of the USWDS fonts +`paths.src.img` | `"./node_modules/uswds/dist/img"` | Source location of the USWDS images +`paths.src.js` | `"./node_modules/uswds/dist/js"` | Source location of the USWDS compiled JavaScript files +`paths.src.projectSass` | `"./sass"` | Source location of any existing project Sass files outside of `paths.dist.sass`.
The `watch` script will watch this directory for changes. +`paths.dist.sass` | `"./sass"` | Project destination for theme files (Sass entry point and settings) +`paths.dist.img` | `"./assets/uswds/images"` | Project destination for images +`paths.dist.fonts` | `"./assets/uswds/fonts"` | Project destination for fonts +`paths.dist.js` | `"./assets/uswds/js"` | Project destination for compiled JavaScript +`paths.dist.css` | `"./assets/uswds/css"` | Project destination for compiled CSS + +
+ +Note, the `src` settings are specific to the Design System; the `dist` settings are specific to your project. + +Once your paths are set, export uswds-compile functions (summarized in the following table) in your project's gulpfile.js to use them in your project: + +Function | Description +--- | --- +`compile` | `compileSass` + `compileIcons` +`compileIcons` | Build the USWDS icon sprite into `paths.dist.img` +`compileSass` | Compile Sass into `paths.dist.css` +`default` | `watch` +`copyAll` | `copySetup` + `copyAssets` +`copyAssets` | Copies all static assets: `copyFonts` + `copyImages` + `copyJS` +`copyFonts` | Copy USWDS fonts to `paths.dist.fonts` +`copyImages` | Copy USWDS images to `paths.dist.img` +`copyJS` | Copy USWDS compiled JavaScript to `paths.dist.js` +`copySetup` | Copy USWDS theme files (Sass entry point and settings files) from the `uswds` package to `paths.dist.sass` +`init` | `copyAll` + `compile` +`updateUswds` | `copyAssets` + `compile` +`watch` | Compiles, then recompiles when there are changes to Sass files in `paths.dist.sass` and `paths.src.projectSass` + +For any function you defined as an `export` in your `gulpfile.js`, you can run `npx gulp [function]`. -{:.site-note} -**Note**: Initialization will overwrite files already in `PROJECT_SASS_SRC`. +## Step 5: Initialize your project +Initialize your project to copy all the necessary image, font, and Javascript assets from the source code. Initialize your project and get started by running the following command: @@ -159,11 +176,12 @@ Initialize your project and get started by running the following command: ```bash npx gulp init ``` +If you receive the error `replaceAll is not a function` when trying to run `npx gulp init`, please verify you are using the version of Node specified in the [.nvmrc file](https://github.com/uswds/uswds/blob/main/.nvmrc) and run the command again. This command will add all the USWDS assets to the directories you set, add a project Sass entry point, and compile USWDS into CSS. Add this CSS file to the `` of your project HTML. ## Step 6: Verify successful installation -Any time you want to recompile your CSS, run `npx gulp build-sass` from the command line in your project root. +Any time you want to recompile your CSS, run `npx gulp compileSass` from the command line in your project root. To verify whether you’ve successfully installed USWDS and that compilation is working, we recommend confirming the directory structure matches the paths you have updated in `gulpfile.js`, copying a few [components]({{ site.baseurl }}/components/overview/), pasting them into an HTML page, and then visiting that page in the browser to see if the components appear as expected. diff --git a/pages/documentation/maturity-model.md b/pages/documentation/maturity-model.md index e1a27d4cb..fe48d3acb 100644 --- a/pages/documentation/maturity-model.md +++ b/pages/documentation/maturity-model.md @@ -118,15 +118,15 @@ Government websites include components that aren’t included in USWDS yet. Use #### 1: Add USWDS code and adjust settings. -- Add USWDS to your project [with NPM]({{ site.baseurl }}/documentation/developers/#install-using-npm) or by [downloading the source from Github]({{ site.baseurl }}/documentation/developers/#download-and-install). -- Compile the Sass source code using the [guidelines in the documentation]({{ site.baseurl }}/documentation/developers/#sass-compilation-requirements) or by using [uswds-gulp](https://github.com/uswds/uswds-gulp) available via GitHub. -- Compile the Javascript source code using the [guidelines in the documentation]({{ site.baseurl }}/documentation/developers/#js-customization) or [download a precompiled version]({{ site.baseurl }}/documentation/developers/#download-and-install). +- Add USWDS to your project [with NPM]({{ site.baseurl }}/documentation/developers/#install-using-npm) or by [downloading the source from Github]({{ site.baseurl }}/documentation/developers/#download-and-install-without-npm). +- Compile the Sass source code using the [guidelines in the documentation]({{ site.baseurl }}/documentation/developers/#sass-compilation-requirements) or by using [uswds-compile](https://github.com/uswds/uswds-compile) available via GitHub. +- Compile the Javascript source code using the [guidelines in the documentation]({{ site.baseurl }}/documentation/developers/#js-customization) or [download a precompiled version]({{ site.baseurl }}/documentation/developers/#download-and-install-without-npm). - Add USWDS Javascript to your page templates. - Add USWDS CSS to your page templates. #### 2: Use USWDS design tokens in all stylesheets. -- Install USWDS source Sass files using [the instructions]({{ site.baseurl }}/documentation/developers/#download-and-install) on the USWDS website. +- Install USWDS source Sass files using [the instructions]({{ site.baseurl }}/documentation/developers/#download-and-install-without-npm) on the USWDS website. - Include USWDS Sass before including existing project source files. See [Sass an theme settings]({{ site.baseurl }}/documentation/developers/#sass-and-theme-settings). - Convert existing values to tokenized values. Use [the conversion tables](/documentation/migration/#integrating-tokens) to convert existing values to USWDS tokens. - Use USWDS [tokens]({{ site.baseurl }}/design-tokens/), functions (see [font-family functions]({{ site.baseurl }}/design-tokens/typesetting/font-family/#using-family-tokens), for example), and utility mixins (see [font-family utility mixins]({{ site.baseurl }}/design-tokens/typesetting/font-family/#using-family-tokens), for example) in existing component code.