USWDS-Tutorial: Extending USWDS

[mejiaj]

For March 2024 Monthly Call.

How to customize and extend USWDS. Teach how to build new components that look and feel consistent with existing components.

Requirements

• Work with design system settings
• Apply tokens consistently with Sass functions and mixins
• Avoid style conflicts when overriding defaults
• Use tools for ensuring proper color contrast in every context

Original in event brief

Tasks

The full exercise (Pt. 1 completed) will be on a separate branch. The steps to follow will later be added to main so users can follow both parts.

Setup

• Update NVMRC to latest LTS
• Complete tutorial steps
• Update link to step two instructions (updated from/build to /extend. Might not be needed for the monthly call) Fixed in Extend: Update hero copy & links #33
• Add getting started instructions from clean setup
• USWDS-Site: Document color setting mixins uswds-site#2541
• USWDS-Tutorial: Run watch task on start #35 [Follow up work]
• Remove unnecessary files/code for demo

Exercises

• Identify and create two exercises to show how users can build with USWDS
• Create a new page for exercises
• Create a new layout for exercises
• Add initial exercise code
• Change permalink to extending. Done in 938aee0.

Intro

• Update hero text & buttons fixed in Extend: Update hero copy & links #33.

Exercise 1

• Ensure public sans is default sans font at this point (should have came from part one of the tutorial) - Confirmed
• Update segue - fixed in March MC - Instructions: Finish structure and add all instructions #36
• Update button color in theme settings

Exercise 2

• Add instruction about custom class to the top @mahoneycm
• Add instructions to add /components/ scss dir - fixed in March MC - Instructions: Finish structure and add all instructions #36
• Move note about completing part one before moving to the extending tutorial - fixed in March MC - Instructions: Finish structure and add all instructions #36
• Replace filler instructions (step 4) - fixed in March MC - Instructions: Finish structure and add all instructions #36
• Create segue fixed in March MC - Instructions: Finish structure and add all instructions #36
• Finalize theme settings

Exercise 3

• Create section for instructions - added in March MC - Instructions: Finish structure and add all instructions #36
  • Add new testimonial include under ut-card include
• Demo testimonial component March MC - Exercise 3: Standalone testimonial #32
  • Use usa-card as a reference for people who want to build a similar component

[mahoneycm]

Reverting setup steps

Because users are expected to complete the setup steps (besides the NVMRC update) during the first part of the exercise, we should revert these changes as to not mess up the first part of the tutorial.

I created a branch and draft PR with the entire first part of the tutorial complete that we can use as a testing branch for where this tutorial should pick up.

[mejiaj]

Closing as done with #25 and #40.