Merge pull request #4236 from uswds/release-2.12.0

Release 2.12.0

.prettierignore

@@ -1,4 +1,3 @@
-*.html
 *.njk
 *.woff*
 *.svg

LICENSE.md

@@ -1,5 +1,17 @@
 ## A few parts of this project are not in the public domain
 
+### Copyright ownership of Works created by U.S. federal employees
+
+This repository contains both the original design for Google Material Icons (the “Work”, as defined in Section 1 of the Apache 2.0 License) and modifications made by the General Services Administration (GSA). This repository combines the Work and these GSA modifications, which is a “Modified Version” of Material Icons.
+
+This repository also contains both original designs for Source Sans Pro, Merriweather, and Font Awesome (the “Font Software”, as defined in Section 1 of the SIL Open Font License, version 1.1) and modifications made by the General Services Administration (GSA). This repository combines the Work and these GSA modifications, which is a “Modified Version” of Source Sans Pro, Merriweather, Public Sans, and Font Awesome respectively.
+
+As a work of the United States Government, the software modifications made by GSA are not subject to copyright within the United States. Additionally, GSA waives copyright and related rights in its software modifications worldwide through the CC0 1.0 Universal Public Domain Dedication (https://creativecommons.org/publicdomain/zero/1.0/).
+
+The Work (as defined in the Apache 2.0 License) and Font Software (as defined in the SIL Open Font License, Version 1.1) remains subject to copyright under the respective open source license. The section below lists which works are subject to particular open source licenses.
+
+This Modified Version packaged as `dist/img/sprite.svg` contains both design elements under the Apache 2.0 License and design modifications by GSA released as CC0. It is a “joint work” made of the icon set and modifications combined into a single work.
+
 ### Files licensed under the SIL Open Font License, Version 1.1
 
 The Source Sans Pro font files in `src/fonts/source-sans-pro` are a [customized subset](https://github.com/miguelsousa/source-sans-pro-subset) of [Source Sans Pro](https://github.com/adobe-fonts/source-sans-pro) owned by Adobe Systems Incorporated, licensed under the [SIL Open Font License, Version 1.1](https://scripts.sil.org/cms/scripts/page.php?site_id=nrsi&id=OFL_web), and copyright 2010, 2012, 2014 [Adobe Systems Incorporated], with Reserved Font Name 'Source'. All Rights Reserved. Source is a trademark of Adobe Systems Incorporated in the United States or other countries.
@@ -8,19 +20,17 @@ The Merriweather font files in `src/fonts/merriweather` are the version 2.001 fi
 
 The Public Sans font files in `src/fonts/public-sans` are licensed under the [SIL Open Font License, Version 1.1](https://scripts.sil.org/cms/scripts/page.php?site_id=nrsi&id=OFL_web). Public Sans is a modification of Libre Franklin, copyright [Impallari Type](www.impallari.com).
 
-The files in `src/img` are from [Font Awesome](http://fontawesome.io/) by Dave Gandy under the [SIL Open Font License, Version 1.1](https://scripts.sil.org/cms/scripts/page.php?site_id=nrsi&id=OFL_web).
+Icon files in `src/img` and `src/img/social-icons` are from [Font Awesome](http://fontawesome.io/) by Dave Gandy under the [SIL Open Font License, Version 1.1](https://scripts.sil.org/cms/scripts/page.php?site_id=nrsi&id=OFL_web).
 
 ### Files licensed under the Apache 2.0 License
 
 The Roboto Mono font files in `src/fonts/roboto-mono` are licensed under the [Apache License Version 2.0](https://www.apache.org/licenses/LICENSE-2.0.txt).
 
-The Google Material icons in `src/img/usa-icons` and `src/img/usa-icons-unused` are licensed under the [Apache License Version 2.0](https://www.apache.org/licenses/LICENSE-2.0.txt).
+The Google Material Icons in `src/img/usa-icons` and `src/img/material-icons` are licensed under the [Apache License Version 2.0](https://www.apache.org/licenses/LICENSE-2.0.txt).
 
 ### Files licensed under the MIT license
 
-The files in `src/stylesheets/lib` are from:
-
-- [Normalize.css](https://github.com/necolas/normalize.css), copyright Nicolas Gallagher and Jonathan Neal, under the [MIT license](https://github.com/necolas/normalize.css/blob/master/LICENSE.md).
+The files in `src/stylesheets/lib` are from [Normalize.css](https://github.com/necolas/normalize.css), copyright Nicolas Gallagher and Jonathan Neal, under the [MIT license](https://github.com/necolas/normalize.css/blob/master/LICENSE.md).
 
 #### Full license text for the MIT licensed files:
 
@@ -44,13 +54,13 @@ Additionally, we waive copyright and related rights in the work worldwide throug
 
 This is a human-readable summary of the [Legal Code (read the full text)](https://creativecommons.org/publicdomain/zero/1.0/legalcode).
 
-#### No Copyright
+#### No copyright
 
 The person who associated a work with this deed has dedicated the work to the public domain by waiving all of his or her rights to the work worldwide under copyright law, including all related and neighboring rights, to the extent allowed by law.
 
 You can copy, modify, distribute and perform the work, even for commercial purposes, all without asking permission.
 
-#### Other Information
+#### Other information
 
 In no way are the patent or trademark rights of any person affected by CC0, nor are the rights that other persons may have in the work or in how the work is used, such as publicity or privacy rights.
 
@@ -59,3 +69,7 @@ Unless expressly stated otherwise, the person who associated a work with this de
 ### Contributions to this project
 
 As stated in [CONTRIBUTING](CONTRIBUTING.md), all contributions to this project will be released under the CC0 dedication. By submitting a pull request, you are agreeing to comply with this waiver of copyright interest.
+
+### Trademark
+
+GSA owns, reserves, and retains all rights, title, and interest in all trademarks owned by GSA. The User does not acquire any right or interest of any kind in any GSA trademark because of their use of the Modified Version or any of the modifications made to the Work by GSA.

README.md

@@ -8,32 +8,35 @@ This repository is for the design system code itself. We maintain [another repos
 
 ## Contents
 
-- [Background](#background)
-- [Recent updates](#recent-updates)
-- [Getting started](#getting-started)
-- [Using the design system](#using-the-design-system)
-  - [Download and install](#download-and-install)
-  - [Install using `npm`](#install-using-npm)
-    - [Using the USWDS package](#using-the-uswds-package)
-    - [Sass and theme settings](#sass-and-theme-settings)
-    - [Sass compilation requirements](#sass-compilation-requirements)
-    - [JavaScript](#javascript)
-  - [Use another framework or package manager](#use-another-framework-or-package-manager)
-- [CSS architecture](#css-architecture)
-- [JS customization](#js-customization)
-- [Customization, theming, and tokens](#customization-theming-and-tokens)
-  - [Using tokens in theme settings](#using-tokens-in-theme-settings)
-  - [Set the base asset paths (fonts and images)](#set-the-base-asset-paths-fonts-and-images)
-  - [Main variables that can be customized](#main-variables-that-can-be-customized)
-- [Where things live](#where-things-live)
-- [Browser support](#browser-support)
-- [Accessibility](#accessibility)
-- [Fractal](#fractal)
-  - [Template compatibility](#template-compatibility)
-- [Need installation help?](#need-installation-help)
-- [Contributing to the code base](#contributing-to-the-code-base)
-- [Reuse of open-source style guides](#reuse-of-open-source-style-guides)
-- [Licenses and attribution](#licenses-and-attribution)
+- [United States Web Design System](#united-states-web-design-system)
+  - [Contents](#contents)
+  - [Background](#background)
+  - [Recent updates](#recent-updates)
+  - [Getting started](#getting-started)
+  - [Using the design system](#using-the-design-system)
+    - [Download and install](#download-and-install)
+    - [Install using npm](#install-using-npm)
+      - [Using the USWDS package](#using-the-uswds-package)
+      - [Sass and theme settings](#sass-and-theme-settings)
+      - [Sass compilation requirements](#sass-compilation-requirements)
+      - [JavaScript](#javascript)
+    - [Use another framework or package manager](#use-another-framework-or-package-manager)
+  - [CSS architecture](#css-architecture)
+  - [JS customization](#js-customization)
+  - [Customization, theming, and tokens](#customization-theming-and-tokens)
+    - [Using tokens in theme settings](#using-tokens-in-theme-settings)
+    - [Set the base asset paths (fonts and images)](#set-the-base-asset-paths-fonts-and-images)
+  - [Where things live](#where-things-live)
+  - [Browser support](#browser-support)
+  - [Accessibility](#accessibility)
+  - [Fractal](#fractal)
+    - [Template compatibility](#template-compatibility)
+  - [Long-term support of v1.x](#long-term-support-of-v1x)
+  - [Need installation help?](#need-installation-help)
+  - [Contributing to the code base](#contributing-to-the-code-base)
+  - [Reuse of open-source style guides](#reuse-of-open-source-style-guides)
+  - [Licenses and attribution](#licenses-and-attribution)
+  - [Contributing](#contributing)
 
 ## Background
 
@@ -62,12 +65,12 @@ How you implement the design system depends on the needs of your project and you
 
 ### Download and install
 
-1. Download the [USWDS zip file](https://github.com/uswds/uswds/releases/download/v2.11.2/uswds-2.11.2.zip) from the latest USWDS release and open that file.
+1. Download the [USWDS zip file](https://github.com/uswds/uswds/releases/download/v2.12.0/uswds-2.12.0.zip) from the latest USWDS release and open that file.
 
    After extracting the zip file you should see the following file and folder structure:
 
    ```
-   uswds-2.11.2/
+   uswds-2.12.0/
    ├── css/
    │   ├── uswds.min.css.map
    │   ├── uswds.min.css
@@ -98,7 +101,7 @@ How you implement the design system depends on the needs of your project and you
    ```
    example-project/
    ├── assets/
-   │   ├── uswds-2.11.2/
+   │   ├── uswds-2.12.0/
    │   ├── stylesheets/
    │   ├── images/
    │   └── javascript/
@@ -118,11 +121,11 @@ How you implement the design system depends on the needs of your project and you
        <meta charset="utf-8" />
        <meta http-equiv="X-UA-Compatible" content="IE=edge" />
        <title>My Example Project</title>
-       <script src="assets/uswds-2.11.2/js/uswds-init.min.js"></script>
-       <link rel="stylesheet" href="assets/uswds-2.11.2/css/uswds.min.css" />
+       <script src="assets/uswds-2.12.0/js/uswds-init.min.js"></script>
+       <link rel="stylesheet" href="assets/uswds-2.12.0/css/uswds.min.css" />
      </head>
      <body>
-       <script src="assets/uswds-2.11.2/js/uswds.min.js"></script>
+       <script src="assets/uswds-2.12.0/js/uswds.min.js"></script>
      </body>
    </html>
    ```
@@ -247,7 +250,7 @@ We recommend using a **minifier** like [csso](https://github.com/css/csso) to co
 
 ### Use another framework or package manager
 
-If you’re using another framework or package manager that doesn’t support `npm`, you can find the source files in this repository and use them in your project. Otherwise, we recommend that you follow the [download instructions](#download). Please note that the core team [isn’t responsible for all frameworks’ implementations](https://github.com/uswds/uswds/issues/877).
+If you’re using another framework or package manager that doesn’t support `npm`, you can find the source files in this repository and use them in your project. Otherwise, we recommend that you follow the [download instructions](#download-and-install). Please note that the core team [isn’t responsible for all frameworks’ implementations](https://github.com/uswds/uswds/issues/877).
 
 If you’re interested in maintaining a package that helps us distribute USWDS, the project’s build system can help you create distribution bundles to use in your project. Please read our [contributing guidelines](CONTRIBUTING.md#building-the-project-locally-with--gulp-) to locally build distributions for your framework or package manager.
 
@@ -304,7 +307,9 @@ function App() {
 
   useEffect(() => {
     // initialize
-    characterCount.on(ref); // default ref is document.body, if you want to use default you do not have to pass arguments
+    characterCount.on(ref);
+    // default ref is document.body, if you want to use
+    // default you do not have to pass arguments
     accordion.on();
 
     // remove event listeners when component un-mounts.
@@ -321,7 +326,9 @@ Angular example:
 ```js
 export class App implements OnInit {
   constructor() {
-    this.ref = document.body; // default ref is document.body, if you want to use default you do not have to pass arguments
+    this.ref = document.body;
+    // default ref is document.body, if you want to use
+    // default you do not have to pass arguments
   }
 
   ngOnInit() {
@@ -338,6 +345,8 @@ export class App implements OnInit {
 }
 ```
 
+> Those using **Webpack 5** can take advantage of the updated exports field which allows declaration for requests like `import "uswds"` or `import accordion from "uswds/src/js/components/accordion"`
+
 ## Customization, theming, and tokens
 
 USWDS 2.0 provides extensive support for theming via its theme settings files introduced in [Sass and theme settings](#sass-and-theme-settings), above.

SECURITY.md

@@ -15,7 +15,7 @@ We include a security and vulnerability report with every USWDS release, and rel
 We encourage you to verify the security and status of the USWDS package:
 
 1. **Check the vulnerability badge.** Confirm the vulnerability badge in the [USWDS Github code repository](https://github.com/uswds/uswds) says there are `0` vulnerabilities.
-1. **Download the package via npm.** We recommend using the [npm package](https://designsystem.digital.gov/documentation/developers/#install-using-npm) instead of the [zip file](https://designsystem.digital.gov/documentation/developers/#download), whenever possible. Using npm makes it easier to stay up-to-date and use the latest USWDS version as a project dependency, and is a secure and reliable way to download USWDS source code.
+1. **Download the package via npm.** We recommend using the [npm package](https://designsystem.digital.gov/documentation/developers/#install-using-npm) instead of the [zip file](https://designsystem.digital.gov/documentation/developers/#download-and-install), whenever possible. Using npm makes it easier to stay up-to-date and use the latest USWDS version as a project dependency, and is a secure and reliable way to download USWDS source code.
 
 ## Report a security issue
 

config/gulp/sass.js

@@ -8,17 +8,16 @@ const gulpStylelint = require("gulp-stylelint");
 const postcss = require("gulp-postcss");
 const replace = require("gulp-replace");
 const rename = require("gulp-rename");
-const sass = require("gulp-sass");
+const sass = require("gulp-dart-scss");
 const sourcemaps = require("gulp-sourcemaps");
 const changed = require("gulp-changed");
 const dutil = require("./doc-util");
 const pkg = require("../../package.json");
+const { logError } = require("./doc-util");
 
 const task = "sass";
 const normalizeCssFilter = filter("**/normalize.css", { restore: true });
 
-sass.compiler = require("sass");
-
 const IGNORE_STRING = "This file is ignored";
 const ignoreStylelintIgnoreWarnings = (lintResults) =>
   formatters.string(
@@ -91,13 +90,7 @@ gulp.task(
     return gulp
       .src("src/stylesheets/uswds.scss")
       .pipe(sourcemaps.init({ largeFile: true }))
-      .pipe(
-        sass
-          .sync({
-            outputStyle: "expanded",
-          })
-          .on("error", sass.logError)
-      )
+      .pipe(sass({ outputStyle: "expanded" }).on("error", logError))
       .pipe(postcss(pluginsProcess))
       .pipe(replace(/\buswds @version\b/g, `uswds v${pkg.version}`))
       .pipe(gulp.dest("dist/css"))