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 for the American public.

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
A diagram showing the concentric circles of the USWDS maturity model, progressing from Principles on the outside, through Guidance, and finally to Code in the innermost circle.

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.

Learn about earning trust

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.

Learn about listening

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.

How to check

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.

2: Use USWDS design tokens in all stylesheets.

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.

They’re meant to help your team understand and improve your design system maturity: to help your team solve problems, not stress you out. Over the next few months, we will be working on the format of a maturity assessment, our user-centered process for updating it, and how we’ll release updates to the community.

If any of our guidance doesn’t make sense or feels like it’s leading your team in the wrong direction, please let us know. File an issue at our GitHub page or send USWDS an email.