Import only the USWDS Core design language

uswds-core-import.md

Using only the core USWDS design language in your project

So, USWDS source files are written in a language called Sass and need to be compiled into CSS to be browser-readable. We use a task-runner called Gulp to do this compiling, and we have a project called uswds-gulp that outlines one way to set it up.

Essentially you'll want the compiler to look for the following files, in the following order:

1. USWDS Settings files
2. USWDS Core files
3. Your project stylesheets

Settings files

Your settings files are a set of user-settable variables that control USWDS output. You can read more abiout them here in our settings documentation. A settings file overrides USWDS defaults to adapt to your project's code and style needs. For instance:

// Sample settings file

$theme-image-path:              "../uswds/img";
$theme-font-path:               "../uswds/fonts"
$theme-show-compile-warnings:   false;

$theme-color-primary-family:    "blue"
$theme-color-primary-lightest:  "#{$theme-color-primary-family}-5";
$theme-color-primary-lighter:   "#{$theme-color-primary-family}-10";
$theme-color-primary-light:     "#{$theme-color-primary-family}-30";
$theme-color-primary:           "#{$theme-color-primary-family}-50";
$theme-color-primary-vivid:     "#{$theme-color-primary-family}-50v";
$theme-color-primary-dark:      "#{$theme-color-primary-family}-60";
$theme-color-primary-darker:    "#{$theme-color-primary-family}-70";
$theme-color-primary-darkest:   "#{$theme-color-primary-family}-90";

$theme-font-type-sans:          "system";

You can see some more complete examples of USWDS settings files in our Github repo.

Importing USWDS

Say you have a project like the following — with some stylesheets written in Sass, USWDS included via npm, and your compiled CSS in an assets directory:

├── assets
│   └── css
│       └── styles.css
├── node_modules
│   └── uswds
│       ├── dist
│       │   └── scss
│       │       ├── packages
│       │       │   ├── _global.scss
│       │       │   ├── _layout-grid.scss
│       │       │   ├── _required.scss
│       │       │   ├── _typography.scss
│       │       │   ├── _usa-accordion.scss
│       │       │   ...
│       │       └── uswds.scss
│       ...
├── stylesheets
│   ├── styles.scss
│   └── includes
│       ├── _body.scss
│       ├── _footer.scss
│       ├── _header.scss
│       └── _uswds-settings.scss

styles.scss (Sass entry point)

This is your Sass entry point. A task runner like Gulp targets when running the compile process. The entry point should link out to all the necessary stylesheets in your project with include statements.

Here we see the styles.scss file for our demo project.

1. First, it imports USWDS settings.

2. Then, instead of importing all of USWDS, it uses the concept of packages, described in the documentation, to include only the USWDS core token definitions, mixins, and fuctions, in a file called _required.scss. (Note that neither the underscrore nor the suffix are necessary in the include statement.)

3. Finally, it imports all the project stylesheets.

// 1. USWDS Settings files
@import "includes/uswds-settings";

// 2. USWDS Core files
@import "../node_modules/uswds/dist/scss/packages/required";

// 3. Your project stylesheets
@import "includes/body";
@import "includes/footer";
@import "includes/header";

Importing only the USWDS required package outputs no CSS. It only includes the USWDS design language, the token definitions, variables, mixins, and functions used by USWDS v2. Now you can use this functionality in your own stylesheets, and use some of the guidance on the USWDS migrations page to start to convert your existing stylesheets into the USWDS design language.

Updating code

For example, if you had some existing code like the following:

$project-cream: #f6f6ef;
$project-cream: #111;

.my-card {
  background-color: $project-cream;
  border: 2px solid $project-black;
  border-radius: 6px;
  font-family: Source Sans Pro;
  font-size: 16px;
  font-weight: bold;
  line-height: 1.25;
  margin-bottom: 15px;
  margin-top: 15px;
  padding: 10px;
}

You are now able to express it with the following USWDS tokens, mixins, and functions, include in the USWDS core:

$project-cream: color("gold-5");
$project-cream: color("gray-90");

.my-card {
  @include typeset("sans", "md", 3);
  @include u-margin-y(2);
  background-color: $project-cream;
  border: units(2px) solid $project-black;
  border-radius: units(0.5);
  font-weight: fw("bold");
  padding: units(1);
}

Use this technique as a lightweight way to experiment with integrating the USWDS design language into your existing stylesheets.

Would be worth creating a minimum core package with just utilities and tokens. This way users can pull just core styles from a CDN to prototype or demo without bringing in the entire framework.