Caseflow: USWDS upgrade

[mdbenjam]

Time-boxed exploration of trying to upgrade to the latest USWDS. Currently we use an outdated USWDS gem that hasn't been updated in 2 years. We should see if we can import the NPM package directly, instead of through the gem so that we can receive regular updates. Let's keep this exploration to two days and see what happens. After that time, when we understand the difficulties of migrating, we can make a decision on which way to go.

[nolawi]

USWDS update and Use NPM

Broken the level of effort needed to upgrade USWDS into four parts. (Difficulty 1-5)

1. USWDS package via NPM in FE (3)

• Attempted to import and run the package in the client side using webpack and add styles to load on all pages. Breaks UI in some pages, and some style guide components like table, accordion, and navigation header.

• We will also need to explore adding some kind of style linter.

2. Remove Outdated Gem in Caseflow (4)

There was two issues here I found.

• Caseflow commons has outdated USWDS gem as a dependency also.
  and it needs the USWDS gem also installed for it to run in caseflow. I didn’t explore this much.

_caseflow-commons gem can not be used with out also importing USWDS gem_

• There are non style issues in some global components. Javascript errors rendering some components, including ones imported from caseflow-frontend toolkit

3. Remove Gem as a Dependency from caseflow-commons(2)

There are style mixing and variables that caseflow common needs to work independently, this would essentially mean removing imported USWD style overrides.

_Consider deprecating Casflow-commons_
Most of styles can just be imported directly in the sass file or just adding it local to our project and eventually removing most of these styles because we are moving in the direction of inline javascript styles.

4. Styleguide (4)

All of styleguide does not render at all without USWDS. We should consider react based library like Storybook or pattern lab - easy to manage as we move to inline Javascript styled component.

Proposal

Although every step will require some kind of visual regression test for UI in steps 3-4, this can be done. (LOE 4 = full sprint)

1. Deprecate caseflow-commons, move styles into caseflow. (2)
2. Build infastructure to import and compile styles via npm package. (2)
3. Add USWDS in the frontend while keeping GEM. Remove style conflict and fix javascript component conflict, (4)
4. Remove USWDS gem. At this point we will know more - ‘there are unknown unknowns' (3)
5. Consider what to do with styleguide(?)

[mdbenjam]

Some questions:

and it needs the USWDS gem also installed for it to run in caseflow. I didn’t explore this much.

When you say it needs the USWDS gem installed, what does that mean. Aren't we just using this as a conduit for including USWDS? If we install it via NPM don't we get the same thing?

There are non style issues in some global components. Javascript errors rendering some components, including ones imported from caseflow-frontend toolkit

What do non-style issues look like? Do you have some examples?

this would essentially mean removing imported USWD style overrides.

You may not know this, but why did we decide to override so many USWDS?

All of styleguide does not render at all without USWDS

If we pull in USWDS from NPM, doesn't it still have access to those styles?

[nolawi]

1. caseflow-commons gem can not be used with out also importing USWDS gem, Its not just a not a conduit for USWDS. Essentially we are importing USWDS gem twice, one as a dependency of caseflow commons with some overrides and global caseflow styles. I didn't explore installing commons via NPM. I am hoping we do not have a need for caseflow-commons.

2. Non style issues include a lot of javascript console errors. But mostly its that click interactions like accordion, dropdown does not work, having to do with updated behaviors
   compared to old

3. In regards USWDS style overrides, from what it looks like we built our own grid styles as opposed to relying what USWDS has. This may or may not have been there 2 years ago.

4. If we pull in USWDS from NPM styleguide also has access to new styles but styleguide container UI is broken. Display issues, nothing is floating correctly mostly having to do with container styles

[mdbenjam]

I was just talking with Sunil and he had an interesting suggestion. What if we try to bring in the same version of USWDS that we are currently using in gem form? Then we can upgrade at a later point. We still get the advantage of cleaning up how we include css, and make upgrading later easier.

[mkhandekar]

Hi team (+ @department-of-veterans-affairs/caseflow-designers)

1. What will this USWDS upgrade impact?

2. Will it update our UI styles, and how can we get prepared for the changes?

3. Can someone speak to the background context/rationale for overriding things like USWDS grids? Where else do we have overrides?

[mdbenjam]

1) Not sure yet all the things that updating USWDS will impact. Nolawi outlined some things, but there are likely many more that will be affected.

2) It will update our styles, we haven't explored yet how to prepare for it.

3) I'm not sure why we had overrides for a lot of these styles. @shanear might have a better sense.

[nolawi]

@mdbenjam @mkhandekar Not a lot of override styles but some.. the deviation from the styleguide is not significant. Although it exist

[nolawi]

Status

1. PR removing styles from commons(done)
2. PR with styles in caseflow (done)
3. PR ..feedback (done)
   4 PR ..efloder (inprogress)

Once all four done, will merge with master together. @mdbenjam

[nolawi]

Updates

Now that we have cleaned up some of styles issues; went ahead and attempted to use the latest version of USWDS styles, and it still seems to be backward compatible enough that we should consider jumping into the latest release v1.6.3. We were on v0.10, which is over 2 years old.

I am still auditing, there are a few components that look somewhat different: You can walk through the latest updates here

Buttons

Before

After upgrade

Tabs

Before

After

Headline fonts

Fonts appear to be slightly bigger, will be noticeable but not significant enough to worry about.

Focus

Almost everything in focus will have dotted line

[mkhandekar]

@nolawi Overall, awesome! Couple small comments, as I compare these changes to the current USWDS components:

1. I don't see any horizontal tabs in USWDS -- am I just not seeing them?

2. Also, doesn't the USWDS use Source Sans Pro (almost) everywhere? The screenshots above have what looks like Helvetica or another sans serif font. Not saying this need to change - just checking.

3. It would be nice to get a full walkthrough (in person / video chat with the team) to see what's been changed and where!

[nolawi]

@mkhandekar
1, Some components are created _by us for us_. Global styles will overwrite some features of the tabs.
2, True, but still exists. See some of the changes here Essentially they make use of Source sans less.
3, Absolutely I can do a full demo for those that are interested, at somepoint.

[nolawi]

Update

My attempt to import node modules directly into the asset-pipeline hit a bit of a snag. The USWDS package has to be built and served by webpack this way all the dependencies attached.

Attempting that approach now.

Resolving path. https://github.com/uswds/uswds#set-the-base-asset-path-fonts-and-images

[nolawi]

Related to the issue we are having

Essentially there is an updated https://github.com/jgarber623/uswds-rails rails gem we can use instead. If we can't resolve the issues via npm package.