A Yeoman generator for the U.S. Draft Web Design Standards!
This isn't published on npm yet, but for now you can install it with:
npm install -g github:18F/generator-uswds
Alternatively (or if you want to contribute!) you can clone this repo then run:
npm install
npm link
cd my-new-project
yo uswds
After you run this generator, your directory structure should look like this:
your-project/ ├── css/ ├── fonts/ ├── images/ ├── js/ ├── sass/ ├── page-templates/ └── package.json
Note the pattern: each type of file gets its own top-level directory, and (with the exception of css
) each of them has a vendor/uswds
subtree containing the static USWDS assets of that type. This layout is meant to accommodate the addition of site-specific assets alongside USWDS. Each directory contains a README.md
(in Markdown) describing its contents. Here is an overview:
The css
directory contains CSS generated from the Sass source files in scss
. The CSS files are minified to discourage direct editing.
The USWDS custom fonts (Merriweather and Source Sans Pro) live in the fonts/vendor/uswds
directory. Additional fonts can be placed in this directory and referenced from the [Sass][#sass].
The USWDS images live in the images/vendor/uswds
directory. Additional images can be placed in this directory, and may be referenced relatively from the Sass, e.g. in background-image
properties via url(../images/path/to/image.png)
.
The js
directory contains your site's JavaScript:
js/vendor/uswds
contains both minified and un-minified versions ofuswds.js
. You should always useuswds.min.js
in your templates unless you need to be able to debug USWDS and lack a browser with [source map] support.main.js
is a placeholder for your site's custom scripts, and is imported out of the box in the page templates.
This directory contains both of the USWDS page templates as standalone HTML files. We suggest copying these files and customizing them for your needs rather than editing them in place. This can make it easier to test customizations that you make to the Sass, and allows you to compare changes that you've made in other pages to the originals if you end up breaking something by accident.
The sass
directory contains all of the Sass source files for the USWDS and a main.scss
file from which you can customize the system. We suggest working in this file to get a feel for it, then factoring your work into additional Sass "partials" for more component-oriented CSS rules. For instance, you could organize your sass
directory like this:
├── my-project/ | ├── _all.scss | └── # other files imported by _all.scss ├── vendor/uswds/... ├── _variables.scss └── main.scss
Then your main.scss
could be structured like so:
# this should go before importing uswds
@import 'variables';
@import 'vendor/uswds/all';
# and this should go after if your styles override uswds rules in any way
@import 'my-project/all';
See tasks below for more information on regenerating the CSS files from Sass.
Your package.json
tells npm about your project's JavaScript dependencies. After your directory is created, the Yeoman generator runs npm install
to install the depenencies used for building your CSS file(s) from the Sass sources.
The package.json
defines the following tasks in the scripts
section:
-
npm start
(ornpm run start
)Starts a web server in your project directory so that you can preview your site at
http://127.0.0.1:8080
. -
npm run build:css
-
npm run build
Runs
npm run build:css
. In the future we may include other build commands for different asset types.