Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Introduce USWDS theming and upgrade to USWDS 3.8. #1425

Merged
merged 3 commits into from
May 23, 2024

Conversation

sanason
Copy link
Member

@sanason sanason commented May 23, 2024

This PR does 2 things:

  1. Updates the version of USWDS we are using from 3.6.1 to 3.8. This will give us access to a new sticky table header feature which we can use for https://trello.com/c/7f3i1ylK/79-when-a-table-is-longer-than-viewport-table-header-row-stays-visible-on-scroll.
  2. Adopts a somewhat more formal procedure for upgrading and customizing USWDS in our project (documented in the README).

Number 2 is just a proposal, from a brand new member of the team who has no context on why things are done the way they are done so, reviewers, feel free to criticize. That said, I think the new procedure offers these benefits:

  • Clearer documentation of which USWDS version we are on (since it's now recorded in package.json).
  • Single automated command that ensures that all updated assets are copied to the right place (gulp updateUswds).
  • Follows the "approved" approach for customizing USWDS (by adjusting the settings provided by the framework) which makes our customizations less likely to break when USWDS is updated. (Note that this PR only takes one tiny step in this direction.)

Testing

Did the upgrade to 3.8 break anything in the Touchpoints app? Did the upgrade to 3.8 break anything in the display of questionnaire forms?

No changes that I can see. The only breaking change listed (in 3.8) concerns the class usa-layout-docs__sidenav which, as far as I can tell, we aren't really using.

Do our tables look the same after using the theme-table-border-color setting to customize their appearance?

Yes, borders look the same.

@@ -251,21 +251,6 @@ tbody tr:hover td {
text-decoration: none;
}

.usa-table {
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These overrides were replaced by setting $theme-table-border-color in uswds/_uswds-theme.scss.

@@ -10,7 +10,7 @@
* files in this directory. Styles in this file should be added after the last require_* statement.
* It is generally better to create a new file per style scope.
*
*= require uswds
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Renamed because I couldn't figure out a way to get the USWDS compiler to generate the file with its original name.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wish this was not minified but that's how the USWDS compiler operates. There is a feature request in uswds-compile asking to make minification optional. Admittedly, that is a very old feature request and the project hasn't had a release for a long time but I could ask about it.

@sanason sanason marked this pull request as ready for review May 23, 2024 17:56
@sanason
Copy link
Member Author

sanason commented May 23, 2024

Follows the "approved" approach for customizing USWDS (by adjusting the settings provided by the framework) which makes our customizations less likely to break when USWDS is updated.

Here's an example of customizations being broken:
Originally, I upgraded to 3.8 simply by copying over the new versions of uswds.js and uswds.css. Then I added the new class usa-table--sticky-header to the list-of-forms table and got this result:
Screenshot 2024-05-23 at 3 24 40 PM
The new class added a border to the table and, since we weren't setting theme-table-border-color, we ended up with a black border.

@sanason sanason requested a review from ryanwoldatwork May 23, 2024 20:36
Copy link
Contributor

@ryanwoldatwork ryanwoldatwork left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@sanason - thank you!

this is looking good and accomplishes:

  • a better uswds build process
  • minified versions of the assets are in place
  • updated assets (icons)
  • kept style customizations
  • removed old, non-minified assets

@ryanwoldatwork ryanwoldatwork merged commit 78dadf9 into develop May 23, 2024
5 checks passed
@sanason sanason deleted the upgrade-to-uswds-3.8 branch August 14, 2024 18:51
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants