Idea book: design patterns for U.S. Web Design System (USWDS) sites

uswds.facioquo.com

A website demonstrating design patterns for U.S. Web Design System (USWDS). Each pattern is a separate site page with its own isolated HTML, SASS stylesheet, and TS typescript files, to make their implementation easy to see and reuse.

While this site is built with the Angular framework, the source code is abstracted in a way that it is easily transposed to any other web development framework. Links to the GitHub code folder for each design pattern are at the bottom of each pattern page.

All design patterns are listed on the uswds.facioquo.com home page.

Don't see a good design pattern? Submit a request or contribute some code.

Getting started with local development

# install packages and
# start the local site
npm install
npm start

Testing

This project uses Jest for unit/component tests and Playwright for end-to-end tests.

Unit tests (Jest):

npm test          # run once
npm run test:watch
npm run test:coverage

End-to-end tests (Playwright):

npm run e2e           # headless on Chromium/Firefox/WebKit
npm run e2e:headed    # headed browsers
npm run e2e:ui        # Playwright test UI
npm run e2e:report    # open last HTML report

By default, e2e tests start a dev server at http://localhost:4200. You can also start the app yourself (npm run start:test) and reuse the server locally.

We use base stylesheets

Since our design pattern pages are based on default USWDS styles, we use its base stylesheets: SASS/uswds-styles.scss is an out of the box USWDS baseline. It's also the primary SASS entry point. SASS/_site.scss and the base .site family of styles are for our regular dark themed site pages and components.

Individual design patterns have their own stylesheets in their own folder. They build on top of the base USWDS styles.

Last updated: August 24, 2025