How to use USWDS
USWDS maturity model
Use the USWDS maturity model to adopt the design system incrementally and design and build better digital experiences.
You don’t need to adopt the design system all at once.
Adopt the design system incrementally through the levels of the USWDS maturity model. Your project can progress both through higher levels of maturity and with more comprehensive maturity at each level. Most importantly, using the design system is about integrating the USWDS Design Principles, common goals that align teams across government and serve as an evaluative lens for design and implementation decisions.
As you adopt and adapt the design system, be sure to contribute back to the system. Use the USWDS GitHub page to:
- Report problems or bugs
- Contribute new research or guidance
- Propose new components
Level 1: Integrate design principles
USWDS Design Principles support and reflect the important guidance codified in the 21st Century Integrated Digital Experience Act. These design principles are intended to help teams across government align on important common goals and better use the design system — to be an evaluative lens for design and implementation decisions.
Start with real user needs
Real user needs should inform product decisions. Whether our audience includes members of the public or government employees, decision-makers must include real people in our design process from the beginning. Then, we need to test the assumptions we make and the products and services we build with real people, to keep us focused on what is most useful and important.
Learn about starting with user needs
Earn trust
Trust has to be earned every time. Federal websites and digital services can’t assume it. Trust is about understanding and meeting or exceeding expectations, a process that can be established quickly and maintained over continued interactions, but is easily damaged. Be reliable, consistent, and honest. Reduce the impact of failure with solid design and engineering. Be a good steward of your audience’s data, resources, and time.
Embrace accessibility
Accessibility affects everybody, build it into every decision. Legal requirements are a critical, necessary starting point, but this is only the beginning. Accessibility is about real people who use our services — it’s usability for people who interact with products differently. Everyone who works on government websites has a role to play in making federal resources accessible and inclusive. Design generously and celebrate accessibility requirements as a set of design constraints that help us create a better product for all users.
Learn about embracing accessibility
Promote continuity
Minimize disruption and provide a consistent experience: throughout services, over time, and across agencies, platforms, and devices. Consistency is not necessarily conformity. Agencies, sites, and services may have different audiences, missions, and goals — and the way we implement our solutions may differ — but we promote continuity by starting from shared solutions and values. These design principles are one set of shared values. The design language of the U.S. Web Design System is another. Strive to build user-centered solutions that address the whole experience, not just a user’s specific task, but the context of their journey.
Learn about promoting continuity
Listen
Evaluate and improve your product by listening to your audience and learning from what you hear. Continuous feedback drives continuous improvement. Measure customer experience — how well what we’ve built is working for our audience — at every stage of a project, and as projects grow and mature. Listen to what people say and observe how they interact with our products or services, whether through direct observation or through analytics data. If we’re not listening, we’re not learning.
Level 2: Follow user experience guidance
USWDS UX guidance helps assure that components do what users expect them to do, based on UX best practices and research. Every website is built of common functional units: components like buttons, forms, and navigation. For every website component in USWDS, we provide user experience (UX) guidance as well as code. You should follow the UX guidance even if you don’t use USWDS code.
What to do
1: Inventory your site components.
- Make a list of the components your current site uses.
- Check to see if an equivalent USWDS component exists.
2: Read the component UX guidance.
- Find the relevant component guidance on the USWDS website. Each component has its own UX guidance. (See the “Guidance” section of the button component, for example.)
- Read and understand the guidance for each component used on your site.
3: Assure site components follow guidance.
- Update any site components that fall outside USWDS guidance.
How to check
- Google Lighthouse UX audit
- Check maximum line lengths are no longer than 90 characters
- Check that sites adhere to agency-specific design and style guidelines
Level 3: Use USWDS code
Use USWDS code to provide accessible, mobile-friendly experience across government sites. The code is comprised of two parts, design tokens and components. USWDS design tokens are common and consistent elements of color, spacing, and typography that government websites share. USWDS components are pre-built, defaults elements that make up government websites. For example, the USWDS banner component is an easy way to show your site is an official government website and explain the benefits of secure connections.
Government websites include components that aren’t included in USWDS yet. Use USWDS design tokens to build new components, and contribute any new components you develop and research you collect back to USWDS.
What to do
1: Add USWDS code and adjust settings.
- Add USWDS to your project with npm or by downloading the source from Github.
- Compile the Sass source code using the guidelines in the documentation or by using uswds-compile available via GitHub.
- Compile the Javascript source code using the guidelines in the documentation or download a precompiled version.
- Add USWDS Javascript to your page templates.
- Add USWDS CSS to your page templates.
2: Use USWDS design tokens in all stylesheets.
- Install USWDS source Sass files using the instructions on the USWDS website.
- Include USWDS Sass before including existing project source files. See Sass an theme settings.
- Convert existing values to tokenized values. Use the conversion tables to convert existing values to USWDS tokens.
- Use USWDS tokens, functions (see font-family functions, for example), and utility mixins (see font-family utility mixins, for example) in existing component code.
3: Replace existing components with USWDS components.
- Swap existing components with
usa-classed components in project templates. - Use component overrides and USWDS settings to adapt the USWDS default components to your project’s desired style and tone.
4: Contribute back to the system.
- Contribute new research, guidance, components, and issues back into the system.
How to check
- Presence of banner markup
- Presence of current banner text
- Presence of
usa-prefixed classes - Presence of specific
usa-prefixed classes for common components (banner, header, footer, button, search, inputs) - Presence of USWDS stylesheet
- Presence of USWDS color tokens
- Presence of current USWDS version in stylesheets
- Presence of tokens in source Sass
- Presence of rem units for margin and padding in compiled CSS
Maturity assessment resources
Our maturity assessment resources are meant to help you assess and understand your as-is state, what you’re doing well, and how you can better use USWDS to improve the public’s experience of your websites and digital services.
Maturity Assessment Worksheet
We’re introducing the draft Maturity Model Assessment Worksheet (PDF, 723 KB, 26 pages). It’s meant to help you assess and understand your as-is state, what you’re doing well, and how you can better use USWDS to improve the public’s experience of your websites and digital services.
Checklists to track your progress
Use the checklists in the worksheet to help track your team’s progress in understanding and adopting the design principles and individual components.
This is a work in progress, and we want your input.
- Share your feedback and collaborate with the USWDS community on the #uswds-public Slack channel.
- If you can’t access slack, email us your feedback directly at uswds@gsa.gov
If you’re new to the maturity model, listen to USWDS January Monthly Call on the using the USWDS maturity model.
Latest updates
Meaningful code and guidance updates are listed in the following table:
| Date | Description |
|---|---|
| 2022-03-10 |
Replaced the outdated text: |
