USWDS-Site: Phase two compile updates #1766
Conversation
|
|
||
| ## Step 4: Create path settings and export compile functions | ||
| Now, create your path settings using the following table: | ||
| ### Step 4: Customize path settings |
There was a problem hiding this comment.
Added detail to explain what the path settings are for and examples that show how a user might want to customize
| exports.watch = uswds.watch; | ||
| ``` | ||
|
|
||
| ### Step 3: Set USWDS version |
There was a problem hiding this comment.
Added this step to highlight the need for setting the USWDS version, as well as describe which values are available.
There was a problem hiding this comment.
This is AMAZING and I think the improvements are really concrete.
I reviewed this for clarity, plain language (within reason). The main changes I've suggested are making sure to link to relevant documentation when there's a lot to know or unpack behind a seemingly simple step (like "load uswds settings"), but I absolutely defer to your knowledge of their knowledge.
|
|
||
| A project often has many Sass files, but typically, there’s a single file that serves as the root — the “homepage” of the Sass — that links out to the others. This root file is also known as the “Sass entry point.” The Sass entry point is the most important stylesheet file in your project because it tells the compiler what source files make up your Sass codebase. | ||
| When your entry point is ready, you'll need to load USWDS Sass. Your Sass entry point will need to do the following three tasks in this order: |
There was a problem hiding this comment.
Is there a link to USWDS Sass or an explanation of how to do this that we could link to?
There was a problem hiding this comment.
I have added some language ("For your entry point to complete these tasks") immediately after these tasks are identified to help transition the user. Let me know if you think it needs more.
I am also wondering if USWDS Sass sounds a bit like its own product, rather than just referring to the Sass files inside USWDS. Do you see this too?
|
@bonnieAcameron made some updates:
Let me know if you have thoughts! |
|
@mejiaj We are working through some restructuring of the Phase 2 compile page. Will you take a look and let us know what you think? |
|
|
||
| After you import the USWDS source code, you can build new styles with USWDS design tokens, functions, and mixins. For the purposes of this guide, we won’t get into custom code, but the important thing to understand is that any custom code should follow the settings and USWDS source code in your Sass entry point. | ||
| After you've loaded the USWDS source code, you can build new styles with USWDS design tokens, functions, and mixins. For the purposes of this guide, we won’t get into custom code, but the important thing to understand is that any custom code should follow the settings and USWDS source code in your Sass entry point. |
There was a problem hiding this comment.
What if they did want to get into "custom code," is there a resource for that that we could add?
Summary
Restructured the content in Phase 2 of the Getting Started for Developers guide to add clarity.
Related issue
Closes #1708
Recommend releasing this update with the settings page update in PR #1755
Preview link
Preview link: Phase 2 Compile
Problem statement
The guide for compiling USWDS Sass should give clear instructions for both users who want to use
uswds-compileto create their Sass, and those who want to manage their own Sass compilation. However, the current page creates a single set of steps for both processes. Additionally, the instructions foruswds-compilecan be confusing if the user is not very familiar with Sass compilation.Solution
By separating out the sections and adding clear headers, we can help the user understand which steps they need to take for their project. Additionally, adding more information about setting up the
gulpfile.jsforuswds-compilewill help give users a clear step-by-step process to get up and running.Testing and review
For copyeditors:
For developers: