USWDS Gulp pipeline for copying assets and compiling Sass
A simple Gulp 4.0 workflow for transforming USWDS Sass into browser-readable CSS.
Note: You do not need to clone this repo into your project. Follow the instructions below.
You'll need to be familiar with the command line.
You'll need to install the following packages via
If you've never installed Gulp, you'll need to install the Gulp command line interface:
npm install gulp-cli -g
Ensure your project has a
package.json file. You can create one by following the instructions on the USWDS fundamentals and quickstart guide.
Add all the required dependencies at once with following command from your project's root directory:
npm install autoprefixer gulp gulp-replace sass gulp-sass gulp-sourcemaps gulp-rename gulp-svg-sprite gulp-postcss postcss postcss-csso uswds uswds-gulp@github:uswds/uswds-gulp --save-dev
If you don't already have a project gulpfile, copy the
gulpfile.js to your current directory (the project root):
cp node_modules/uswds-gulp/gulpfile.js .
If you do already have a project gulpfile, copy and rename the USWDS gulpfile (then you can manually add the contents of the USWDS gulpfile to your existing gulpfile and continue with the instructions):
cp node_modules/uswds-gulp/gulpfile.js gulpfile-uswds.js
We use autoprefixer for maximum browser compatibility. To ensure you're targeting the correct browsers we use a
.browserslistrc file. If you don't already have one copy our file to your current directory (the project root):
cp node_modules/uswds-gulp/.browserslistrc .
If you already have a
.browserslistrc make sure you're targeting the following browsers:
> 2% last 2 versions IE 11 not dead
gulpfile.js in a text editor. In the
Paths section, set the following constants with the proper paths. Don't use trailing slashes in the paths. All paths should be relative to the project root.
PROJECT_SASS_SRC: The directory where we'll save your USWDS settings files and the project's custom Sass.
IMG_DEST: The directory where we'll save the USWDS images
FONTS_DEST: The directory where we'll save the USWDS fonts
CSS_DEST: The destination of the final, compiled CSS
gulpfile.js with these updated paths.
Initialize your USWDS project. Initialization does the following:
- Copies settings files and the USWDS base Sass file to your project Sass directory
- Compiles the USWDS Sass into a usable CSS file, called
Intitialize your USWDS project by running the following command:
Edit your USWDS settings in the new settings files and add custom Sass to the new
_uswds-theme-custom-styles.scss file. Watch these files and compile any changes with
Update SVG sprite
gulp init, the USWDS images will be moved into your project. Open the USWDS
images directory and find the
usa-icons-unused directories. Either add your own SVGs to the
usa-icons directory or move icons from
usa-icons and rebuild the sprite with