USWDS-Proposals - ADR: Improve modularity in USWDS #24
+68
−0
There are no files selected for viewing
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
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -0,0 +1,68 @@ | ||||||
| <!-- | ||||||
| The record number and the title should be in the filename. | ||||||
| For example: | ||||||
| /decisions/0000-adr-title.md | ||||||
| --> | ||||||
|
|
||||||
| <!-- | ||||||
| PR Title: | ||||||
| ADR Proposal: A brief description | ||||||
| --> | ||||||
|
|
||||||
| # 6. Improve modularity in USWDS | ||||||
|
|
||||||
| | Date | Status | | ||||||
| | ---------- | -------- | | ||||||
| | 2024-12-19 | Proposed | | ||||||
|
|
||||||
| <!-- | ||||||
| Status options: | ||||||
| - Draft | ||||||
| - Proposed | ||||||
| - Approved | ||||||
| - Rejected | ||||||
| - Deprecated | ||||||
| - Superseded | ||||||
| --> | ||||||
|
|
||||||
| ## Context | ||||||
|
|
||||||
| USWDS is becoming a set of products, in the form of tools and targets. To improve performance and provide flexibility to teams we should make USWDS more modular by offering products such as: | ||||||
|
There was a problem hiding this comment.
Suggested change
|
||||||
|
|
||||||
| - USWDS Core (our current HTML/CSS with SASS variables, mixins, functions) | ||||||
| - USWDS Elements (a new HTML Web Components-based version of USWDS Core) | ||||||
| - USWDS Utilities | ||||||
| - USWDS Components | ||||||
| - USWDS Tokens | ||||||
| - USWDS design kit | ||||||
|
|
||||||
| ## Decision | ||||||
|
|
||||||
| We'll create additional products and resources that teams can use individually, such as: utilities, tokens, SASS helpers, and HTML components. | ||||||
|
There was a problem hiding this comment.
Suggested change
|
||||||
|
|
||||||
| ### Alternatives | ||||||
|
|
||||||
| Staying on the monolithic repo. This has proven difficult to maintain both centrally and for teams that implement the system, increases dependencies, and doesn't allow us to quickly make changes and ship features. | ||||||
|
|
||||||
| ## Consequences | ||||||
|
|
||||||
| ### Benefits | ||||||
|
There was a problem hiding this comment. suggestion: may be good to explicitly call out performance and bundle size, since the hope is that increasing modularity will make it easier to make each package as small as possible There was a problem hiding this comment. @heymatthenry good idea. Tried to capture in f5e50e8. |
||||||
|
|
||||||
| - This improves reusability for all teams. For example, we can use tokens in both USWDS Core and Elements repo. Other teams will also be able to use tokens for their custom products. | ||||||
| - Increased modularity will improve overall performance and reduce bundle size. | ||||||
| - Teams will be able to prototype quicker with utilities without having to compile SASS. | ||||||
| - This allows teams to choose among these products, or even choose portions within these products, considering the tradeoffs that might come with each. This interchangeability can lead to reduced maintenance time and costs, simplify code dependencies, and/or allow further flexibility. | ||||||
| - Teams will be able to make USWDS product choices that will make their work easier to get started and stay up to date. | ||||||
| - USWDS Core team will be able to test code and manage dependencies more easily. | ||||||
| - USWDS Core team will be able to ship features faster, with less risk of downstream breaks. | ||||||
|
|
||||||
| ### Risks | ||||||
|
|
||||||
| - Teams may be unsure which products to use, or how to use them together. | ||||||
| - USWDS Core team will have additional overhead maintaining many more products, including documentation and testing. | ||||||
| - USWDS Core team will need to take extra care to make sure there aren't interdependence issues or conflicts with new code. | ||||||
|
|
||||||
| ## Supporting information | ||||||
|
|
||||||
| - This decision was driven by significant research in 2024. | ||||||
| - A cross-agency working group which includes teams and individuals from VA, SSA, DHS, IRS, and NIH, among others, provided feedback. | ||||||
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
chore: Update status before merge.