Description

Closes: #4698

Problem details:

Styles from normalize.css are taking precedence over some USWDS global typography styles when either the $theme-global-content-styles and/or $theme-global-paragraph-styles setting is set to true. Because normalize.css is reset CSS, it should not take precedence over any USWDS styles.

How this is happening

In limited cases, some root global styles are compiling at the top of the CSS file, above the normalize reset CSS. This appears to happen under the following conditions:

1. The related style rule is defined using a Sass placeholder
2. The placeholder is declared in one file and @extended in another
   1. Example: usa-content-styles.scss

Here, the main risk is to root global styles (in this case, the heading and paragraph elements) that do not have the specificity to take precedence over normalize CSS.

Compilation order

To solve this and retain normalize.css as our reset, we must reorder how the CSS compiles root global styles so that reset CSS does not take precedence over USWDS styles.

Proposed solution:

Sass mixins compile differently than placeholders, and replacing the affected placeholders with mixins reorders the root CSS below normalize.

However, using mixins throughout has a pitfall we discovered previously: Using the typeset mixins with * + & inside caused confusion in the compilation. Please reference the notes in PR 4576 for more details.

Placeholders do not struggle with * + & in the same way, so I have limited the placeholder implementation of %usa-prose-p and %usa-prose-headline to be only inside usa-prose.scss. This code will compile above normalize in the CSS, but it has the specificity to take precendence.

Specificity wins

Now only elements with parent selectors live above normalize:

To reproduce issue:

1. Create test USWDS project
2. Set $theme-global-content-styles: true
3. Open sample html

   <h1>Headline</h1>
   <p>The heading and button have different margins between v2 and v3 of USWDS, due to the import order of _normalize.scss (I think?). </p>
   <button class="usa-button">Button</button>

4. Notice the vertical margin issues (outlined in Normalize.css has higher precedence in version 3 #4698)
   

Things to check:

Confirm vertical margins

• Headlines should have margin-bottom: 0
• <p>, <button> should have margin-top: 1em

Confirm successul usa-prose compilation

A successful test will show:

.usa-prose > * + p{
  margin-top:1em;
}
.usa-prose > p + *{
  margin-top:1em;
}

.usa-prose > h1,
.usa-prose > h2,
.usa-prose > h3,
.usa-prose > h4,
.usa-prose > h5,
.usa-prose > h6{
  margin-bottom:0;
  margin-top:0;
  clear:both;
}
.usa-prose > * + h1,
.usa-prose > * + h2,
.usa-prose > * + h3,
.usa-prose > * + h4,
.usa-prose > * + h5,
.usa-prose > * + h6{
  margin-top:1.5em;
}
.usa-prose > h1 + *,
.usa-prose > h2 + *,
.usa-prose > h3 + *,
.usa-prose > h4 + *,
.usa-prose > h5 + *,
.usa-prose > h6 + *{
  margin-top:1em;
}

Future solution

In the future, we should look to replace normalize, as it does not appear to be an actively maintained code base.

Additional information

Before you hit Submit, make sure you’ve done whichever of these applies to you:

• Follow the 18F Front End Coding Style Guide and Accessibility Guide.
• Run npm test and make sure the tests for the files you have changed have passed.
• Run your code through HTML_CodeSniffer and make sure it’s error free.
• Title your pull request using this format: [Website] - [UI component]: Brief statement describing what this pull request solves.