The U.S. Web Design System includes a library of open source UI components and a visual style guide for U.S. federal government websites.
This repository is for the Design System itself. We maintain another repository for the documentation and website. To see the Design System and documentation on the web, visit https://designsystem.digital.gov.
The components and style guide of the U.S. Web Design System follows industry-standard web accessibility guidelines and use the best practices of existing style libraries and modern web design. The U.S. Digital Service and 18F created the U.S. Web Design System for designers and developers. The U.S. Web Design System is a project of GSA’s Technology Transformation Service, maintained by the Office of Products and Programs. They are designed for use by government product teams who want to create beautiful, easy-to-use online experiences for the public. To learn more about the project, check out this blog post and to view websites and applications check out our list here.
Information about the most recent release of the Design System can always be found in the release history. We include details about significant updates and any backwards incompatible changes along with a list of all changes.
We’re glad you’d like to use the Design System — here’s how you can get started:
There are a few different ways to use the Design System within your project. Which one you choose depends on the needs of your project and how you are most comfortable working. Here are a few notes on what to consider when deciding which installation method to use:
Download the Design System if:
npm and package management.Use the Design System npm package if:
npm and package management.After extracting the zip file you should see the following file and folder structure:
uswds-1.0.0/
├── css/
│ ├── uswds.min.css.map
│ ├── uswds.min.css
│ └── uswds.css
├── fonts/
├── html/
└── js/
├── uswds.min.js.map
├── uswds.min.js
└── uswds.js
example-project/
├── assets/
│ ├── uswds-1.0.0/
│ ├── stylesheets/
│ ├── images/
│ └── javascript/
└── index.html
You'll notice in our example above that we also outline a stylesheets, images and javascript folder in your assets folder. These folders are to help organize any assets that are unique to your project.
Here is an example of how to reference these assets in your index.html file:
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<title>My Example Project</title>
<link rel="stylesheet" href="assets/uswds-1.0.0/css/uswds.min.css">
</head>
<body>
<script src="assets/uswds-1.0.0/js/uswds.min.js"></script>
</body>
</html>
We offer both files, the CSS and the JavaScript, in two versions — a minified version, and an un-minified one. (In the examples above, we are using the minified files.) Use the minified files in a production environment or to reduce the file size of your downloaded assets. And the un-minified files are better if you are in a development environment or would like to debug the CSS or JavaScript assets in the browser.
And that’s it — you should now be able to copy our code samples into our index.html and start using the Design System.
npm is a package manager for Node based projects. The U.S. Web Design System maintains a uswds package for you to utilize both the pre-compiled and compiled files on your project.
Node/npm. Below is a link to find the install method that coincides with your operating system:Note for Windows users: If you are using Windows and are unfamiliar with Node or npm, we recommend following Team Treehouse's tutorial for more information.
npm -v
3.10.8 # This line may vary depending on what version of Node you've installed.
Create a package.json file. You can do this manually, but an easier method is to use the npm init command. This command will prompt you with a few questions to create your package.json file.
Add uswds to your project’s package.json:
npm install --save uswds
The uswds module is now installed as a dependency. You can use the un-compiled files found in the src/ or the compiled files in the dist/ directory.
node_modules/uswds/
├── dist/
│ ├── css/
│ ├── fonts/
│ ├── html/
│ ├── img/
│ ├── js/
└── src/
├── fonts/
├── img/
├── js/
├── stylesheets/
└── templates/
Since you are already using npm, the U.S. Web Design System team recommends leveraging the ability to write custom scripts. Here are some links to how we do this with our docs website using npm + gulp:
Link to npm scripts example in uswds-site
Link to gulpfile.js example in uswds-site
The Design System is easily customizable using the power of Sass (Syntactically Awesome Style Sheets). The main Sass (SCSS) source file is located here:
node_modules/uswds/src/stylesheets/uswds.scss
Global variables are defined in the node_modules/uswds/src/stylesheets/core/_variables.scss file. Custom theming can be done by copying the _variables.scss file into your own project’s Sass folder, changing applicable variable values, and importing it before uswds.scss.
Below is an example of how you might setup your main Sass file to achieve this:
@import 'variables.scss'; # Custom Sass variables file
@import 'node_modules/uswds/src/stylesheets/uswds.scss';
You can now use your copied version of _variables.scss to override any styles to create a more custom look and feel to your application.
require('uswds') will load all of the U.S. Web Design System’s JavaScript onto the page. Add this line to whatever initializer you use to load JavaScript into your application.
If you’re using another framework or package manager that doesn’t support npm, you can find the source files in this repository and use them in your project. Otherwise, we recommend that you follow the download instructions. Please note that the core team isn’t responsible for all frameworks’ implementations.
If you’re interested in maintaining a package that helps us distribute the U.S. Web Design System, the project’s build system can help you create distribution bundles to use in your project. Please read our contributing guidelines to locally build distributions for your framework or package manager.
We're using Fractal to generate an interactive component library for the Design System. You can run it locally after npm install with:
npm start
Then, visit http://localhost:3000/ to see the Design System in action.
Optional: To re-build when code changes are made, run the following command from the project directory in a separate terminal window:
npm run watch
Many of our Fractal view templates are compatible with Nunjucks (for JavaScript/Node), Jinja (Python), and Twig (PHP) out of the box. Components that reference other components use a Fractal-specific {% render %} tag that will either need to be implemented in other environments or replaced with the appropriate {% include %} tags.
Do you have questions or need help with setup? Did you run into any weird errors while following these instructions? Feel free to open an issue here:
https://github.com/uswds/uswds/issues.
You can also email us directly at uswebdesignstandards@gsa.gov.
For complete instructions on how to contribute code, please read CONTRIBUTING.md. These instructions also include guidance on how to set up your own copy of the Design System style guide website for development.
If you would like to learn more about our workflow process, check out the Workflow and Issue label Glossary pages on the wiki.
If you have questions or concerns about our contributing workflow, please contact us by filing a GitHub issue or emailing our team.
Much of the guidance in the U.S. Web Design System leans on open source designs, code, and patterns from other civic and government organizations, including:
A few parts of this project are not in the public domain. Attribution and licensing information for those parts are described in detail in LICENSE.md.
The rest of this project is in the worldwide public domain, released under the CC0 1.0 Universal public domain dedication.
All contributions to this project will be released under the CC0 dedication alongside the public domain portions of this project. For more information, see CONTRIBUTING.md.
FAQs
Open source UI components and visual style guide for U.S. government websites
The npm package uswds receives a total of 9,807 weekly downloads. As such, uswds popularity was classified as popular.
We found that uswds demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 4 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
Socket’s threat research team has detected six malicious npm packages typosquatting popular libraries to insert SSH backdoors.
Security News
MITRE's 2024 CWE Top 25 highlights critical software vulnerabilities like XSS, SQL Injection, and CSRF, reflecting shifts due to a refined ranking methodology.
Security News
In this segment of the Risky Business podcast, Feross Aboukhadijeh and Patrick Gray discuss the challenges of tracking malware discovered in open source softare.