Improvements to migration guidance #1583
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
thisisdano
commented
May 4, 2022
Comment on lines
94
to
+102
| - name: "margin" | ||
| base: "margin-" | ||
| defaultSize: 47.9 | ||
| defaultSize: 4.35 | ||
| - name: "margin-horizontal" | ||
| base: "margin-" | ||
| defaultSize: 21.75 | ||
| - name: "margin-vertical" | ||
| base: "margin-" | ||
| defaultSize: 21.75 |
There was a problem hiding this comment.
Added new margin modules. margin is a quirky module that has -horizontal and -vertical options as well.
Comment on lines
+10
to
+13
| - text: Using USWDS CSS and JavaScript in your project | ||
| href: '#using-uswds-css-and-javascript-in-your-project' | ||
| - text: Compiling USWDS Sass into CSS | ||
| href: '#compiling-uswds-sass-into-css' |
There was a problem hiding this comment.
Updated the sidenav to match the new structure of the README
| - text: Need installation help? | ||
| href: '#need-installation-help' | ||
| - text: Contributing | ||
| href: '#contributing-to-the-code-base' | ||
| --- | ||
|
|
||
| {% assign content = site.data.install-readme.decoded | markdownify | absolutify_links: 'https://github.com/uswds/uswds/blob/release-2.0/' | split: '<h2 id="using-the-design-system">Using the design system</h2>' | last | split: '<h2 id="reuse-of-open-source-style-guides">' | first %} | ||
| {% assign content = site.data.install-readme.decoded | markdownify | absolutify_links: 'https://github.com/uswds/uswds/blob/release-2.0/' | split: '<h2 id="installing-the-design-system">Installing the design system</h2>' | last | split: '<h2 id="reuse-of-open-source-style-guides">' | first %} |
There was a problem hiding this comment.
Fixed the README import to match the new format of the README.
| - const sass = require("gulp-sass"); | ||
| + const sass = require("gulp-sass")(require("sass")); | ||
| {%- endhighlight %} | ||
| </li> |
There was a problem hiding this comment.
Added some more steps to outline how sass and gulp-sass need to be updated to compile our Sass properly
| <li>Update the USWDS <code>const</code> elements to the updated USWDS package location: | ||
| {% highlight diff -%} | ||
| - const pkg = require("./node_modules/uswds/package.json"); | ||
| + const pkg = require("./node_modules/@uswds/uswds/package.json"); | ||
| ... | ||
| - const uswds = require("./node_modules/uswds-gulp/config/uswds"); | ||
| + const uswds = "node_modules/@uswds/uswds"; | ||
| + const uswds = "./node_modules/@uswds/uswds"; |
There was a problem hiding this comment.
Use ./ consistently throughout
Comment on lines
+515
to
+516
| 1. Check your settings to see if they are set to either the **old** or the **new** default. | ||
| 1. If they use either the **old** or the **new** default, delete the setting from your settings file so it uses the system default. |
There was a problem hiding this comment.
Delete the setting if it uses the old value or the new value.
| @@ -512,7 +533,7 @@ Setting | Old default | New default | |||
| We deprecated the `$theme-site-max-width` variable. We're using `$theme-grid-container-max-width` instead. | |||
|
|
|||
| ###### What to do | |||
| 1. Replace instances of `$theme-site-max-width` with `$theme-grid-container-max-width` | |||
| 1. Replace instances of `$theme-site-max-width` with `$theme-grid-container-max-width`. If your layout is affected by this change, remove this setting from your settings file. | |||
There was a problem hiding this comment.
Add a note about checking to see if there are any regressions after replacing this setting
| @@ -829,7 +850,7 @@ Using individual component packages instead of the `uswds` bundle package can re | |||
|
|
|||
| 2. **Determine which packages your project needs.** The process of determining which packages your project needs is not automatic. Most projects will need to do a little work to identify the components their project uses. | |||
|
|
|||
| A brute-force method to determine which packages your project uses is to search your codebase for use of a key class name associated with that component, like `usa-accordion` for accordions. All `usa-` prefixed packages use the same name as their CSS class. For reference, all the available packages in USWDS 3.0 are listed in the [table below](#available-packages). | |||
| A brute-force method to determine which packages your project uses is to search your codebase for use of a key class name associated with that component, like `usa-accordion` for accordions. All `usa-` prefixed packages use the same name as their CSS class. For reference, all the available packages in USWDS 3.0 are listed in the [table below](#available-packages). Search package-by-package for instances of the package or search your codebase for instances of `usa-` and make a running list of all the packages you use. | |||
There was a problem hiding this comment.
Add a hint about package usage and identification
| @@ -844,7 +865,9 @@ Using individual component packages instead of the `uswds` bundle package can re | |||
|
|
|||
| Each package is smart enough to include any dependent package it needs to display properly. | |||
|
|
|||
| 4. **Remove your reference to the uswds bundle package.** Once all of your project's component packages are loaded, you can safely remove the `uswds` package reference from your entry point. | |||
| 4. Many projects will need to use the utilities package (`uswds-utilities`) and the global package (`uswds-global`). If your site uses utilities, be sure to include the utilites package. The global package includes normalize. If you compile your styles and see improper spacing around many elements (like around the perimeter of the page), be sure to include `uswds-global`. | |||
There was a problem hiding this comment.
Add a note about using the utilities package and the global package
| @@ -933,7 +956,7 @@ $theme-utility-breakpoints: ( | |||
| ), | |||
| ``` | |||
|
|
|||
| For each breakpoint set to true in your project, search for its usage in your codebase by searching for the **breakpoint name** + a colon (`:`). SO, to search for the `tablet-lg` breakpoint, search for `tablet-lg:`. If that breakpoint does not appear, you can set the value to `false`. | |||
| For each breakpoint set to true in your project, search for its usage in your codebase by searching for the **breakpoint name** + a colon (`:`). So, to search for the `tablet-lg` breakpoint, search for `tablet-lg:`. If that breakpoint does not appear, you can set the value to `false`. | |||
mejiaj
approved these changes
May 4, 2022
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
I've made some improvements to the migration guidance based on my experience migrating to USWDS 3.0 on the Public Sans website. Changes outlined in the comments.