USWDS-Compile - return projectSass styles

[amyleadem]

Description

When running both the compile and watch tasks, the files in paths.src.projectSass are not included in the compiled CSS.

Addresses Issue #19

Steps to reproduce

1. Install uswds-compile on a static project
2. Follow the USWDS-compile usage instructions
3. In your project's gulpfile.js, designate a custom directory for paths.src.projectSass
4. Check your compiled assets to see if the custom styles were included

In the example shown below, you'll see that the projectSass directory is ignored during compilation. index.css does not compile and the styles from the projectSass directory are not included inside styles.css:

Proposed resolution

When the paths.src.projectSass is included in the buildSass task in the uswds-compile gulpfile.js, it compiles the expected files inside paths.dist.css.

[thisisdano]

So, in reviewing this, I'm now not really sure that this is a bug.

How is compile working now?

So, we designed the compile workflow with the intention that the styles.scss Sass entry point output to paths.dist.theme is the primary entry point for the project. There will be a problem if teams want to set another file as the primary entry point, or if they want to output additional CSS files in the compile process.

What does the user want to do?

I understand wanting to isolate the USWDS files from the project files. When teams want to use or update uswds, they'll want to grab all the USWDS assets from the npm package and move them into a location that's visible to the project (like an /assets directory. Teams don't ever want to overwrite any project code in this process — they don't want a new version of styles.scss or _uswds-theme.scss to clobber their project specific work!

The .scss files in the USWDS theme are meant to be edited, but none of the other assets — fonts, images, compiled JS (with the exception of the SVG sprite, which is its own can of worms!) are meant to be editable. They can all be updated at will.

But not only are the .scss meant to be edited, but in most projects, USWDS will not work properly if they are not edited.

Let's look at a proposed file structure like the one in the original issue:

├── assets
│  ├── uswds
│  │   ├── fonts
│  │   ├── img
│  │   ├── scss
│  │   │   ├── _uswds-theme.scss
│  │   │   ├── _uswds-theme-custom-styles.scss
│  │   │   └── styles.scss
│  │   └── js
│  └── other stuff
├── sass
│  ├── project.scss
│  └── includes
│      ├── _module-primary.scss
│      └── _module-secondary.scss
...

There's a project Sass file which must look a bit like this:

/* project.scss */

@forward "../assets/uswds/scss/styles";
@forward "includes/module-primary";
@forward "includes/module-secondary";

The USWDS Sass looks like this:

/* styles.scss */

@forward "uswds-theme";
@forward "uswds";
@forward "uswds-custom-styles";

If we assume that this file gets clobbered with every asset install, it's pretty much pointless. The team can never update packages, and never update the either the theme file or the custom styles file (or their locations). The @forward "../assets/uswds/scss/styles" in project.scss will always point to a default file with no custom settings. In order to make it work properly, the team would need to recreate that functionality in project.scss and create a new _uswds-theme.scss file with custom settings.

Their project Sass file would have to look like this:

/* project.scss */

@forward "includes/NEW-uswds-theme";
@forward "{{ USWDS PACKAGES }}";
@forward "includes/module-primary";
@forward "includes/module-secondary";

They are re-creating styles.scss in project.scss.

How can teams accomplish this?

Instead, I believe teams should use styles.scss as their project Sass entry point. They can rename it if they like. This location can be set with paths.dist.theme. In this project, it would look something like:

uswds.paths.dist.theme = "./sass";

Then, their project would look like this:

├── assets
│  ├── uswds
│  │   ├── fonts
│  │   ├── img
│  │   └── js
│  └── other stuff
├── sass
│  ├── _uswds-theme.scss
│  ├── _uswds-theme-custom-styles.scss
│  ├── project.scss
│  ├── styles.scss
│  └── includes
│      ├── _module-primary.scss
│      └── _module-secondary.scss
...

They should use either styles.scss or project.scss as the project entry point and harmonize those files into a single file. Let's call it project.scss:

/* project.scss */

@forward "uswds-theme";
@forward "{{ USWDS PACKAGES }}";
@forward "includes/module-primary";
@forward "includes/module-secondary";

When Compile runs, it will see that file and compile it.

But what about clobbering assets on update?

Now teams should use the copyAssets task to copy and update the assets in the future. That will copy all the static assets and leave the Sass files untouched.

Recommendations

• Use init only once.
• Use paths.dist.theme as the spot where you're keeping your active Sass files
• Use our styles.scss as the Sass entry point — or recreate its functionality in an existing Sass entry point
• Update and install static assets with the copyAssets task
• Compile only from a single Sass entry point, defined in paths.dist.theme

[amyleadem]

Closing this PR because the code is working as intended. Instead, we can evaluate our documentation to see if there are ways to provide clarity.