uswds-jekyll 5.0.1 → 5.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 552f833b8c33993f2f5b0c670b2e29e375b3ab4f9484154ca4487bfb3c907160
-  data.tar.gz: 357f8e3b7448a757997279b3bae773b372d2413977f0f4cfbd4e19f27bd7d9c0
+  metadata.gz: 84151ee36e5dee15c291972675e4d0729dbcf813886683f27efa8548b2cb550d
+  data.tar.gz: 68991524fdfd3a08ca5642dd9d41bf1c7308eade2477802f0d8dceb7a83d8eeb
 SHA512:
-  metadata.gz: a88852b3c1997c9660e55dc3dfb1b436facc3526ea4adca8a58fc06d20bd6b11a36847d3c39a798cc625286a8ec7a3a784f4021f68e02e2053a60a3e29a2e7bd
-  data.tar.gz: e4d77d84905057cd33a187f8f5a05eee25c1f1112ee3cc4941b8aff33b01980a600a83e9a6e9ae7b69045ccc0ebe51acbf154380c7db77f0b05d5939252f0be1
+  metadata.gz: 8eccde348a2be434e4f280293b1e181069f1487766317cce3dbd4a5fe5caaed4d0424f13225659b32f6c2535aae2150afe9a5860179d57b6529aa68457880084
+  data.tar.gz: 9c451c5628afca130330ea6336c945c780959bcab350fd8c5cf133ab27eaf142098691fa6dc6bb3578059c39f1511036b541f371898c4c42336737ac3a01b5f4

data/README.md

@@ -25,8 +25,6 @@ This is a [Jekyll theme](https://jekyllrb.com/docs/themes/) for the
    - [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)
 1. [Components](#components)
    - [Header](#header)
@@ -77,8 +75,7 @@ You will need to restart your Jekyll server to see the effects.
    gem 'uswds-jekyll'
    ```
 
-1. Set the `theme` in your site's Jekyll configuration,
-   `_config.yml`:
+1. Set the `theme` in your site's Jekyll configuration, `_config.yml`:
 
    ```yml
    theme: uswds-jekyll
@@ -96,8 +93,7 @@ You will need to restart your Jekyll server to see the effects.
 
 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. 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
@@ -106,9 +102,7 @@ To reference a specific version of this theme:
 
 ## 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
-of each component.
+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 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.
 
@@ -148,10 +142,7 @@ primary:
     links: <links>
 ```
 
-This scheme allows you to define navigational elements that can be
-shared by different components, such as the [header](#header) and
-[footer](#footer). See the documentation for those components for
-more info.
+This scheme allows you to define navigational elements that can be shared by different components, such as the [header](#header) and [footer](#footer). See the documentation for those components for more info.
 
 ### Page title
 
@@ -192,8 +183,7 @@ A page's "current" or "active" state in the sidenav is determined by whether a l
 
 `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 `#`.
+**Note that subnav link hrefs are not 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:
 
@@ -207,8 +197,7 @@ into:
 <h2 id="section-one">Section one</h2>
 ```
 
-If you're using Redcarpet, you will need to configure it to enable
-the `with_toc_data` extension in your `_config.yml`, like so:
+If you're using Redcarpet, you will need to configure it to enable the `with_toc_data` extension in your `_config.yml`, like so:
 
 ```yml
 markdown: redcarpet
@@ -286,9 +275,7 @@ You can add Google Analytics to your site by uncommenting the `google_analytics_
 
 #### Digital Analytics Program (DAP)
 
-You can add DAP to your site by uncommenting the `dap_agency` line and, if need be, replacing `GSA` with the appropriate agency key.
-And optionally, `dap_subagency` may also be specified.
-For more information visit <https://www.digitalgov.gov/services/dap/>
+You can add DAP to your site by uncommenting the `dap_agency` line and, if need be, replacing `GSA` with the appropriate agency key. And optionally, `dap_subagency` may also be specified. For more information visit <https://www.digitalgov.gov/services/dap/>
 
 ```
 # Configuration for DAP, add your agency ID here:
@@ -298,12 +285,23 @@ For more information visit <https://www.digitalgov.gov/services/dap/>
 
 ### 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.
+To show the last date a page was last modified by:
 
-```yml
-# Used to show the "Last updated" date and time;
-# last_updated: true
-```
+1. Add this line to the `footer.yml` data file:
+
+    ```yml
+    last_updated: true
+    ```
+
+1. Add the following to your `Gemfile`:
+
+    ```ruby
+    group :jekyll_plugins do
+      gem "jekyll-last-modified-at"
+    end
+    ```
+
+This will add the date right before the footer component.
 
 ### Anchor JS
 
@@ -328,8 +326,7 @@ Read more about customizing [stylesheets](#stylesheets) and [scripts](#scripts)
 
 ### 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:
+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:
 
 ```yml
 styles:
@@ -338,15 +335,11 @@ styles:
     media: (screen|print|all) # optional
 ```
 
-Stylesheets specified as objects (in the latter item above) must
-have an `href` property. The `media` defaults to `screen`.
+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'
-`</body>`, which prevents them from blocking the rendering of your
-page's content. Scripts can be specified in `_config.yml` or a
-layout or page's [front matter] YAML in the following form:
+As a general rule, all scripts are inserted before a layouts' `</body>`, which prevents them from blocking the rendering of your page's content. Scripts can be specified in `_config.yml` or a layout or page's [front matter] YAML in the following form:
 
 ```yml
 scripts:
@@ -355,8 +348,7 @@ scripts:
     async: true # optional
 ```
 
-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.)
+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.)
 
 ### Asset load order
 
@@ -372,18 +364,17 @@ Both [stylesheets](#stylesheets) and [scripts](#scripts) can be configured
 
 ## Customization
 
-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.
+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 place USWDS settings and custom Sass into a couple specific locations for the theme to find them.
 
-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. **Settings:** Add custom USWDS settings to `_sass/_uswds-theme-settings.scss`. Settings control the USWDS output. See all available settings in the [USWDS settings documentation](https://designsystem.digital.gov/documentation/settings/). We recommend adding only your modified settings to the `_uswds-theme-settings.scss` file.
 
-1. Copy these theme settings files to you project's `_sass/settings` directory. If this directory doesn't exist, create it.
+    To see an example of all the settings available to USWDS, see the files [in the USWDS GitHub repo](https://github.com/uswds/uswds/tree/develop/src/stylesheets/theme). The repo splits settings into multiple files. If you want to copy and mimic that structure, download the repo files using a tool like [DownGit](https://minhaskamal.github.io/DownGit/#/home?url=https://github.com/uswds/uswds/tree/develop/src/stylesheets/theme). Then add them to the `_sass/` directory and `@import` them from `_uswds-theme-settings.scss`.
 
-1. Edit these new settings files to customize your USWDS implementation, following the USWDS's [theme settings guidance](https://designsystem.digital.gov/documentation/settings/).
+    Whether you add only individual settings variables or import from multiple files, `_uswds-theme-settings.scss` needs to be the entry point.
 
-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)
+1. **Custom Sass and variables:** Add any custom CSS or Sass to `_sass/_uswds-theme-custom-styles.scss`. You can use this custom styles file to `@import` any _additional_ Sass or CSS files your project needs, as long as any additional files exist in the `/_sass` directory.
 
-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.
+    Custom Sass loads after the USWDS and default Sass, so you can use it to override the defaults. Individual sites can also [selectively override](#overriding-includes-and-layouts) individual includes and layouts.
 
 ### Overriding includes and layouts
 
@@ -391,11 +382,6 @@ Any [include](_includes) or [layout](_layouts) can be overridden by
 your site by placing a file with the same name into your site's
 `_includes` or `_layouts` directory. For instance:
 
-- To change how [stylesheets](#stylesheets) are loaded or
-  referenced, you can create your own `_includes/styles.html`,
-  which will subsequently change how stylesheets are loaded in all
-  layouts that inherit from the USWDS [default layout](#layout-default).
-
 - You can change how the side navigation is rendered (but not which
   data it receives) in the [page layout](#layout-page) by creating
   your own `_includes/sidenav.html`.
@@ -406,24 +392,13 @@ your site by placing a file with the same name into your site's
 
 ## Components
 
-For some [USWDS components](https://designsystem.digital.gov/components/),
-there are two different files that control how data is passed to
+For some [USWDS components](https://designsystem.digital.gov/components/), there are two different files that control how data is passed to
 the template:
 
-1. `components/{component}.html` is the low-level template that
-   assumes a similarly named global template variable. For
-   instance, the header component operates on the `header` template
-   variable.
-1. `{component}.html` is the "concrete" implementation of the
-   component that sets the appropriate global variable then
-   includes the low-level template.
-
-This separation allows you to override either of the component
-includes in your own Jekyll site without having to re-implement
-either the high- or low-level logic. For instance, if you want your
-header data to come directly from the Jekyll configuration file
-(`_config.yml`) rather than `_data/header.yml`, you can override
-`_includes/header.html` to look like this:
+1. `components/{component}.html` is the low-level template that assumes a similarly named global template variable. For instance, the header component operates on the `header` template variable.
+1. `{component}.html` is the "concrete" implementation of the component that sets the appropriate global variable then includes the low-level template.
+
+This separation allows you to override either of the component includes in your own Jekyll site without having to re-implement either the high- or low-level logic. For instance, if you want your header data to come directly from the Jekyll configuration file (`_config.yml`) rather than `_data/header.yml`, you can override `_includes/header.html` to look like this:
 
 ```html
 {% assign header = site.data.header %} {% include components/header--basic.html
@@ -432,28 +407,20 @@ header data to come directly from the Jekyll configuration file
 
 ### Header
 
-The [header.html include](_includes/header.html) sets the `header`
-template variable to `site.data.header`, the value of which is set
-in your Jekyll project's `_data/header.yml` file. Then it includes
-[components/header.html](_includes/components/header.html) to
-render the header's markup.
+The [header.html include](_includes/header.html) sets the `header` template variable to `site.data.header`, the value of which is set in your Jekyll project's `_data/header.yml` file. Then it includes [components/header.html](_includes/components/header.html) to 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`
-template variable to `site.data.footer`, the value of which is set
-in your Jekyll project's `_data/footer.yml` file. Then it includes
-[components/footer.html](_includes/components/footer.html) to
+The [footer.html include](_includes/footer.html) sets the `footer` template variable to `site.data.footer`, the value of which is set in your Jekyll project's `_data/footer.yml` file. Then it includes [components/footer.html](_includes/components/footer.html) to
 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
-setting the `layout` [front matter] on each page, like so:
+This theme provides the following layouts, which you can use by setting the `layout` [front matter] on each page, like so:
 
 ```yml
 ---
@@ -471,32 +438,22 @@ Supported (optional) front matter for page layouts.
 
 ### `layout: default`
 
-This is the bare-bones USWDS layout, which does all of the
-basic page scaffolding then drops the page content into the
-`<main>` element. All of the other layouts "inherit" this one and
-provide other features in the content block.
+This is the bare-bones USWDS layout, which does all of the basic page scaffolding then drops the page content into the `<main>` element. All of the other layouts "inherit" this one and provide other features in the content block.
 
-The default layout provides a layout [front matter] hook to add
-attributes to the `<main>` element. You can see how this works in
-the [page layout](_layouts/page.html#L3-L4).
+The default layout provides a layout [front matter] hook to add attributes to the `<main>` element. You can see how this works in the [page layout](_layouts/page.html#L3-L4).
 
 ### `layout: home`
 
 This layout implements the [home page
-template](https://designsystem.digital.gov/page-templates/landing/), which
-accommodates the following [front matter]:
+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.
+Check out the YAML front matter in the [home demo page](demo/home.html) for an example of how to structure it.
 
 ### `layout: page`
 
-This layout implements the [document page
-template](https://designsystem.digital.gov/page-templates/docs/).
+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
-to structure named navigation data for your site.
+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 to structure named navigation data for your site.
 
 ### `layout: post`
 
@@ -544,7 +501,7 @@ To show a listing of team members on a page add `{% include team-list.html %} to
 
 See [this example pull request](https://github.com/18F/before-you-ship/pull/458).
 
-### From from earlier versions
+### From earlier versions
 
 **Note:** `uswds-jekyll` 5.x is only compatible with Jekyll 4.0 and higher.
 
@@ -560,8 +517,10 @@ See [this example pull request](https://github.com/18F/before-you-ship/pull/458)
    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. If you have an existing `_sass` folder, it needs to move to the root level, and out of any directory like `/assets`.
+1. Add or move any custom styles or variables to `/_sass/_uswds-theme-custom-styles.scss`.
+
+    If you have multiple custom styles files, add them to the `/_sass` directory and `@import` them from `_uswds-theme-custom-styles.scss`.
 1. Convert manual values to tokenized 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

data/_includes/components/banner.html

@@ -18,26 +18,28 @@
     <div class="usa-banner__content usa-accordion__content" id="gov-banner">
       <div class="grid-row grid-gap-lg">
         <div class="usa-banner__guidance tablet:grid-col-6">
-          <img class="usa-banner__icon usa-media-block__img" src="{{ site.baseurl }}/assets/uswds/img/icon-dot-gov.svg" alt="Dot gov">
+          <img class="usa-banner__icon usa-media-block__img" src="{{ site.baseurl }}/assets/uswds/img/icon-dot-gov.svg" role="img" alt="Dot gov">
           <div class="usa-media-block__body">
             <p>
-              <strong>The .gov means it’s official.</strong>
-              <br>
-              Federal government websites often end in .gov or .mil. Before sharing sensitive information, make sure you’re on a federal government site.
+              <strong>Official websites use .gov</strong>
+              <br/>
+              A <strong>.gov</strong> website belongs to an official government organization in the United States.
             </p>
           </div>
         </div>
         <div class="usa-banner__guidance tablet:grid-col-6">
-          <img class="usa-banner__icon usa-media-block__img" src="{{ site.baseurl }}/assets/uswds/img/icon-https.svg" alt="Https">
+          <img class="usa-banner__icon usa-media-block__img" src="{{ site.baseurl }}/assets/uswds/img/icon-https.svg" role="img" alt="Https">
           <div class="usa-media-block__body">
             <p>
-              <strong>The site is secure.</strong>
-              <br>
-              The <strong>https://</strong> ensures that you are connecting to the official website and that any information you provide is encrypted and transmitted securely.
+              <strong>Secure .gov websites use HTTPS</strong>
+              <br/>
+              A <strong>lock</strong> (
+<span class="icon-lock"><svg xmlns="http://www.w3.org/2000/svg" width="52" height="64" viewBox="0 0 52 64" class="usa-banner__lock-image" role="img" aria-labelledby="banner-lock-title banner-lock-description"><title id="banner-lock-title">Lock</title><desc id="banner-lock-description">A locked padlock</desc><path fill="#000000" fill-rule="evenodd" d="M26 0c10.493 0 19 8.507 19 19v9h3a4 4 0 0 1 4 4v28a4 4 0 0 1-4 4H4a4 4 0 0 1-4-4V32a4 4 0 0 1 4-4h3v-9C7 8.507 15.507 0 26 0zm0 8c-5.979 0-10.843 4.77-10.996 10.712L15 19v9h22v-9c0-6.075-4.925-11-11-11z"/></svg></span>
+) or <strong>https://</strong> means you’ve safely connected to the .gov website. Share sensitive information only on official, secure websites.
             </p>
           </div>
         </div>
       </div>
     </div>
   </div>
-</section>
+</section>

data/_sass/uswds/components/_header.scss

@@ -17,7 +17,7 @@
       height: units(2);
       margin-right: units(1);
 
-      @media($theme-header-min-width) {
+      @include at-media($theme-header-min-width) {
         margin-top: 0;
         height: units(3);
       }

data/_sass/uswds/components/_nav-buttons.scss

@@ -1,17 +1,17 @@
 .usa-header,
 .usa-sidenav-list {
-  @media($theme-header-min-width) {
+  @include at-media($theme-header-min-width) {
     .usa-button {
       margin: 0;
       width: auto;
     }
   }
   .usa-button {
-    color: $color-white;
+    color: color("white");
     padding: units(1.5);
     &:hover {
-      background-color: color('primary-dark');
-      color: $color-white;
+      background-color: color("primary-dark");
+      color: color("white");
       text-decoration: none;
     }
   }

data/_sass/uswds/src/components/_alerts.scss

@@ -8,14 +8,14 @@ $usa-alerts: (
   success: "success-lighter",
   warning: "warning-lighter",
   error: "error-lighter",
-  info: "info-lighter"
+  info: "info-lighter",
 );
 
 $usa-alerts-bar: (
   success: "success",
   warning: "warning",
   error: "error",
-  info: "info"
+  info: "info",
 );
 
 $alerts: map-merge($usa-alerts, $usa-custom-alerts);
@@ -51,14 +51,13 @@ $alert-padding-left: units($theme-alert-padding-x) +
     width: units($theme-alert-bar-width);
   }
 
-  ul {
-    margin-bottom: 0;
-    margin-top: units(1);
-    padding-left: units(1);
-  }
-
-  .usa-checklist {
+  > .usa-list,
+  .usa-alert__body > .usa-list {
     padding-left: 0;
+
+    &:last-child {
+      margin-bottom: 0;
+    }
   }
 }
 

data/_sass/uswds/src/components/_banner.scss

@@ -1,7 +1,40 @@
+$banner-guidance-measure: 3;
+$banner-icon-colors: get-link-tokens-from-bg(
+  $theme-banner-background-color,
+  $theme-banner-link-color
+);
+$banner-icon-color: nth($banner-icon-colors, 1);
+$banner-icon-hover: nth($banner-icon-colors, 2);
+$banner-icon-chevron: (
+  "name": "chevron",
+  "svg-height": 39,
+  "svg-width": 64,
+  "height": 0.8ex,
+  "color": $banner-icon-color,
+  "color-variant": "white",
+  "color-hover": $banner-icon-hover,
+);
+$banner-icon-chevron-up: map-merge(
+  $banner-icon-chevron,
+  (
+    "rotate": 180deg,
+  )
+);
+$banner-icon-close: (
+  "name": "close-alt",
+  "svg-height": 40,
+  "svg-width": 40,
+  "height": $theme-icon-image-size,
+  "color": "blue-60v",
+  "color-variant": "white",
+  "container-height": $size-touch-target,
+  "container-width": $size-touch-target,
+);
+
 .usa-banner {
   @include typeset($theme-banner-font-family);
   @include border-box-sizing;
-  background-color: color("base-lightest");
+  background-color: color($theme-banner-background-color);
 
   @include at-media("tablet") {
     font-size: font-size($theme-banner-font-family, "3xs");
@@ -13,6 +46,11 @@
   }
 }
 
+.usa-banner__header,
+.usa-banner__content {
+  @include set-text-from-bg($theme-banner-background-color);
+}
+
 .usa-banner__content {
   @include grid-container($theme-banner-max-width);
   @include add-responsive-site-margins;
@@ -36,6 +74,9 @@
 }
 
 .usa-banner__guidance {
+  @include u-display("flex");
+  @include u-flex("align-start");
+  @include u-measure($banner-guidance-measure);
   padding-top: units(2);
 
   @include at-media("tablet") {
@@ -43,6 +84,19 @@
   }
 }
 
+.usa-banner__lock-image {
+  $lock-h: 64; // unitless height of svg
+  $lock-w: 52; // unitless width of svg
+  $lock-aspect: $lock-w / $lock-h;
+  $icon-height: 1.5ex; // height of the lock icon; use ex for resilience
+
+  height: $icon-height;
+  width: $icon-height * $lock-aspect;
+  path {
+    fill: currentColor;
+  }
+}
+
 .usa-banner__inner {
   @include add-responsive-site-margins;
   @include grid-container($theme-banner-max-width);
@@ -68,23 +122,6 @@
   }
 }
 
-.usa-banner__header-close-text {
-  @include u-margin-y(0);
-  color: color("base-dark");
-  display: none;
-  font-size: font-size($theme-banner-font-family, 1);
-  line-height: line-height($theme-banner-font-family, 2);
-  padding-top: units(0.5);
-
-  .usa-banner__header--expanded & {
-    display: block;
-
-    @include at-media("tablet") {
-      display: none;
-    }
-  }
-}
-
 .usa-banner__header-text {
   @include u-margin-y(0);
   font-size: font-size($theme-banner-font-family, 1);
@@ -92,8 +129,18 @@
 }
 
 .usa-banner__header-action {
-  @include add-icon("angle-arrow-down-primary", "after", 1, 1, 0.5, "hover");
-  color: color("primary");
+  @include place-icon(
+    $banner-icon-chevron,
+    "after",
+    2px,
+    middle,
+    $theme-banner-background-color
+  );
+  @include set-link-from-bg(
+    $theme-banner-background-color,
+    $theme-banner-link-color
+  );
+
   line-height: line-height($theme-banner-font-family, 2);
   margin-bottom: units(0);
   margin-top: units(2px);
@@ -124,7 +171,6 @@
 
   @include at-media("tablet") {
     background-color: transparent;
-    color: color("ink");
     display: block;
     font-size: font-size($theme-banner-font-family, 1);
     font-weight: font-weight("normal");
@@ -150,6 +196,10 @@
   @include u-pin("left");
   @include u-pin("y");
   @include u-text("primary", underline, baseline);
+  @include set-link-from-bg(
+    $theme-banner-background-color,
+    $theme-banner-link-color
+  );
   display: block;
   font-size: font-size($theme-banner-font-family, 1);
   height: auto;
@@ -164,14 +214,23 @@
   }
 
   @include at-media("tablet") {
-    @include add-icon("angle-arrow-down-primary", "after", 1, 1, 2px, "hover");
+    @include place-icon(
+      $banner-icon-chevron,
+      "after",
+      2px,
+      middle,
+      $theme-banner-background-color
+    );
+    @include set-link-from-bg(
+      $theme-banner-background-color,
+      $theme-banner-link-color
+    );
     @include u-pin("none");
     display: inline;
     margin-left: units(1);
     position: relative;
 
     &:hover {
-      @include u-text("primary-darker");
       // Underline added to inner text instead.
       text-decoration: none;
     }
@@ -185,25 +244,37 @@
     background-image: none;
 
     @include at-media-max("tablet") {
-      @include add-icon(
-        "close-blue-60v-alt",
+      @include place-icon(
+        $banner-icon-close,
         "after",
-        $theme-icon-image-size,
-        $size-touch-target,
         0,
-        "no-hover"
+        middle,
+        "base-lighter"
       );
 
-      &::after {
+      &::before {
         @include u-pin("y");
         @include u-pin("right");
         background-color: color("base-lighter");
-        height: auto;
+        content: "";
+        display: block;
+        height: units($size-touch-target);
+        width: units($size-touch-target);
+      }
+      &::after {
+        @include u-pin("y");
+        @include u-pin("right");
       }
     }
 
     @include at-media("tablet") {
-      @include add-icon("angle-arrow-up-primary", "after", 1, 1, 2px, "hover");
+      @include place-icon(
+        $banner-icon-chevron-up,
+        "after",
+        2px,
+        middle,
+        $theme-banner-background-color
+      );
       height: auto;
       padding: units(0);
       position: relative;