uswds-jekyll 4.2.0 → 5.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d66abed686bf7cab270424ed9e27df903f6fd3a8b6e5992a8af32572365c0a07
-  data.tar.gz: 3ed7ff3610291b1b97e9d58f2bafdf520f29be82e69fb4952943804e396ec13b
+  metadata.gz: e5e338726e8357ad03b9947d7ddd0b977b5658671627d2f068fe6a05cb22002f
+  data.tar.gz: 42f04fbefa5c026573c1190baecbbb79065917375f9f8e41ad8aab3377b0430b
 SHA512:
-  metadata.gz: 07edf05992481180980340d152539871b98a877065455f3efa92b5498971f9b5ec52f1d00e461ad0870c5bc933b9edf85762f6833760a89bda6e2a7f4c0e7504
-  data.tar.gz: 160780e8ac43fec6e728b7f53e492e452276a15ecec4fd9ba711d175e22a4c349079a454322bec929a8eae506c45e295f124467d0efe3bc05d3808f89387311c
+  metadata.gz: 33fa5198894809d8031f7c1fa9923502c124f930e32463fdb8d7330b6ac18d0211aa42620be8b2b27c288135c05fc376f8a90eac379a6509c5f7621b0ae2c88d
+  data.tar.gz: f826137b0b11b0c427866588c610e0ff35462363d3e255cdcffeb128faf183124935bdf309413978092dc888ab547cb93e3b2d7a85b85a9c47667e233f6a23ea

data/README.md

@@ -4,175 +4,146 @@ This is a [Jekyll theme](https://jekyllrb.com/docs/themes/) for the
 [U.S. Web Design System](https://designsystem.digital.gov).
 
 ## Table of contents
+
 1. [Installation](#installation)
-    - [Development](#development)
-    - [Versioning](#versioning)
+   - [Versioning](#versioning)
 1. [Configuration](#configuration)
-    - [Site title](#site-title)
-    - [Site description](#site-description)
-    - [Navigation](#navigation)
-    - [Page subnavigation](#page-subnavigation)
-    - [Hero](#hero)
-    - [Tagline intro](#tagline-intro)
-    - [Graphics list](#graphics-list)
-    - [Color and font configuration](#color-and-font-configuration)
-    - [Search](#search)
-    - [Analytics](#analytics)
-    - [Last modified date](#last-modified-date)
-    - [Anchor JS](#anchor-js)
+   - [Site title](#site-title)
+   - [Site description](#site-description)
+   - [Navigation](#navigation)
+   - [Page subnavigation](#page-subnavigation)
+   - [Hero](#hero)
+   - [Tagline intro](#tagline-intro)
+   - [Graphics list](#graphics-list)
+   - [Color and font configuration](#color-and-font-configuration)
+   - [Search](#search)
+   - [Analytics](#analytics)
+   - [Last modified date](#last-modified-date)
+   - [Anchor JS](#anchor-js)
 1. [Assets](#assets)
-    - [Stylesheets](#stylesheets)
-    - [Scripts](#scripts)
-    - [Asset load order](#asset-load-order)
+   - [Stylesheets](#stylesheets)
+   - [Scripts](#scripts)
+   - [Asset load order](#asset-load-order)
 1. [Customization](#customization)
-    - [Customizing with Sass](#customizing-with-sass)
-    - [Customizing with CSS overrides](#customizing-with-css-overrides)
-    - [Overriding includes and layouts](#overriding-includes-and-layouts)
+   - [Customizing with Sass](#customizing-with-sass)
+   - [Customizing with CSS overrides](#customizing-with-css-overrides)
+   - [Overriding includes and layouts](#overriding-includes-and-layouts)
 1. [Components](#components)
-    - [Header](#header)
-    - [Footer](#footer)
+   - [Header](#header)
+   - [Footer](#footer)
 1. [Layouts](#layouts)
-    - [Default](#layout-default)
-    - [Page](#layout-page)
-    - [Home](#layout-home)
-    - [Post](#layout-post)
-    - [Project](#layout-project)
-    - [Team member](#layout-team-member)
-
-
+   - [Default](#layout-default)
+   - [Page](#layout-page)
+   - [Home](#layout-home)
+   - [Post](#layout-post)
+   - [Project](#layout-project)
+   - [Team member](#layout-team-member)
+1. [Migrating from earlier versions](#migrating-from-earlier-versions)
+1. [Development](#development)
 
 ## Installation
 
 1. Install the theme as a Ruby Gem by adding it to your `Gemfile`
    like so:
 
-    ```ruby
-    gem 'uswds-jekyll'
-    ```
+   ```ruby
+   gem 'uswds-jekyll', :git => 'https://github.com/18F/uswds-jekyll.git', :branch => 'update-uswds-2.0'
+   ```
 
 1. Fetch and update your bundled gems by running:
 
-    ```sh
-    bundle
-    ```
+   ```sh
+   bundle
+   ```
 
 1. Set the `theme` in your site's Jekyll configuration,
    `_config.yml`:
 
-    ```yml
-    theme: uswds-jekyll
-    ```
+   ```yml
+   theme: uswds-jekyll
+   ```
 
 You will need to restart your Jekyll server to see the effects.
 
 ### Install as a new Jekyll site
 
 1. Create a new Jekyll site:
-    ```
-    jekyll new
-    ```
+   ```
+   jekyll new
+   ```
 1. Replace the default `gem "minima", "~> 2.0"` gem with the `uswds-jekyll` gem in your `Gemfile`:
 
-    ```ruby
-    gem 'uswds-jekyll', :git => 'https://github.com/18F/uswds-jekyll.git'
-    ```
+   ```ruby
+   gem 'uswds-jekyll', :git => 'https://github.com/18F/uswds-jekyll.git', :branch => 'update-uswds-2.0'
+   ```
 
 1. Set the `theme` in your site's Jekyll configuration,
    `_config.yml`:
 
-    ```yml
-    theme: uswds-jekyll
-    ```
-1. Fetch and update your bundled gems by running:
-
-    ```sh
-    bundle
-    ```
-1. Run Jekyll `jekyll serve` to build your site locally at http://localhost:4000/
+   ```yml
+   theme: uswds-jekyll
+   ```
 
-### Development
+1. Fetch and update your bundled gems by running:
 
-To develop this theme and/or test it locally:
+   ```sh
+   bundle
+   ```
 
-1. Clone this repo
-1. Run Jekyll (`jekyll serve`) in the local clone of this repo;
-   **or**
-1. Create a new Jekyll project, follow the
-   [installation](#installation) instructions, then change your
-   `Gemfile` to point at the local clone of this repo:
-
-    ```ruby
-    gem 'uswds-jekyll', :path => '../path/to/uswds-jekyll'
-    ```
-### Publish to Rubygems
-1. Update `spec.version = "NUMBER HERE"` in the uswds-jekyll.gemspec file to the version you want to publish
-1. Run `bundle install`
-1. Add a PR for the update and get it merged
-1. Run `bundle exec rake release`
-1. Add a GitHub release to the releases page with the same version number
-1. You should see the latest version here https://rubygems.org/gems/uswds-jekyll
+1. Run `bundle exec jekyll serve` to build your site locally at http://localhost:4000/
 
 ### Versioning
 
-To reference a specific version of this plugin:
+To reference a specific version of this theme:
 
 1. Visit the [releases page](https://github.com/18F/uswds-jekyll/releases) and
    decide which version you want to use.
 1. Specify the version in your `Gemfile`.
 
-    ```ruby
-    gem 'uswds-jekyll', '1.4.1'
-    ```
+   ```ruby
+   gem 'uswds-jekyll', '5.0.0'
+   ```
 
 ## Configuration
 
 Configuration of common elements ([header](#header),
-[footer](#footer), [navigation](#navigation), etc.) happens in your
-project's [data files](https://jekyllrb.com/docs/datafiles/). See
-this project's [data directory](_data) for reference configurations
+[footer](#footer), [navigation](#navigation), etc.) happens in your project's [data files](https://jekyllrb.com/docs/datafiles/). See this project's [data directory](_data) for reference configurations
 of each component.
 
-The [default layout](#layout-default) also provides a mechanism for
-automatically including [stylesheets](#stylesheets) and
-[scripts](#scripts) on a site-wide, layout-wide, and per-page
-basis. See [asset load order](#asset-load-order) for more
-information.
-
+The [default layout](#layout-default) also provides a mechanism for automatically including [stylesheets](#stylesheets) and [scripts](#scripts) on a site-wide, layout-wide, and per-page basis. See [asset load order](#asset-load-order) for more information.
 
 ### Site title
 
-You can change your site's title with the `title` field in your
-`_config.yml`.  If you want to provide an alternate title for use
-_only_ in the site header, you can set the `title` field in
-`_data/header.yml`.
+You can change your site's title with the `title` field in `_config.yml`. If you want to provide an alternate title for use _only_ in the site header, you can set the `title` field in `_data/header.yml`.
 
 ### Site description
 
-You can change your site's description with the `description` field in your
-`_config.yml`. If you want to override it for a particular page, you can set the `description` field in that page's frontmatter.
+You can change your site's description with the `description` field in `_config.yml`. If you want to override it for a particular page, you can set the `description` field in that page's frontmatter.
 
 ### Navigation
 
-This theme's navigation system is powerful and flexible. Named
-navigational lists live in your project's `_data/navigation.yml`,
-e.g.
+This theme's navigation system is powerful and flexible. Named navigational lists live in your project's `_data/navigation.yml`.
 
 By default all links are assumed to be internal to the site. You can add `external: true` to links that are external. You can also add `class: class-name` to add a class to a specific link.
 
 ```yml
 # _data/navigation.yml
+
 primary:
   - text: Documentation
     href: /docs/
   - text: Support
     href: /help/
-  - text: External link
+    class: highlight
+  - text: "18F"
     href: https://18f.gsa.gov
     external: true
 
   # link objects with a 'links' field will be presented as
-  # collapsible link lists. The 'links' field can either be a
-  # reference to another link list in this file, or a literal list.
+  # collapsible link lists. The 'links' field can either be
+  # a reference to another link list in this file, or
+  # a literal list.
+
   - text: Section title
     links: <links>
 ```
@@ -186,7 +157,7 @@ more info.
 
 Set each page's title in its frontmatter:
 
-```md
+```
 ---
 title: About us
 ---
@@ -194,8 +165,7 @@ title: About us
 
 ### Page subnavigation
 
-If you're using the [page layout](#layout-page), each page may declare its own
-side navigation and subnavigation in its [front matter]:
+If you're using the [page layout](#layout-page), each page may declare its own side navigation and subnavigation in its front matter:
 
 ```md
 ---
@@ -206,35 +176,26 @@ subnav:
   - text: Section two
     href: '#section-two
 ---
+
 ## Section one
 
 ## Section two
 ```
 
-As with the [header](#header) and [footer](#footer), the `sidenav` field may
-either reference a common [navigation list](#navigation) from
-`_data/navigation.yml` (recommended) or be a literal list of links.
-
-The `subnav` field should be used to link to sections _within_ the current
-page, because links to other pages will cause the linking page's side
-navigation to collapse when visited.
+As with the [header](#header) and [footer](#footer), the `sidenav` field may either reference a common [navigation list](#navigation) from `_data/navigation.yml` (recommended) or be a literal list of links.
 
+The `subnav` field should be used to link to sections _within_ the current page, because links to other pages will cause the linking page's side navigation to collapse when visited.
 
 `sidenav` is a key _into_ `_data/navigation.yml`. See the [navigation](#navigation) docs for more info.
 
-A page's "current" or "active" state in the sidenav is
-determined by whether a link's `href` matches `page.url` or
-`page.permalink` for each page being rendered.
+A page's "current" or "active" state in the sidenav is determined by whether a link's `href` matches `page.url` or `page.permalink` for each page being rendered.
 
 `subnav` is a list of links to display on this page under its own link in the side navigation.
 
 **Note that subnav link hrefs are not prefixed with
-`site.baseurl`** because this breaks hash links prefixed with
-`#`.
+`site.baseurl`** because this breaks hash links prefixed with `#`.
 
-**Pro tip:** Unless your Jekyll configuration specifies otherwise, the default
-Markdown formatter (Kramdown) will automatically generate predictable `id`
-attributes for your page headings and convert markdown like this:
+**Pro tip:** Unless your Jekyll configuration specifies otherwise, the default Markdown formatter (Kramdown) will automatically generate predictable `id` attributes for your page headings and convert markdown like this:
 
 ```md
 ## Section one
@@ -284,6 +245,7 @@ intro: |
 ```
 
 ### Graphics list
+
 ```yml
 # an optional list of graphics to display before or after the content
 graphics:
@@ -298,10 +260,9 @@ graphics:
 graphics_position: (before|after)
 ```
 
-### Color and font configuration
-
-The default colors and fonts can be configured in the `_data/theme.yml` file.
+### Color configuration
 
+The default colors can be configured in the `_data/theme.yml` file. Other settings can be configured using USWDS theme settings. (See the [customization](#customization) section, below.)
 
 ### Search
 
@@ -310,7 +271,7 @@ The default colors and fonts can be configured in the `_data/theme.yml` file.
 Before configuring your search you will need to create a search.gov account and set up your website
 with search.gov.
 
-After setting up your site on search.gov you can then add your `site handle` to the `config.yml`.
+After setting up your site on search.gov you can then add your `search_site_handle` to the `config.yml`.
 
 ### Analytics
 
@@ -334,8 +295,7 @@ You can add DAP to your site by uncommenting the `dap_agency` line and, if need
 
 ### Last modified date
 
-You can show the last date a page was last modified by uncommenting this line from the `footer.yml` data file.
-This will add the date right before the footer component and uses the `last-modified.html` include.
+You can show the last date a page was last modified by uncommenting this line from the `footer.yml` data file. This will add the date right before the footer component and uses the `last-modified.html` include.
 
 ```yml
 # Used to show the "Last updated" date and time;
@@ -344,9 +304,7 @@ This will add the date right before the footer component and uses the `last-modi
 
 ### Anchor JS
 
-You can show an anchor link next to header tags by uncommenting this section from the `_config.yml` data file.
-This will add an anchor link after the header tag on the page and post layouts making ech header linkable.
-See https://github.com/bryanbraun/anchorjs for more information.
+You can show an anchor link next to header tags by uncommenting this section from the `_config.yml` data file. This will add an anchor link after the header tag on the page and post layouts making ech header linkable. See https://github.com/bryanbraun/anchorjs for more information.
 
 ```yml
 # anchor_js_targets: [h1, h2, h3, h4, h5, h6]
@@ -354,10 +312,7 @@ See https://github.com/bryanbraun/anchorjs for more information.
 
 ## Assets
 
-The [stylesheet](_includes/styles.html) and [script](_includes/scripts.html)
-includes each incorporate the USWDS CSS and JS files if the corresponding
-`styles` and `scripts` lists aren't defined in your `_config.yml`. So unless
-you add one or both of those manually, your HTML will include the following:
+The [stylesheet](_includes/styles.html) and [script](_includes/scripts.html) includes each incorporate the USWDS CSS and JS files if the corresponding `styles` and `scripts` lists aren't defined in your `_config.yml`. So unless you add one or both of those manually, your HTML will include the following:
 
 ```html
 <!-- in the <head> -->
@@ -366,16 +321,12 @@ you add one or both of those manually, your HTML will include the following:
 <script src="/assets/uswds/js/uswds.min.js" async>
 ```
 
-Read more about customizing [stylesheets](#stylesheets) and [scripts](#scripts)
-below.
-
+Read more about customizing [stylesheets](#stylesheets) and [scripts](#scripts) below.
 
 ### Stylesheets
 
 As a general rule, all stylesheets are inserted in a layouts'
-`<head>`, which qualifies them as "render-blocking". Site
-stylesheets can be specified in `_config.yml` or a layout or page's
-[front matter] YAML in the following form:
+`<head>`, which qualifies them as "render-blocking". Site stylesheets can be specified in `_config.yml` or a layout or page's [front matter] YAML in the following form:
 
 ```yml
 styles:
@@ -387,7 +338,6 @@ styles:
 Stylesheets specified as objects (in the latter item above) must
 have an `href` property. The `media` defaults to `screen`.
 
-
 ### Scripts
 
 As a general rule, all scripts are inserted before a layouts'
@@ -403,14 +353,7 @@ scripts:
 ```
 
 Scripts specified as objects (in the latter item above) must have a `src`
-property. Scripts with `async: true` will get an `async` attribute, which tells
-the browser _not_ to let this script's loading block the execution of
-subsequent scripts. If the execution order of your scripts is **not**
-important, setting `async: true` may provide performance benefits to your
-users. (Conversely, if you don't know whether your scripts need to execute in a
-particular order, then you should not set `async: true` because it may prevent
-your scripts from running propertly.)
-
+property. Scripts with `async: true` will get an `async` attribute, which tells the browser _not_ to let this script's loading block the execution of subsequent scripts. If the execution order of your scripts is **not** important, setting `async: true` may provide performance benefits to your users. (Conversely, if you don't know whether your scripts need to execute in a particular order, then you should not set `async: true` because it may prevent your scripts from running propertly.)
 
 ### Asset load order
 
@@ -424,70 +367,20 @@ Both [stylesheets](#stylesheets) and [scripts](#scripts) can be configured
 1. Those configured at the page level (in the page's [front matter])
    will be loaded last.
 
-
 ## Customization
 
-You have two options for customizing the CSS: [Sass](#customizing-with-sass) or
-[CSS overrides](#customizing-with-css-overrides). Individual sites can also
-[selectively override](#overriding-includes-and-layouts) individual includes
-and layouts.
-
-
-### Customizing with Sass
-
-1. Create a [Sass][] (or SCSS) entry point that sets variables and then imports
-   the USWDS source files:
-
-    ```scss
-    ---
-    # assets/main.scss
-    ---
-    // set your variables or @import them here.
-
-    // at the very least, you should set the USWDS font and image paths
-    // to the correct paths relative to assets/main.css, like so:
-    $font-path: 'uswds/fonts';
-    $image-path: 'uswds/img';
+Customize the USWDS Jekyll theme with [USWDS theme settings files](https://designsystem.digital.gov/documentation/settings/), [USWDS design tokens](https://designsystem.digital.gov/design-tokens/), and custom Sass or CSS. You'll need to manually add these custom files to your Jekyll project into a couple specific locations.
 
-    @import 'uswds/all';
-    ```
+1. Find the **most current settings files** in the `_sass/settings` [folder of this theme](https://github.com/18F/uswds-jekyll/tree/update-uswds-2.0/_sass/settings). [Download these files with DownGit](https://minhaskamal.github.io/DownGit/#/home?url=https://github.com/18F/uswds-jekyll/tree/update-uswds-2.0/_sass/settings)
 
-1. Change the path to your site's default stylesheet in your `_config.yml`:
+1. Copy these theme settings files to you project's `_sass/settings` directory. If this directory doesn't exist, create it.
 
-    ```yml
-    styles:
-      - /assets/main.css
-    ```
+1. Edit these new settings files to customize your USWDS implementation, following the USWDS's [theme settings guidance](https://designsystem.digital.gov/documentation/settings/).
 
-All of the USWDS [SCSS source files](https://github.com/uswds/uswds/tree/master/src/stylesheets)
-are placed in the [_sass/uswds](_sass/uswds) directory and are available as
-Sass imports via `@import 'uswds/<path>';`. See the [Jekyll docs][Jekyll Sass]
-for more information about its Sass/SCSS support, and configuring its Sass
-renderer in your site's config.
+1. Add any **custom CSS or Sass** to a folder called `_sass/custom/_uswds-theme-custom-styles.scss`. You can also use this file to import any additional Sass or CSS files your project needs. [Download this file from Github](https://raw.githubusercontent.com/18F/uswds-jekyll/update-uswds-2.0/_sass/custom/_uswds-theme-custom-styles.scss)
 
-
-### Customizing with CSS overrides
-
-1. Create a new CSS or Sass file that defines your customizations,
-   e.g.
-
-    ```scss
-    ---
-    # assets/uswds-overrides.scss
-    ---
-    .usa-header {
-      // overrides here
-    }
-    ```
-
-1. Add the new stylesheet's path to your `_config.yml` _after_
-   `uswds.min.css`:
-
-    ```yml
-    styles:
-      - /assets/uswds/css/uswds.min.css
-      - /assets/uswds-overrides.css
-    ```
+You have two options for customizing the CSS: [Sass](#customizing-with-sass) or [CSS overrides (#customizing-with-css-overrides). Individual sites can also
+[selectively override](#overriding-includes-and-layouts) individual includes and layouts.
 
 ### Overriding includes and layouts
 
@@ -530,11 +423,10 @@ header data to come directly from the Jekyll configuration file
 `_includes/header.html` to look like this:
 
 ```html
-{% assign header = site.data.header %}
-{% include components/header--basic.html %}
+{% assign header = site.data.header %} {% include components/header--basic.html
+%}
 ```
 
-
 ### Header
 
 The [header.html include](_includes/header.html) sets the `header`
@@ -545,7 +437,6 @@ render the header's markup.
 
 See this repo's [header.yml](_data/header.yml) for more info.
 
-
 ### Footer
 
 The [footer.html include](_includes/footer.html) sets the `header`
@@ -556,7 +447,6 @@ render the footer's markup.
 
 See this repo's [footer.yml](_data/footer.yml) for more info.
 
-
 ## Layouts
 
 This theme provides the following layouts, which you can use by
@@ -566,7 +456,9 @@ setting the `layout` [front matter] on each page, like so:
 ---
 layout: name
 ---
+
 ```
+
 Supported (optional) front matter for page layouts.
 
 - [page navigation](#page-subnavigation)
@@ -591,7 +483,6 @@ This layout implements the [home page
 template](https://designsystem.digital.gov/page-templates/landing/), which
 accommodates the following [front matter]:
 
-
 Check out the YAML front matter in the [home demo
 page](demo/home.html) for an example of how to structure it.
 
@@ -601,12 +492,12 @@ This layout implements the [document page
 template](https://designsystem.digital.gov/page-templates/docs/).
 
 See the [page demo page](demo/page.md) for an example of how this
-works, and see [_data/navigation.yml](_data/navigation.yml) for how
+works, and see [\_data/navigation.yml](_data/navigation.yml) for how
 to structure named navigation data for your site.
 
 ### `layout: post`
 
-This layout is identical to the layout `page` and is included to allow for easier site creation using  `Jekyll new`.
+This layout is identical to the layout `page` and is included to allow for easier site creation using `Jekyll new`.
 
 ### `layout: project`
 
@@ -640,6 +531,137 @@ email: email@address.gov
 
 To show a listing of team members on a page add `{% include team-list.html %} to the page`
 
-[Sass]: http://sass-lang.com/guide
-[Jekyll Sass]: https://jekyllrb.com/docs/assets/#sassscss
+[sass]: http://sass-lang.com/guide
+[jekyll sass]: https://jekyllrb.com/docs/assets/#sassscss
 [front matter]: https://jekyllrb.com/docs/frontmatter/
+
+## Migrating from earlier versions
+
+**Note:** `uswds-jekyll 5.0.0` is only compatible with Jekyll 4.0 and higher.
+
+1. Update your `uswds-jekyll` gem in your project's Gemfile. Replace the current `gem 'uswds-jekyll'` line with:
+
+   ```ruby
+   gem 'uswds-jekyll', '5.0.0'
+   ```
+
+   Then, in the terminal, run
+
+   ```
+   bundle update uswds-jekyll
+   ```
+
+1. Add any custom styles to `/_sass/custom/`
+1. `_sass` folder needs to be at the root level, not in assets.
+1. Convert manual values to tokenzied values using the guidance on the [USWDS migration page](https://designsystem.digital.gov/documentation/migration/#spacing-units).
+1. Don't duplicate the `h1` in the body content of `page` template pages. (This is automatically inserted at the top with the content of `page.title`.)
+1. Check that certain data keys exist
+
+   ```
+   --> config.yml
+   styles:
+     [nothing unless adding additional stylesheets]
+
+   --> header.yml
+   type: [basic | basic-mega | extended | extended-mega]
+
+   --> footer.yml
+   type: [slim | default | big]
+
+   --> navigation.yml
+   sidenav-breakpoint: {{ breakpoint_token }}
+
+   --> theme.yml (examples)
+   colors:
+     usa-banner:
+       usa-banner-bg: 'base-lightest'
+       usa-banner-text: 'ink'
+       usa-banner-link: 'primary-dark'
+       usa-banner-link-hover: 'primary-darker'
+     header:
+       header-bg: 'white'
+       header-title: 'ink'
+       header-link: 'base'
+       header-link-hover: 'primary-dark'
+     alt-section:
+       bg-color: 'primary-darker'
+       header-color: 'accent-cool'
+       text-color: 'white'
+       link-color: 'base-lightest'
+       link-hover-color: 'white'
+     hero:
+       hero-bg: 'primary-darker'
+       hero-header: 'accent-cool'
+       hero-header-alt: 'white'
+       hero-text: 'white'
+       hero-link: 'accent-cool'
+       hero-button-bg: 'primary'
+       hero-button-text: 'white'
+     top-navigation:
+       top-nav-bg: 'white'
+       top-nav-link: 'base-dark'
+       top-nav-link-hover: 'primary'
+       top-nav-link-hover-bg: 'white'
+       top-nav-link-current: 'base-dark'
+       top-nav-dropdown-bg: 'primary-dark'
+       top-nav-dropdown-link: 'white'
+       top-nav-dropdown-link-hover-bg: 'transparent'
+     side-navigation:
+       side-nav-bg: 'transparent'
+       side-nav-link: 'ink'
+       side-nav-link-hover: 'primary-dark'
+       side-nav-link-hover-bg: 'base-lightest'
+       side-nav-link-current: 'primary-dark'
+     footer:
+       primary-footer-bg: 'base-lightest'
+       primary-footer-link: 'ink'
+       footer-bg: 'base-lighter'
+       footer-text: 'ink'
+       footer-link: 'ink'
+       footer-social-link: 'black-transparent-10'
+
+   ```
+
+1. Check that css is referencing `uswds-theme.css`
+
+## Development
+
+To develop this theme and/or test it locally:
+
+1. Clone this repo
+
+1. Check the version of USWDS in `package.json` — update to the newest version if necessary, and sync its new files to the theme.
+
+   > `rake update`
+
+1. Start Jekyll to preview the effects of your changes. This will build the Jekyll site, watch the Sass files, and recompile the Sass when there are changes.
+
+   > `npm start`
+
+   **or**
+
+   Create a new Jekyll project, follow the
+   [installation](#installation) instructions, then change your
+   `Gemfile` to point at the local clone of this repo:
+
+   ```ruby
+   gem 'uswds-jekyll', :path => '../path/to/uswds-jekyll'
+   ```
+
+### Publish to Rubygems
+
+1. Update `spec.version = "NUMBER HERE"` in the uswds-jekyll.gemspec file to the version you want to publish
+1. Run `bundle install`
+1. Add a PR for the update and get it merged
+1. Run `bundle exec rake release`
+1. Add a GitHub release to the releases page with the same version number
+1. You should see the latest version here https://rubygems.org/gems/uswds-jekyll
+
+#### Scripts
+
+- `start`: Starts the jekyll site
+- `setup-uswds`: Copies assets from the USWDS package to their theme locations, but running the following scipts, which can also be run separately:
+  - `sync-assets`: Copies assets to `assets/uswds`
+  - `sync-sass`: Copies Sass cource files to `_sass/uswds/src/`
+  - `sync-default-settings`: Copies default settings files to `_sass/uswds/settings`
+  - `sync-theme-settings`: Copies only theme settings files to `_sass/settings`