Reading the USWDS package: dist, packages and the exports map
The U.S. Web Design System helps the federal government build fast, accessible, mobile-friendly websites.
At a glance
- What is it?
- USWDS is the design system behind U.S. federal websites, published as the @uswds/uswds package with compiled files in dist and component source in packages. Most of the confusion a new adopter hits comes from the gap between those two trees and from an exports map that resolves some imports to raw source.
- Who is it for?
- Take USWDS when you are building a U.S. government site and want accessible defaults, an icon sprite and four self-hosted font families without designing them. Leave it when your theme values have to change at runtime, when your build cannot compile Sass, or when you planned to patch a component inside the package.
- Can I use it commercially?
- Check first. The repository uses a licence we do not classify automatically, so read its LICENSE file before any commercial use.
- Is it still maintained?
- Yes. The repository last received commits 11 days ago.
- What is it written in?
- Mainly JavaScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- uswds/uswds7,246 β Β· +47
| Repository | 2026-09-23 | 2026-11-15 |
|---|---|---|
| uswds/uswds | 7.2k | 7.2k |
47 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
This repository is the code, not the documentation
uswds/uswds holds the design system itself: component source, compiled assets and the build. Documentation and the public website live in a separate repository, uswds/uswds-site, and the rendered version of everything you would read first is at designsystem.digital.gov. That split has a cost worth naming before you clone anything. This repository gives you no guidance pages, and its README is a map rather than a manual. The table of contents points at installing the design system, compiling USWDS Sass into CSS, JavaScript customization, style theming and tokens, the CSS architecture, browser support, accessibility, and the long-term support notes for v1.x and v2.x.
Two other details change what you get from a clone. The default branch is develop, not master, so a plain clone lands you on the working line rather than on a released tag. And LICENSE.md sits at the root while the README calls the components public domain and open source; GitHub's repository metadata reports the licence as NOASSERTION. If your organization's dependency inventory needs a named license, that field is where you will stop and ask.
Compiled files in dist, component source in packages
Two directories, two jobs. dist holds compiled or collected files: uswds.css, uswds.min.css and a source map, the font families, the images and the precompiled JavaScript. packages holds the component source, one directory per component, with stylesheets at packages/[package]/src/styles, a Sass entry point at packages/[package]/_index.scss that pulls in that component's dependencies, and component JavaScript at packages/[package]/src/index.js. The fonts are duplicated on purpose, since dist/fonts is a copy of packages/uswds-core/src/assets/fonts and a project can serve the compiled tree without the core package's sources.
What catches teams out is the template layer. Each package also ships markup as Twig at packages/[package]/src/[package].twig, and the guidance is not to copy that markup but to take the HTML source for a component from designsystem.digital.gov/components instead. Outside a Twig stack the packaged template is dead weight, so the markup you actually ship is hand-copied from the site, which means it can drift from the version your dependency names.
First use is a matter of file paths
The short route to a rendered page is to add the package, published on npm as @uswds/uswds, and point your build at the compiled files inside it. The repository metadata gives the current version as 3.14.0, and the top of the tree looks like this:
[uswds package]
βββ .storybook/
βββ dist/
β βββ css/
β β βββ uswds.css
β β βββ uswds.min.css
β β βββ uswds.min.css.map
β βββ fonts/
β β βββ merriweather/
β β βββ public-sans/
β β βββ roboto-mono/
β β βββ source-sans-pro/Four paths matter on day one. The stylesheet is dist/css/uswds.min.css. The JavaScript sits in dist/js: uswds-init.js and the bundle uswds.js, each with a minified version. Icons live in dist/img, with sprite.svg holding the precompiled set. The four font families are directories you copy next to your own CSS, not a webfont service to link. The package metadata names the same entry points, and its sass field points into src rather than dist:
"main": "dist/js/uswds.min.js",
"module": "./dist/js/uswds.min.js",
"style": "dist/css/uswds.min.css",
"sass": "./src/stylesheets/uswds.scss",Without npm you maintain the paths yourself
Projects that do not use npm for package management are an anticipated case. The README routes them to instructions further down the same file for installing the design system without npm. What that route costs is visible in the package contents. You lose the exports map, so nothing resolves a component subpath for you and every reference becomes a path you maintain by hand into dist. You also lose the dependency graph behind Sass compilation, which puts the compiler, its version and its include path on your team.
What you keep is the compiled tree, the four font families and sprite.svg, which is exactly what a static site with a hand-rolled build wants. So the choice is not between a good install and a bad one. It is between a package manager that keeps component paths aligned for you and a directory of files your build script has to keep aligned itself, and the second option gets more expensive with every component you add.
The exports map resolves two imports to two builds
The package metadata declares an exports field with more than ten subpaths, and two of them hand you different code for the same component. Here are the mapping entries most projects touch:
"./js/*": "./packages/*/src/index.js",
"./scss/*": "./packages/*/_index.scss",
"./css/*": "./dist/css/*",
"./img/*": "./dist/img/*",
"./fonts/*": "./packages/uswds-core/src/assets/fonts/*"Read that next to the root entry, which points at ./dist/js/uswds.min.js. Importing the package root gives you the transpiled bundle. Importing through the ./js subpath gives you the raw index.js out of packages, with no build step in between. A team that mixes the two while developing and switches to the root for production runs two builds of the same component, and a smoke test will not show it.
The font subpath is a second trap in the same map, because it resolves into packages/uswds-core/src/assets/fonts rather than the dist/fonts copy. The same family can then be requested under two different URLs depending on which subpath a file used, which is the kind of duplication a cache header cannot fix.
gulp compiles, vite builds the components, eslint polices both
Changing the design system means running this repository's toolchain, and the scripts say exactly what it is:
"build": "gulp && npm run build:web-components",
"build:web-components": "vite build --config='./vite.config.banner.cdn.js'",
"lint": "npm run lint:js && npm run lint:sass",
"lint:js": "eslint .",
"lint:sass": "gulp lintSass",
"mocha": "mocha"gulp remains the entry point for Sass compilation and Sass linting, vite builds the web component output under its own banner config, eslint covers the JavaScript and mocha runs the tests. The root directory holds the configuration for all of it: gulpfile.js, eslint.config.mjs, .browserslistrc, .prettierrc.json, .stylelintrc.json, svgo.config.js, tsconfig.json, and four vite configs including vite.config.components.js.
The consequence for an application team is narrow and firm. This is not a place to patch a component for your own site, because dist is generated by that toolchain and a hand edit there disappears on the next build. What you own is your markup, your Sass and your copy of the fonts.
Theme files are examples, not a settings API
Theming rests on three example files and a compile step. Under dist/scss/theme you get _uswds-theme.scss as an example theme settings file, _uswds-theme-custom-styles.scss as an example custom settings file, and styles.scss as an example project stylesheet. Changing a colour means editing Sass and compiling it again.
Which entry point you compile is a decision of its own, because there are two. dist/scss/stylesheets/uswds.scss is described as the backwards compatible USWDS Sass entry point, while the sass field in the package metadata points at ./src/stylesheets/uswds.scss. Pick one, pin it in your build configuration, and read backwards compatible as the documentation's own warning that the other path exists for older setups.
v1.x and v2.x keep separate support notes, 3.0 has a guide
The README holds long-term support sections for two older major versions, v1.x and v2.x, and states that 3.0 is the most recent major release, with a migration guide published on the documentation site.
The 3.x cadence is visible in the tags: v3.12.0 on 2025-03-07, v3.13.0 on 2025-05-23, v3.14.0 on 2026-08-18, with the last push to the develop branch on 2026-10-31. Moving inside a minor version means recompiling your Sass against a newer dist tree and re-copying the fonts and the sprite, because those live inside the dependency rather than in your own assets directory. Moving across a major version is a migration project with breaking changes to work through, and for 3.0 that guide sits at designsystem.digital.gov/documentation/migration.
Editorial conclusion
Take USWDS when you are building a U.S. government site and want accessible defaults, an icon sprite and four self-hosted font families without designing them. Leave it when your theme values have to change at runtime, when your build cannot compile Sass, or when you planned to patch a component inside the package. Check three things before committing: which Sass entry point your build resolves, whether your component imports go through the ./js subpath or the package root, and what LICENSE.md says about your use.
Frequently asked questions
What does USWDS stand for?
United States Web Design System. The GitHub repository is uswds/uswds and the npm package is @uswds/uswds, whose metadata in this repository reads version 3.14.0.
What is USWDS?
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.
Is USWDS open source?
The README calls it a library of public domain and open source user interface components, and a LICENSE.md file sits at the repository root. GitHub's repository metadata reports the licence as NOASSERTION.
What are the USWDS typography guidelines?
The package self-hosts four font families under dist/fonts: merriweather, public-sans, roboto-mono and source-sans-pro.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/uswds-uswds)Star history chart for your README
[](https://hysenlabs.com/projects/uswds-uswds)Was this useful?