Clarify When to Extend vs. Use Existing Classes (and Document Best Practices for Overriding)

[mejiaj]

Overview

There’s confusion about when to extend USWDS (U.S. Web Design System) with new styles or components, versus using existing USWDS classes. Sometimes, team members start custom work only to find out later that USWDS already offers a solution. This leads to duplicated effort and inconsistent code.

Why This Matters

• Reduces redundant custom code and maintenance.
• Promotes consistency and reliability in our UI.
• Saves time for both engineers and designers.
• Makes onboarding and handoff easier.

Ideas

• Decision Guide: Create a simple guide or flowchart for “Should I extend USWDS or use what’s there?”
• Best Practices: Document clear best practices for:
  • When and how to extend USWDS (add/override classes, tokens, etc.)
  • When to avoid overriding or duplicating USWDS classes
  • Customizing tokens, colors, or components (adding your own icons, etc.).
• Examples: Add real-world examples of:
  • Using USWDS out-of-the-box vs. extending it
  • Common pitfalls (e.g., redundant custom classes)
• Reference: Link to USWDS docs and existing project code where possible
• Checklist: Provide a checklist for engineers/designers to review before starting custom work

Helpful Context / Suggestions

• There have been several cases where team members built new styles or components, only to discover later that USWDS already had a class or pattern for that need.
• We should cover:
  • How to search/check USWDS docs before starting new work
  • The process for proposing an extension (when needed)
  • How to document overrides so others know what’s custom
• Consider a quick “before you start” checklist:
  • Did you check the USWDS documentation?
  • Is there an existing class/component that meets your need?
  • If you’re extending, is it for a valid use case (not just preference)?
  • Are you documenting your extension/override clearly?

Goal:
Make it easy for engineers and designers to know when and how to extend USWDS, and avoid unnecessary custom code.