Restructure output as package overrides

.gitignore

@@ -1,5 +1,6 @@
 /dist
 /build
+/packages
 /node_modules
 /tmp
 .DS_Store

.stylelintrc.json

@@ -1,4 +1,4 @@
 {
   "extends": "@18f/identity-stylelint-config",
-  "ignoreFiles": "./src/scss/uswds/**/*"
+  "ignoreFiles": "./src/scss/uswds-packages/**/*"
 }

CONTRIBUTING.md

@@ -15,7 +15,7 @@ If you have any questions or want to read more, check out the [18F Open Source P
 Since the Login.gov Design System is based upon the [U.S. Web Design System (USWDS)](https://designsystem.digital.gov/), the code should reflect this:
 
 - Where possible, use [the available Sass theme variables](https://designsystem.digital.gov/documentation/developers/#customization-theming-and-tokens) to customize the appearance of components. These are configured under `src/scss/uswds-theme`. We only include the customized variables, to improve visibility of where differences are expected. Refer to the [USWDS theme variables source](https://github.com/uswds/uswds/tree/develop/src/stylesheets/theme) for the full set of configuration values.
-- To limit side-effects and to clarify where styles are extended, customized USWDS styles should follow as close to the file location and CSS selector as possible. For example, if USWDS defines a selector `.usa-overlay` in `src/stylesheets/components/_header.scss` which defines a style `background` that we want to override, the style should be located at an identically-named selector in `src/scss/components/_header.scss` in this project.
+- To limit side-effects and to clarify where styles are extended, customized USWDS styles should follow as close to the file location and CSS selector as possible. For example, if USWDS defines a selector `.usa-header` in `packages/usa-header` which defines a style `background` that we want to override, the style should be located at an identically-named selector in `src/scss/packages/_usa-header.scss` in this project.
 - Prefer color and size tokens when possible. Never use hard-coded hex colors. Instead, use the `color` SCSS function with a [color token](https://design.login.gov/utilities/color/) as its argument.
 
 ## Public domain

Makefile

@@ -45,7 +45,7 @@ build: build-docs build-assets build-package
 build-docs:
 	JEKYLL_ENV=production bundle exec jekyll build
 
-build-assets: build-sass-and-js build-fonts build-images copy-scss
+build-assets: build-sass-and-js build-fonts build-images copy-scss build-sass-packages
 
 build-package:
 	$(NODE_BIN)/gulp build-package
@@ -56,6 +56,11 @@ build-sass-and-js:
 	OUTPUT_DIR=$(OUTPUT_DIR) \
 	$(NODE_BIN)/gulp build
 
+build-sass-packages:
+	mkdir -p packages
+	cp -r node_modules/@uswds/uswds/packages/* packages
+	cp src/scss/packages/* packages
+
 build-fonts:
 	mkdir -p $(OUTPUT_DIR)/assets/fonts
 	cp -r node_modules/@uswds/uswds/dist/fonts $(OUTPUT_DIR)/assets
@@ -65,7 +70,11 @@ build-images:
 	cp -r node_modules/@uswds/uswds/dist/img $(OUTPUT_DIR)/assets
 	cp -r src/img $(OUTPUT_DIR)/assets
 
-copy-scss:
+copy-uswds-scss:
+	mkdir -p $(OUTPUT_DIR)/assets/scss/uswds-packages
+	cp -r node_modules/@uswds/uswds/packages/* $(OUTPUT_DIR)/assets/scss/uswds-packages
+
+copy-scss: copy-uswds-scss
 	$(NODE_BIN)/gulp copy-scss
 
 test: build

README.md

@@ -113,14 +113,15 @@ Below are various ways to use the Login.gov Design System throughout our various
 
  Finally, import the styles into your main stylesheet:
 
- ```scss
- // app/assets/stylesheets/application.css.scss
-
- $theme-font-path: 'fonts';
- $theme-image-path: 'img';
-
- @import '@18f/identity-design-system/dist/assets/scss/styles';
- ```
+```scss
+// app/assets/stylesheets/application.css.scss
+@use 'uswds-core' with (
+  $theme-font-path: 'fonts',
+  $theme-image-path: 'img',
+);
+
+@forward 'uswds';
+```
 
  If you're using Sprockets and precompiling assets you'll need to update your
  Sprockets manifest to include the images and fonts for production:

gulpfile.js

@@ -130,7 +130,7 @@ gulp.task('build-sass', () =>
     .pipe(
       sass({
         outputStyle: isProduction ? 'compressed' : 'expanded',
-        includePaths: ['node_modules/@uswds/uswds/packages'],
+        includePaths: ['./src/scss/packages', './src/scss/uswds-packages'],
       }),
     )
     .pipe(
@@ -161,14 +161,7 @@ gulp.task('copy-login-scss', () =>
     .pipe(gulp.dest(SCSS_DEST)),
 );
 
-gulp.task('copy-uswds-scss', () =>
-  gulp
-    .src(['node_modules/@uswds/uswds/dist/scss/**/*.scss'])
-    .pipe(underscorePrefix())
-    .pipe(gulp.dest(`${SCSS_DEST}/uswds`)),
-);
-
-gulp.task('copy-scss', gulp.series('copy-login-scss', 'copy-uswds-scss'));
+gulp.task('copy-scss', gulp.series('copy-login-scss'));
 
 gulp.task('lint', gulp.parallel('lint-js', 'lint-sass'));
 

package.json

@@ -40,7 +40,8 @@
   },
   "files": [
     "build",
-    "dist/assets/**/*"
+    "dist/assets/**/*",
+    "packages"
   ],
   "repository": {
     "type": "git",