USWDS: the federal design system you install through npm, Sass and a dist folder

What USWDS solves, and who it is actually built for

USWDS stands for the United States Web Design System. The repository describes it as a toolkit of principles, guidance, and code: a library of public domain and open source user interface components plus a visual style guide designed for U.S. federal government websites, though the README adds that it is useful in many other applications.

The audience is narrow by design. The README splits its getting started paths into designers, developers, and everyone else, pointing designers at a getting-started page and developers at a developer guide. If your project does not use npm for package management, the README says to follow the install instructions that do not require npm. That sentence tells you what the project assumes: a modern JavaScript toolchain is the default path, and the non-npm route is the exception.

The problem it addresses is consistency and accessibility across many independently built government sites. Instead of every agency inventing buttons, alerts, and accordions, USWDS publishes one set of components with one visual language. The trade-off is that you inherit that language. Restyling is possible through theme settings and tokens, but the component markup and class names are the contract.

How the codebase is organized: dist, packages and uswds-core

Since USWDS 3.0.0 the codebase is centered on functional packages, typically one per component. The README gives the pattern: component Sass lives in packages/[package]/src/styles, so accordion styles are at packages/usa-accordion/src/styles. Component JavaScript lives at packages/[package]/src/index.js, and general JavaScript utilities live in the uswds-core package under packages/uswds-core/src/js.

Two directories matter when you consume the package. dist holds compiled assets: dist/css/uswds.css and uswds.min.css, fonts under dist/fonts (merriweather, public-sans, roboto-mono, source-sans-pro), images and icons under dist/img, and JavaScript at dist/js/uswds.js plus uswds-init.js. packages holds the source. The fonts in dist are a copy of the files in packages/uswds-core/src/assets/fonts.

One detail deserves attention. Component template markup is written in Twig, at packages/[package]/src/[package.twig]. The README is explicit that it is best to get HTML source markup directly from designsystem.digital.gov/components rather than reading the Twig. That is a real constraint: if you want to know the exact class names and attributes for a component, the repository is not the recommended source. The website is.

The package.json exports map is the other thing to read closely. The root export and the import condition both resolve to ./dist/js/uswds.min.js. Deep imports such as ./js/* resolve to packages/*/src/index.js, ./css/* to dist/css/*, ./scss/* to packages/*/_index.scss, and ./img/* to dist/img/*. If your bundler only understands the root entry, you get the compiled bundle and not the per-component source.

Installing USWDS from npm and compiling your first stylesheet

The README points developers at the getting-started-for-developers documentation and lists npm as the standard route, with a separate non-npm path. The install command is the package name as published:

npm install @uswds/uswds

After that, the package exposes Sass through the ./scss/* export, which maps to packages/*/_index.scss. The dist directory also ships a theme scaffold at dist/theme with _uswds-theme.scss, _uswds-theme-custom-styles.scss and styles.scss, plus dist/scss/stylesheets/uswds.scss. The README's compiling section covers Sass compilation requirements and theme settings, so treat the compiler version as something to check before you write any styles, not after.

If you do not use npm, the README directs you to its install-the-design-system-without-npm instructions rather than a CDN snippet. There is a vite.config.banner.cdn.js in the repository, but the README does not present a copy-paste CDN tag, so do not assume one exists.

To see a component, the README says to pull markup from designsystem.digital.gov/components. A button in USWDS is a class on an anchor or button element, not a JavaScript import, so the first useful test is dropping the markup in and confirming that dist/css/uswds.min.css is loaded. If the styles do not appear, the usual cause is that the CSS file was never copied out of node_modules.

The JavaScript layer and how initialization actually runs

USWDS ships two JavaScript files in dist/js, and the distinction matters. uswds-init.js is separate from uswds.js, and the README lists both alongside their minified versions and source maps. The presence of a dedicated init file suggests initialization is a distinct step from the component bundle, which is why the README has a JS customization section rather than treating JavaScript as a single include.

Component behavior is per-package. Each component's script sits at packages/[package]/src/index.js, and the exports map routes ./js/* to exactly those files. That means you can import one component's behavior without pulling the whole bundle, provided your bundler honors subpath exports. The root import, by contrast, resolves to the minified bundle.

Testing lives beside the source: the directory structure shows packages/usa-component/src/test/component.spec.js and template.html. The repository's own test runner is Mocha, visible in .mocharc.js and a mocha script in package.json. That is useful context if you plan to fork or patch a component, because you can run the same spec files the project runs.

The limitation to keep in mind is that these are progressive-enhancement scripts attached to server-rendered markup, not a component framework. There are no props, no state management, and no virtual DOM. If your application expects components to own their own rendering, USWDS will feel like the wrong layer.

Where USWDS stops being the right tool

The clearest boundary is framework integration. The README describes a library of UI components and a style guide; it does not describe React, Vue, or Angular bindings. The exports map confirms this: you get CSS, Sass, images, fonts, and plain JavaScript modules. A team that wants typed component props and framework-managed lifecycle will spend its time writing wrappers.

The second boundary is the Twig markup. Because the README recommends taking HTML from the website rather than from packages/[package]/src/[package.twig], the repository is not a self-contained reference for markup. You are dependent on the documentation site staying in sync with the code, and the site lives in a separate repository, uswds/uswds-site, which the README names explicitly. Two repositories means two release rhythms.

The third is styling freedom. Theme settings and tokens exist, and the README has sections on style theming and tokens and on CSS architecture, but the components are opinionated. A brand that diverges sharply from the federal visual language will fight the defaults. If you need a design system that bends to any brand with minimal overrides, USWDS is not that.

Finally, version support is finite. The README carries separate sections for long-term support of v1.x and v2.x, which is a signal that older majors eventually stop receiving that support. Pinning to an old major is a decision with an expiry date.

Figma, Drupal and the alternatives people compare it against

The related searches around USWDS include Figma and Drupal, and both point at the same reality: USWDS is a code and guidance package, and other layers sit on top of it. The README does not document official Figma files or a Drupal distribution, so treat those as community or agency-specific integrations rather than something this repository ships. The repository you install is @uswds/uswds.

A more useful comparison is against general-purpose CSS frameworks. Bootstrap and Tailwind CSS both give you utility classes or a grid and leave accessibility semantics largely to you. USWDS inverts that: the component markup carries the accessibility work, and the styling is what you customize. That is a different division of labor, and it is why USWDS components come with both Sass and JavaScript per package.

The cost of that inversion is flexibility. With a utility framework you compose any visual result from primitives. With USWDS you start from a finished component and adjust tokens and theme settings. For a federal site that needs consistent, accessible patterns across many teams, the constraint is the feature. For a marketing site with a custom brand, it is overhead.

Licensing, attribution and what you inherit

The repository's license field is NOASSERTION, which means GitHub could not match the LICENSE.md file to a standard identifier. The README points to a Licenses and attribution section and a reuse-of-open-source-style-guides section, and the package description calls the components public domain and open source. The practical step is to read LICENSE.md and the attribution section yourself before shipping, because the components and any bundled third-party assets may not carry identical terms.

This is not legal advice. What you can verify from the repository is that LICENSE.md exists at the top level, that the README devotes a section to licenses and attribution, and that the package is published on npm under the name @uswds/uswds. Whether your organization's reuse policy accepts those terms is a question for your own review, not something the README answers.

On upgrade cost, the release cadence is visible. v3.12.0 landed on 2025-03-07, v3.13.0 on 2025-05-23, and v3.14.0 on 2026-08-18. The README says the release history includes details about significant updates and any backward-incompatible changes along with a list of all changes, and it links a USWDS 3.0 migration guide. The last push to the repository was on 2026-09-18. Budget time for reading release notes between majors, since the project maintains separate long-term support statements for v1.x and v2.x rather than promising indefinite support.

Editorial conclusion

Adopt USWDS if you ship a U.S. federal or state site that must meet accessibility expectations and you are willing to run a Sass build. Skip it if you want framework-native components or a design system you can restyle without touching tokens and theme files. Before committing, verify two things in your own environment: that your Sass compiler matches the requirements in the compiling section, and that your bundler resolves the packages/*/src/index.js entry points rather than only dist/js/uswds.min.js.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. uswds/uswds on GitHub