Update readme to improve customization instructions

[thisisdano]

Overview

This project's documentation is pretty sloppy. This PR goes a short way to improving it, but there's much farther to go. The general gist of these changes is that there a single directory for stylesheet-based customization: /_sass. This directory uses two critical files:

• _uswds-theme-settings.scss: The entry point for USWDS settings.
• _uswds-theme-custom-styles.scss: The entry point for new project Sass, overrides, etc.

uswds-theme-settings.scss

USWDS settings control the design system output. Use settings to assign your theme colors, typefaces, type scale, and component styling (among other things). All the settings available to the design system are documented in the Settings section of USWDS website. In uswds-jekyll, we suggest including only the settings variables you wish to change/override in the settings entry point, like:

// _uswds-theme-settings.scss

$theme-show-compile-warnings: false;
$theme-show-notifications: false;
$theme-color-primary-lightest: green-5;
$theme-color-primary-lighter: "green-10";
$theme-color-primary-light: "blue-30";
$theme-color-primary: "green-50";
$theme-color-primary-vivid: "green-50v";
$theme-color-primary-dark: "green-60";
$theme-color-primary-darker: "green-70";
$theme-color-primary-darkest: green-80;

You could also use the older USWDS approach and just grab all the available settings (in separate files) from https://github.com/uswds/uswds/tree/develop/src/stylesheets/theme, add each of these files to the /_sass directory, edit them individually, and then @import them all from the settings entry point. For instance, if you added all the USWDS theme files to /_sass/settings, you could then reference them in the entry point:

// _uswds-theme-settings.scss

@include "settings/uswds-theme-color.scss";
@include "settings/uswds-theme-components.scss";
@include "settings/uswds-theme-custom-styles.scss";
@include "settings/uswds-theme-general.scss";
@include "settings/uswds-theme-spacing.scss";
@include "settings/uswds-theme-typography.scss";
@include "settings/uswds-theme-utilities.scss";

But this approach can introduce errors into version-to-version updates, which is why we suggest the earlier approach.

In general, settings control the USWDS CSS. To add additional CSS or to override the design system beyond what settings allow, you need custom Sass.

uswds-theme-custom-styles.scss

Add any custom Sass or overrides into the custom styles entry point, or, like shown above, use the entry point to import multiple Sass files. All USWDS design tokens, as well as functions and mixins are available to this file or any file imported from it, so you can add USWDS-flavored Sass like:

// uswds-theme-custom-styles.scss

$my-cool-color: "blue-cool-40v";

.foo {
  @include typeset("sans", "sm", 3);
  @include u-margin-x(2);
  @include at-media("tablet") {
    background-color: color($my-cool-color);
  }
}

And, as above, you could use the entry point to import multiple custom style files if you added those files to the /_sass directory. For instance, if you added custom style files to /_sass/my-styles, you could then reference them in the entry point:

// uswds-theme-custom-styles.scss

@import "my-styles/theme.scss";
@import "my-styles/overrides.scss";
@import "my-styles/header.scss";
@import "my-styles/data-tables.scss";

[afeld]

Thank you! A couple small corrections; good to merge after that.