diff --git a/.circleci/config.yml b/.circleci/config.yml index 5e69915f33..d2e6a3d8d8 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -3,14 +3,14 @@ version: 2 references: container: &container docker: - - image: circleci/node:8.10-browsers + - image: circleci/node:10.15.1-browsers environment: CHROME_PATH: /usr/bin/google-chrome restore_deps: &restore_deps restore_cache: keys: - - v1-uswds-dependencies-{{ checksum "package-lock.json" }} + - v2-uswds-dependencies-{{ checksum "package-lock.json" }} jobs: build: @@ -22,12 +22,15 @@ jobs: command: sudo npm install -g codeclimate-test-reporter - restore_cache: keys: - - v1-uswds-dependencies-{{ checksum "package-lock.json" }} + - v2-uswds-dependencies-{{ checksum "package-lock.json" }} - run: npm install - save_cache: paths: - node_modules - key: v1-uswds-dependencies-{{ checksum "package-lock.json" }} + key: v2-uswds-dependencies-{{ checksum "package-lock.json" }} + - run: + name: Setup Snyk + command: sudo npm install -g snyk - run: name: Run test command: npm test @@ -48,7 +51,7 @@ jobs: - checkout - restore_cache: keys: - - v1-uswds-dependencies-{{ checksum "package-lock.json" }} + - v2-uswds-dependencies-{{ checksum "package-lock.json" }} - run: npm install --ignore-scripts - run: npm rebuild node-sass - run: diff --git a/.gitignore b/.gitignore index 42b7d8c585..8fb676d973 100644 --- a/.gitignore +++ b/.gitignore @@ -4,6 +4,7 @@ # ignore Node-specific files and directories node_modules/ npm-debug.log* +.gz # code coverage coverage/ @@ -20,3 +21,6 @@ src/stylesheets/lib # ignore saved screenshots spec/screenshots/*.png spec/screenshots/metadata.js + +# ignore sass cache +.sass-cache/ diff --git a/.nvmrc b/.nvmrc index 45a4fb75db..1047f69681 100644 --- a/.nvmrc +++ b/.nvmrc @@ -1 +1 @@ -8 +10.15.1 diff --git a/.stylelintrc.json b/.stylelintrc.json new file mode 100644 index 0000000000..481999e9a1 --- /dev/null +++ b/.stylelintrc.json @@ -0,0 +1,76 @@ +{ + "plugins": [ + "stylelint-scss" + ], + "rules": { + "at-rule-name-case": "lower", + "at-rule-name-space-after": "always-single-line", + "at-rule-semicolon-newline-after": "always", + "block-closing-brace-newline-after": "always", + "block-closing-brace-newline-before": "always-multi-line", + "block-closing-brace-space-before": "always-single-line", + "block-no-empty": true, + "block-opening-brace-newline-after": "always-multi-line", + "block-opening-brace-space-after": "always-single-line", + "block-opening-brace-space-before": "always", + "color-hex-case": "lower", + "color-no-invalid-hex": true, + "declaration-bang-space-after": "never", + "declaration-bang-space-before": "always", + "declaration-block-no-shorthand-property-overrides": true, + "declaration-block-semicolon-newline-after": "always-multi-line", + "declaration-block-semicolon-space-after": "always-single-line", + "declaration-block-semicolon-space-before": "never", + "declaration-block-single-line-max-declarations": 1, + "declaration-block-trailing-semicolon": "always", + "declaration-colon-space-after": "always-single-line", + "declaration-colon-space-before": "never", + "declaration-no-important": true, + "function-calc-no-unspaced-operator": true, + "function-comma-space-after": "always-single-line", + "function-comma-space-before": "never", + "function-linear-gradient-no-nonstandard-direction": true, + "function-max-empty-lines": 0, + "function-name-case": "lower", + "function-parentheses-space-inside": "never-single-line", + "function-url-quotes": "always", + "function-whitespace-after": "always", + "indentation": 2, + "length-zero-no-unit": true, + "max-empty-lines": 1, + "max-nesting-depth": 4, + "media-feature-colon-space-after": "always", + "media-feature-colon-space-before": "never", + "media-feature-range-operator-space-after": "always", + "media-feature-range-operator-space-before": "always", + "media-query-list-comma-space-after": "always-single-line", + "media-query-list-comma-space-before": "never", + "media-feature-parentheses-space-inside": "never", + "no-eol-whitespace": true, + "no-extra-semicolons": true, + "no-invalid-double-slash-comments": true, + "number-no-trailing-zeros": true, + "property-case": "lower", + "selector-attribute-brackets-space-inside": "never", + "selector-attribute-operator-space-after": "never", + "selector-attribute-operator-space-before": "never", + "selector-combinator-space-after": "always", + "selector-combinator-space-before": "always", + "selector-list-comma-space-before": "never", + "selector-max-empty-lines": 0, + "selector-max-id": 0, + "selector-no-qualifying-type": true, + "selector-pseudo-class-case": "lower", + "selector-pseudo-class-parentheses-space-inside": "never", + "selector-pseudo-element-case": "lower", + "selector-pseudo-element-no-unknown": true, + "selector-type-case": "lower", + "string-no-newline": true, + "string-quotes": "single", + "unit-case": "lower", + "value-list-comma-newline-after": "always-multi-line", + "value-list-comma-space-after": "always-single-line", + "value-list-comma-space-before": "never" + }, + "ignoreFiles": "./src/stylesheets/lib/**/*" +} diff --git a/LICENSE.md b/LICENSE.md index 02237347d4..e17573e37c 100644 --- a/LICENSE.md +++ b/LICENSE.md @@ -2,18 +2,22 @@ ### Files licensed under the SIL Open Font License -The Source Sans Pro font files in `src/fonts` are a customized subset of [Source Sans Pro](https://github.com/adobe-fonts/source-sans-pro), licensed under the [SIL Open Font License](http://scripts.sil.org/cms/scripts/page.php?item_id=OFL), and copyright [Adobe Systems Incorporated](http://www.adobe.com/), with Reserved Font Name 'Source'. All Rights Reserved. Source is a trademark of Adobe Systems Incorporated in the United States and/or other countries. +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), licensed under the [SIL Open Font License](http://scripts.sil.org/cms/scripts/page.php?item_id=OFL), and copyright [Adobe Systems Incorporated](http://www.adobe.com/), with Reserved Font Name 'Source'. All Rights Reserved. Source is a trademark of Adobe Systems Incorporated in the United States and/or other countries. -The Merriweather font files in `src/fonts` are from [Google Web Fonts](https://www.google.com/fonts#UsePlace:use/Collection:Merriweather:400,300,400italic,700,700italic), licensed under the [SIL Open Font License](http://scripts.sil.org/cms/scripts/page.php?item_id=OFL), and copyright [Sorkin Type Co](www.sorkintype.com) with Reserved Font Name 'Merriweather'. +The Merriweather font files in `src/fonts/merriweather` are v2.001 from [GitHub](https://github.com/EbenSorkin/Merriweather/releases/tag/v2.001) subsetted into Latin and with additional formats generated with [Transfonter](https://transfonter.org/), licensed under the [SIL Open Font License](http://scripts.sil.org/cms/scripts/page.php?item_id=OFL), and copyright [Sorkin Type Co](www.sorkintype.com) with Reserved Font Name 'Merriweather'. + +The Public Sans font files in `src/fonts/public-sans` are licensed under the [SIL Open Font License](http://scripts.sil.org/cms/scripts/page.php?item_id=OFL). 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 1.1](http://scripts.sil.org/OFL). +### Files licensed under the Apache 2.0 License + +The Roboto Mono font files in `src/fonts/roboto-mono` are licensed under the [Apache 2.0 License](http://www.apache.org/licenses/LICENSE-2.0). + ### Files licensed under the MIT license The files in `src/stylesheets/lib` are from: -* [Bourbon](http://bourbon.io/), copyright [thoughtbot](https://thoughtbot.com/), inc., under the [MIT license](https://github.com/thoughtbot/neat/blob/master/LICENSE.md). -* [Neat](http://neat.bourbon.io/), copyright [thoughtbot](https://thoughtbot.com/), inc., also under the [MIT license](https://github.com/thoughtbot/neat/blob/master/LICENSE.md). * [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: diff --git a/README.md b/README.md index 14e222aa26..f5f9c05595 100644 --- a/README.md +++ b/README.md @@ -1,27 +1,29 @@ -# U.S. Web Design System +# United States Web Design System [![CircleCI Build Status](https://circleci.com/gh/uswds/uswds/tree/develop.svg?style=shield)](https://circleci.com/gh/uswds/uswds/tree/develop) [![Test Coverage](https://api.codeclimate.com/v1/badges/c10cd4505d61d161cd3a/test_coverage)](https://codeclimate.com/github/uswds/uswds/test_coverage) -The [U.S. Web Design System](https://designsystem.digital.gov) includes a library of open source UI components and a visual style guide for U.S. federal government websites. +The [United States Web Design System](https://designsystem.digital.gov) includes a library of open source UI components and a visual style guide for U.S. federal government websites. -This repository is for the Design System itself. We maintain [another repository for the documentation and website](https://github.com/uswds/uswds-site). To see the Design System and documentation on the web, visit [https://designsystem.digital.gov](https://designsystem.digital.gov). +This repository is for the design system code itself. We maintain [another repository for the documentation and website](https://github.com/uswds/uswds-site). To see the design system and its documentation on the web, visit [https://designsystem.digital.gov](https://designsystem.digital.gov). ## Contents * [Background](#background) * [Recent updates](#recent-updates) * [Getting started](#getting-started) -* [Using the Design System](#using-the-design-system) +* [Using the design system](#using-the-design-system) * [Download](#download) * [Install using `npm`](#install-using-npm) - * [Importing assets](#importing-assets) - * [Sass](#sass) + * [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 and theming](#customization-and-theming) - * [Set the base asset path (fonts and images)](#set-the-base-asset-path-fonts-and-images) +* [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) @@ -35,42 +37,40 @@ This repository is for the Design System itself. We maintain [another repository ## Background -The components and style guide of the U.S. Web Design System follows industry-standard web accessibility guidelines and use the best practices of existing style libraries and modern web design. The [U.S. Digital Service](https://www.whitehouse.gov/digital/united-states-digital-service) and [18F](https://18f.gsa.gov/) created the U.S. Web Design System for designers and developers. The U.S. Web Design System is a project of GSA’s [Technology Transformation Service](https://www.gsa.gov/about-us/organization/federal-acquisition-service/technology-transformation-services), maintained by the Office of Products and Programs. They are designed for use by government product teams who want to create beautiful, easy-to-use online experiences for the public. To learn more about the project, check out this [blog post](https://18f.gsa.gov/2015/09/28/web-design-standards/) and to view websites and applications check out our list [here](docs/WHO_IS_USING_USWDS.md). +USWDS components and style guide follow industry-standard accessibility guidelines and use the best practices of existing style libraries and modern web design. The [U.S. Digital Service](https://www.whitehouse.gov/digital/united-states-digital-service) and [18F](https://18f.gsa.gov/) created USWDS for designers and developers. USWDS is a project of GSA’s [Technology Transformation Service](https://www.gsa.gov/about-us/organization/federal-acquisition-service/technology-transformation-services), maintained by the Office of Products and Programs. They are designed for use by government product teams who want to create beautiful, easy-to-use online experiences for the public. To learn more about the project, check out this [blog post](https://18f.gsa.gov/2015/09/28/web-design-standards/) and to view websites and applications check out our list [here](docs/WHO_IS_USING_USWDS.md). ## Recent updates -Information about the most recent release of the Design System can always be found in the [release history](https://github.com/uswds/uswds/releases). We include details about significant updates and any backwards incompatible changes along with a list of all changes. +Information about the most recent release of the design system can always be found in the [release history](https://github.com/uswds/uswds/releases). We include details about significant updates and any backwards incompatible changes along with a list of all changes. ## Getting started -We’re glad you’d like to use the Design System — here’s how you can get started: +We’re glad you’d like to use the design system — here’s how you can get started: * Designers: [Check out our Getting Started for Designers information](https://designsystem.digital.gov/getting-started/designers/). - * [Design files of all the assets included in the Design System are available for download](https://github.com/uswds/uswds-assets/archive/master.zip). + * [Design files of all the assets included in the design system are available for download](https://github.com/uswds/uswds-assets/archive/master.zip). * Developers: [Follow the instructions in this README to get started.](#using-the-design-system) * [CSS, JavaScript, image, and font files of all the assets on this site are available for download](https://github.com/uswds/uswds/releases/latest). -## Using the Design System +## Using the design system -There are a few different ways to use the Design System within your project. Which one you choose depends on the needs of your project and how you are most comfortable working. Here are a few notes on what to consider when deciding which installation method to use: +How you implement the design system depends on the needs of your project and your workstyle. We recommend implementing the design system with `npm`, but we also provide a direct download if `npm` will not work for you or your project. -*Download the Design System if:* -- You are not familiar with `npm` and package management. +- **[Download the design system](#download)** if you are not familiar with `npm` and package management. -*Use the Design System `npm` package if:* -- You are familiar with using `npm` and package management. +- **[Use the design system `npm` package](#install-using-npm)** if you are familiar with using `npm` and package management. ### Download -1. Download the [USWDS zip file](https://github.com/uswds/uswds/releases/latest) from the latest release and open that file. +1. Download the [USWDS zip file](https://github.com/uswds/uswds/releases/tag/v2.0.0) from the latest USWDS release and open that file. After extracting the zip file you should see the following file and folder structure: ``` - uswds-1.0.0/ + uswds-2.0.0/ ├── css/ │ ├── uswds.min.css.map │ ├── uswds.min.css @@ -90,16 +90,16 @@ There are a few different ways to use the Design System within your project. Whi ``` example-project/ ├── assets/ - │ ├── uswds-1.0.0/ + │ ├── uswds-2.0.0/ │ ├── stylesheets/ │ ├── images/ │ └── javascript/ └── index.html ``` - You'll notice in our example above that we also outline a `stylesheets`, `images` and `javascript` folder in your `assets` folder. These folders are to help organize any assets that are unique to your project. + You'll notice in our example above that we also outline a `stylesheets`, `images` and `javascript` folder in your `assets` folder. These folders are to help organize any assets that are unique to your project and separate from the design system assets. -3. To use the Design System on your project, you’ll need to reference the [CSS (*C*ascading *S*tyle *S*heets)](https://developer.mozilla.org/en-US/docs/Web/CSS) and JavaScript files in each HTML page or dynamic templates in your project. (We also provide Sass (SCSS) files in the zip file which you can compile to CSS. See [Sass](#sass).) +3. Reference the CSS and JavaScript files in each HTML page or dynamic templates in your project. We also provide Sass (.scss) files in the zip package which you can use to generate new CSS with project-specific settings. See [Sass](#sass) for more information. Here is an example of how to reference these assets in your `index.html` file: @@ -110,26 +110,26 @@ There are a few different ways to use the Design System within your project. Whi