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, share what you learn with the USWDS community:
- Report a bug or documentation problem, including the version you use and steps to reproduce the problem.
- Share research, guidance, and implementation questions in GitHub Discussions.
- Propose a new component or pattern.
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. USWDS provides user experience (UX) guidance for components and patterns. 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
- Use the current usability and accessibility guidance for each component to check your implementation.
- Review line length guidance and your agency’s 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.
- Follow Phase 1: Install USWDS to add the package to your project.
- Follow Phase 2: Compile USWDS to copy assets and compile your project’s Sass.
- Include the generated CSS in your page templates. Include the JavaScript required by the components you use, following their implementation guidance. A precompiled JavaScript bundle is available; compiling JavaScript yourself is not required for every project.
- Follow Phase 3: Customize USWDS to adjust settings and styles.
2: Use USWDS design tokens in your stylesheets.
- Use design tokens for consistent colors, spacing, and typography.
- Use the Sass functions and mixins documented with each token, or utilities where appropriate. For example, see font-family tokens.
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
The presence of usa- classes or a USWDS stylesheet can help identify an implementation. It does not establish that the implementation is usable or accessible. Use the current component guidance to check your implementation in context.
Maturity assessment resources
The draft 2020 Maturity Model Assessment Worksheet is no longer recommended for current assessments. Its copied component checklists do not reflect current guidance.
Use the design principles and the current usability, accessibility, and implementation guidance for each component. For installation and customization instructions, use Getting started for developers.
Share questions and findings in USWDS GitHub Discussions.
Latest updates
Meaningful code and guidance updates are listed in the following table:
| Date | Description |
|---|---|
| 2026-09-16 |
Updated community participation guidance to point to GitHub Discussions. More information: uswds-site#3303 |
| 2022-03-10 |
Replaced the outdated text: |
