LG-3187: Upgrade USWDS to 2.9.0 #159

aduth · 2020-10-13T15:08:47Z

~~Related (merges to): #158~~

Preview on Federalist: https://federalist-2f194a10-945e-4413-be01-46ca6dae5358.app.cloud.gov/preview/18f/identity-style-guide/aduth-uswds-upgrade/

This pull request upgrades USWDS dependency from ^2.0.3. to ^2.9.0 (latest).

Notes:

See additional documented findings in ticket LG-3187 description
There have already been a few conflicts in the use of colors. As noted in the research findings, USWDS v2.4.0 introduced additional support for non-token values. The USWDS internal implementation makes some assumptions about the readiness of tokens at initialization, which conflicted with previous usage of token assignment to theme variables. Furthermore, there's at least one upstream bug in USWDS bypassing color tokens which does not interoperate with custom theme colors (source, pending upstream bugfix).

aduth · 2020-10-13T15:39:26Z

Furthermore, there's at least one upstream bug in USWDS bypassing color tokens which does not interoperate with custom theme colors (source, pending upstream bugfix).

See uswds/uswds#3762

aduth · 2020-10-14T21:35:49Z

Regression: Banner link reverts to blue, resulting in accessibility failures.

Screenshot (before):

Error:

    "http://0.0.0.0:35819/accessibility/policies/": [
      {
        "code": "WCAG2AA.Principle1.Guideline1_4.1_4_3.G18.Fail",
        "context": "<span class=\"usa-banner__button-text\">Here’s how you know</span>",
        "message": "This element has insufficient contrast at this conformance level. Expected a contrast ratio of at least 4.5:1, but text in this element has a contrast ratio of 2.66:1. Recommendation: change text colour to #fdfeff.",
        "type": "error",
        "typeCode": 1,
        "selector": "html > body > div:nth-child(2) > div > header > div > button > span"
      }
    ],

Fix: 23f63c9

Impact on other products: None, assuming upgrade, since changes are exclusive to stylesheet updates.

Screenshot (after):

aduth · 2020-10-14T21:46:39Z

Regression: USWDS upgraded the major version of Normalize.css, causing certain opinionated styling to be omitted. This causes pre tags to unexpectedly overflow.

Related: https://github.com/necolas/normalize.css/blob/master/CHANGELOG.md#400-march-19-2016

Screenshot (before):

Fix: b6dc182, e50689e

Impact on other products: None, assuming upgrade, since changes are exclusive to stylesheet updates.

Screenshot (after):

aduth · 2020-10-14T22:07:26Z

Update from research findings:

Header and banner width now controlled in settings: Now there are explicit settings for controlling the max-width of the gov banner and the header.

Affected variables are renamed in 9fcc61c.

See: https://designsystem.digital.gov/about/releases/#version-220

aduth · 2020-10-15T13:05:12Z

Acknowledged and expected change: Footer text changes from Serif (Merriweather) to Sans-Serif (Source Sans Pro).

Screenshot:

Before	After

Related changelog: USWDS v2.3.0

Now components reliably respect their font settings. Setting values like $theme-footer-font-family should set the font face for the entire component, but some CSS specificity quirks were overriding these values in some instances. Now, setting a component’s font face works as expected, with no secret overrides. (uswds/uswds#3253)

Relevant variable assignment:

https://github.com/18F/identity-style-guide/blob/b196ccfcfc3da550275e43eb21e021f6581e2c83/src/scss/uswds-theme/_components.scss#L36

aduth · 2020-10-15T14:12:49Z

Acknowledged and expected change: Line-heights on most content has changed slightly, in direct correlation with a fix in USWDS 2.2.0 to improve rounding precision of the line-height functions. This is only explicitly mentioned to affect navigation, but the affected functions (px-to-rem, line-height, lh) are used extensively throughout USWDS. The effect is that pages may extend longer vertically than they had previously (verified on documentation site with visual regression test results).

Pull request: uswds/uswds#3100

Fixes a spacing issue affecting the header nav indicator bars present since 2.0 that seems to be a result of rounding errors in line-height calculation.

Because this had a significant impact on visual regression testing, I was able to assess the impact of these and other changes by effectively reverting the fix: https://gist.github.com/aduth/77c4d3785666088282cee22f37acd981

The impact is noticeable only under scrutinous review of differences.

Example:

Before	After

aduth · 2020-10-15T14:24:41Z

⚠️ Requires markup changes at time of upgrade in dependent projects ⚠️

USWDS 2.5.0 includes updates to markup for the benefit of improved accessibility.

banner: is now a <section> instead of a <div> with the ARIA label Official government website
footer: nav includes the ARIA label of Footer navigation
graphic-list: uses h2 as a heading default instead of h3
hero: includes the ARIA label of Introduction
search: the search form is given the ARIA role of search
documentation template: includes only the main content in the <main> element. The nav is no longer treated as an <aside>

https://designsystem.digital.gov/about/releases/#version-250

Examples updated in: 64f32de

This will require corresponding markup changes in consuming projects at time of upgrade.

aduth · 2020-10-15T14:27:14Z

⚠️ Requires markup changes at time of upgrade in dependent projects ⚠️

USWDS 2.6.0 updates markup of search component.

Use more consistent search markup. We made the markup of usa-search more consistent and assured that the styling worked properly regardless of what version of the markup you’re using. This is not as breaking change, but we recommend updating your search markup to the most current version. (uswds/uswds#3327)

https://designsystem.digital.gov/about/releases/#version-260

Examples updated in: a611187

This will require corresponding markup changes in consuming projects at time of upgrade.

aduth · 2020-10-15T14:32:28Z

⚠️ Requires markup changes at time of upgrade in dependent projects ⚠️

USWDS 2.7.0 updates markup guidance for numeric input fields:

Improved mobile experience for numeric fields. We updated our guidance and code for numeric fields to follow the lead of gov.uk’s recent guidance and research. This updates those fields to use text rather than number inputs with an inputmode of numeric. (uswds/uswds#3392)

https://designsystem.digital.gov/about/releases/#version-270

Examples updated in: 231ebd3

This will require corresponding markup changes in consuming projects at time of upgrade.

aduth · 2020-10-15T14:35:34Z

Acknowledged and expected change: USWDS 2.7.0 fixes appearance of skip link to appear as link. This is desirable, no changes are necessary, and consuming projects will benefit immediately by upgrading.

Before	After

aduth · 2020-10-15T14:42:01Z

⚠️ Requires markup changes at time of upgrade in dependent projects ⚠️

USWDS 2.7.1 updates markup of SVG images to include role attribute.

Added role="img" to SVG images. (uswds/uswds#3501)

https://designsystem.digital.gov/about/releases/#version-271

Examples updated in: a67fff0

This will require corresponding markup changes in consuming projects at time of upgrade. As a general accessibility best-practice, it could be implemented independently from the LGDS upgrade in consuming projects.

aduth · 2020-10-15T14:56:17Z

Marking this as ready for review, since all necessary changes from upgrades should be accounted for.

Preview on Federalist: https://federalist-2f194a10-945e-4413-be01-46ca6dae5358.app.cloud.gov/preview/18f/identity-style-guide/aduth-uswds-upgrade/

I'm planning to include a CHANGELOG.md file to help document some of the above-noted required changes for consuming projects.

Also noting: The build failure for ci/circleci: visual-regression is expected, as described in above "Acknowledged and expected change" notes and by visual regression tests documentation.

aduth · 2020-10-16T12:21:52Z

⚠️ Requires markup changes at time of upgrade in dependent projects ⚠️

USWDS 2.8.0 updates markup of the "official government website" banner.

https://designsystem.digital.gov/about/releases/#version-280

Updated in documentation site in: 029b089

This will require corresponding markup changes in consuming projects at time of upgrade.

zachmargolis

LGTM, looks like there is a visual regression in the accordion but it looks like mostly padding and I'm OK with it if you are

zachmargolis · 2020-11-16T21:58:51Z

src/scss/uswds-theme/_color.scss

-$theme-color-disabled:         'site-disabled-grey';
-$theme-color-disabled-dark:    'site-darker-grey';
+// TODO: Revert back to `map-get` once https://github.com/uswds/uswds/pull/3762 is released.
+$theme-color-disabled-light:   'gray-5'; // map-get($site-palette, 'site-lightest-grey');


should we standardize on gray vs grey? (looking at $theme-color-disabled-family above). My inclination is to use gray because that's standard for US English?

should we standardize on gray vs grey? (looking at $theme-color-disabled-family above). My inclination is to use gray because that's standard for US English?

tl;dr: I think so, yes.

It might be worth getting broader UX feedback here, but it kinda seems like the whole set of $theme-color-grey variables should be eliminated altogether. At least comparing to the base USWDS theme color tokens, I don't see any reference to where grey originates from. Grays appear to fit within the "base" family, and we only reference grey under the base colors in our own color guide.

It may make sense to keep our own $site-palette, but considering that USWDS spells it as gray in their own system tokens, I agree it'd make sense to align it.

In the short-term though, I'm a bit wary to include it here, since it has some cascading effects, but in terms of making breaking changes in one pass, it could be wise to do before publishing a version of this package that contains USWDS 2.9.0.

aduth · 2020-11-17T15:45:33Z

visual regression in the accordion but it looks like mostly padding and I'm OK with it if you are

Yeah, the prior comments worked to mitigate most of the major differences, but the remaining diff is attributed to a new line height calculation that's expected (#159 (comment)).

See: https://designsystem.digital.gov/about/releases/#version-220

Avoid duplicate overflow, allow margins to collapse as before

See: https://designsystem.digital.gov/about/releases/#version-250

**Why:** Two elements may have this class, and only one should have overflow applied.

See: https://designsystem.digital.gov/about/releases/#version-260

See: https://designsystem.digital.gov/about/releases/#version-270

See: https://designsystem.digital.gov/about/releases/#version-271

See: https://designsystem.digital.gov/about/releases/#version-280

aduth · 2020-11-17T20:58:27Z

Couple more findings that will need reconciliation:

USWDS 2.8.0 includes a new Tooltip component, which conflicts with our custom component (live site, branch preview, USWDS component)
- Suggestion: Remove our custom implementation, defer to USWDS, include note in CHANGELOG describing markup differences for upgrade.
USWDS 2.8.0 includes new Date Picker and Date Range Picker components. While these don't conflict with our date input component recommendation since the three-field input is still included in USWDS, there may need to be additional consideration if and how we propose to leverage these two new components.
- Suggestion: Leave as-is for now.

aduth · 2020-11-17T21:06:57Z

USWDS 2.8.0 includes a new Tooltip component, which conflicts with our custom component (live site, branch preview, USWDS component)

Suggestion: Remove our custom implementation, defer to USWDS, include note in CHANGELOG describing markup differences for upgrade.

As far as impact is concerned, a naive search appears to reveal that we don't use it anywhere:

https://github.com/search?l=&q=usa-tooltip+user%3A18f&type=code

I can still document the change all the same.

**Why**: Clear up console warnings on build

aduth · 2020-11-27T14:59:15Z

Chatted with @nickttng on Slack regarding the notes in #159 (comment):

For Date Picker and Date Range Picker components, we're in agreement to consider this if and when they become relevant for us to use and customize.
For Tooltip, given the fact that we don't currently use it anywhere, it seems reasonable to remove this for now to allow us to move forward with a release. If we discover a need for tooltips in the future, we can investigate how best to reconcile our guidance with USWDS'.

aduth · 2020-11-27T15:10:28Z

Another discovery I'd made is that USWDS introduces a Card component in Version 2.7.0. While there are some visual similarities to the LGDS Card component, the usage guidance is not quite the same, where the USWDS discourages standalone usage of a card.

While it's an unfortunate naming collision, the implementation of the LGDS card using custom lg--based classes means there should not be concern for conflicts in code. Thus, we can upgrade to the latest USWDS without concern for unexpected breakage. Technically, there's nothing to stop a developer from using both or either of lg-card and usa-card.

Recommendation: No action for now. In the future, consider how to reconcile where reconciliation could be one of (a) removing our card implementation in favor of USWDS, (b) renaming our card component if it should be distinct from USWDS card component, or (c) merge implementation and document guidance for different usage if desired to build upon USWDS card.

Note that future revisions or removal of this component should consider impact to dependent applications, where it is currently used in 18f/identity-dashboard and a test route in identity-idp (see search results).

juliaelman

Excellent work @aduth! 🚀

This was referenced Oct 13, 2020

Add basic visual regression testing #158

Merged

Reference "disabled-light" color by token name in File Input styles uswds/uswds#3762

Merged

Base automatically changed from aduth-visual-regression to master October 14, 2020 16:56

aduth force-pushed the aduth-uswds-upgrade branch from 72b1849 to 3010e82 Compare October 14, 2020 16:57

aduth marked this pull request as ready for review October 15, 2020 14:56

aduth mentioned this pull request Oct 19, 2020

Update all Node dependencies, remove unused #162

Merged

aduth force-pushed the aduth-uswds-upgrade branch from edd78fb to 191a314 Compare October 19, 2020 15:26

aduth added the needs: ready for review This pull request is ready to be looked at by any team member (especially those tagged as reviewers) label Oct 19, 2020

aduth mentioned this pull request Oct 21, 2020

Wrap document capture error message at bounds of file input 18F/identity-idp#4324

Merged

its-a-lisa-at-work added this to Reviewed Required in TTS Tech Portfolio (Pull Requests) via automation Oct 22, 2020

its-a-lisa-at-work removed this from Reviewed Required in TTS Tech Portfolio (Pull Requests) Oct 23, 2020

juliaelman self-requested a review October 29, 2020 14:36

aduth mentioned this pull request Nov 16, 2020

LG-3757: Create bundler-ready module entrypoint #165

Merged

zachmargolis approved these changes Nov 16, 2020

View reviewed changes

aduth added 2 commits November 17, 2020 15:23

Upgrade USWDS to 2.9.0

413b62b

Reconcile banner changes from USWDS upgrade

1b10c9b

aduth added 11 commits November 17, 2020 15:23

Add overflow to highlighted code segments

1599221

Update deprecated header settings value

387e82a

See: https://designsystem.digital.gov/about/releases/#version-220

Fix light disabled grey color

5039b28

Apply overflow specific to pre element

d48e676

Avoid duplicate overflow, allow margins to collapse as before

Improve markup accessibility per revisions in USWDS 2.5.0

1ba1404

See: https://designsystem.digital.gov/about/releases/#version-250

Ignore qualified lint error

490226f

**Why:** Two elements may have this class, and only one should have overflow applied.

Update search markup per USWDS 2.6.0

a01b37b

See: https://designsystem.digital.gov/about/releases/#version-260

Update numeric field guidance per USWDS 2.7.0

bcd20e1

See: https://designsystem.digital.gov/about/releases/#version-270

Add role attribute to SVG images per revisions in USWDS 2.7.1

e3a79bc

See: https://designsystem.digital.gov/about/releases/#version-271

Add expected TODO

211967d

Add CHANGELOG.md

6714335

aduth force-pushed the aduth-uswds-upgrade branch from 191a314 to fd300a6 Compare November 17, 2020 20:28

aduth added 3 commits November 17, 2020 15:29

Update banner text per USWDS 2.8.0

668a731

See: https://designsystem.digital.gov/about/releases/#version-280

Fix mobile expanded banner background color

be2d5b8

Update link color of mobile banner button

67ddf89

aduth force-pushed the aduth-uswds-upgrade branch from fd300a6 to 67ddf89 Compare November 17, 2020 20:29

aduth added 2 commits November 17, 2020 16:17

Remove Tooltip component

85b1f3b

NPM audit fix

8c2503a

**Why**: Clear up console warnings on build

juliaelman approved these changes Nov 30, 2020

View reviewed changes

aduth merged commit 64b6f69 into master Nov 30, 2020

aduth deleted the aduth-uswds-upgrade branch November 30, 2020 18:14

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

LG-3187: Upgrade USWDS to 2.9.0 #159

LG-3187: Upgrade USWDS to 2.9.0 #159

aduth commented Oct 13, 2020 •

edited

aduth commented Oct 13, 2020 •

edited

aduth commented Oct 14, 2020 •

edited

aduth commented Oct 14, 2020 •

edited

aduth commented Oct 14, 2020

aduth commented Oct 15, 2020

aduth commented Oct 15, 2020

aduth commented Oct 15, 2020

aduth commented Oct 15, 2020

aduth commented Oct 15, 2020

aduth commented Oct 15, 2020

aduth commented Oct 15, 2020

aduth commented Oct 15, 2020 •

edited

aduth commented Oct 16, 2020 •

edited

zachmargolis left a comment

zachmargolis Nov 16, 2020

aduth Nov 17, 2020

aduth commented Nov 17, 2020

aduth commented Nov 17, 2020 •

edited

aduth commented Nov 17, 2020

aduth commented Nov 27, 2020

aduth commented Nov 27, 2020

juliaelman left a comment

LG-3187: Upgrade USWDS to 2.9.0 #159

LG-3187: Upgrade USWDS to 2.9.0 #159

Conversation

aduth commented Oct 13, 2020 • edited

aduth commented Oct 13, 2020 • edited

aduth commented Oct 14, 2020 • edited

aduth commented Oct 14, 2020 • edited

aduth commented Oct 14, 2020

aduth commented Oct 15, 2020

aduth commented Oct 15, 2020

aduth commented Oct 15, 2020

aduth commented Oct 15, 2020

aduth commented Oct 15, 2020

aduth commented Oct 15, 2020

aduth commented Oct 15, 2020

aduth commented Oct 15, 2020 • edited

aduth commented Oct 16, 2020 • edited

zachmargolis left a comment

Choose a reason for hiding this comment

zachmargolis Nov 16, 2020

Choose a reason for hiding this comment

aduth Nov 17, 2020

Choose a reason for hiding this comment

aduth commented Nov 17, 2020

aduth commented Nov 17, 2020 • edited

aduth commented Nov 17, 2020

aduth commented Nov 27, 2020

aduth commented Nov 27, 2020

juliaelman left a comment

Choose a reason for hiding this comment

aduth commented Oct 13, 2020 •

edited

aduth commented Oct 13, 2020 •

edited

aduth commented Oct 14, 2020 •

edited

aduth commented Oct 14, 2020 •

edited

aduth commented Oct 15, 2020 •

edited

aduth commented Oct 16, 2020 •

edited

aduth commented Nov 17, 2020 •

edited