Based on uswds-sandbox [GitHub]. An eleventy site for rapid web prototyping and testing with the U.S. Web Design System (USWDS).

If you're interested in learning about the design system the USWDS Tutorial [GitHub] is a fantastic resource.

• Node v18 (LTS)

1. Clone repo.
2. Run npm install.
3. Run npm run init to get necessary files.
4. Run npm start for local environment.
5. Visit site locally at http://localhost:8080.

USWDS assets will be in assets/fonts and assets/img.

SASS files will be in the /_styles directory. Running npm start will also watch these files and recompile when there are changes.

• _uswds-theme.scss: override USWDS theme settings here.
• _project-styles.scss: project-specific styles for custom components.
• project/img/hero: Webp hero images from unsplash.
• project/img/hero/original: Original JPEG, use WEBP instead.
• src/_includes/: Component includes (like hero).
• src/_layouts/: Layout templates.

Important As you add and modify components you should always be testing for accessibility.

Exercises below are to help users understand the different ways you can use the U.S. Web Design System. They are in sequential order. If you get stuck you can move to the next branch.

Some exercises use liquid template logic for convenience. This allows you to focus on USWDS as much as possible.

Example logic

Note You won't need to modify these logic statements.

The logic below only adds a class to the first item in the loop. This is where we'll add a special class to visually differentiate this callout.

<div
  class="callout {% if forloop.first %} callout--first {% endif %}">
  …rest of code.
</div>

Branch: 01-core-components

URL: http://localhost:8080/01/

USA Banner & Identifier are core components. These are the most recognizable and standardized elements of a government site.

Exercise

Note We'll be using one of the selected system color tokens as our primary brand color moving forward.

1. Review variants of USA Banner & Identifier.
2. Find component theme settings for each.
3. Use system color tokens to set unique background and link colors in _uswds-theme.scss file.
4. Accessibility: Make sure text and links meet AA contrast requirements. use browser developer tools or the deque axe extension.

Branch: 02-prototyping

URL: http://localhost:8080/02/

Prototype a page using USWDS. We're going to be using: USWDS Components, Theme settings, Tokens, Grid layout, and Utility classes.

Exercise

1. Find News section in 02-prototyping/index.html.
2. Find the div with the ID example-card-flag.
3. Use the code example for Flag layout card to convert the news section markup.
4. Apply utility classes to remove list styles from unordered list labelled #example-list.
5. Apply the USA Tag markup to the list items [example-tags] inside example list.
6. Use the card component example to apply default card markup to the callout section list labelled card-default-example.
7. Add a utility class to change the background color (and text color if needed).
8. Use the headings variant of collection component code example to section labelled example-collection-headers.
9. Apply collection calendar variant code example to section labelled example-collection-headers.
10. Finally we're going to apply layout classes. Start at the top section labelled example-grid-row and apply the grid row classes.
11. Apply layout grid classes to the <main> and <aside> elements to create a two column grid.
12. Use utility settings to enable the tablet-lg breakpoint in [_uswds-theme.scss].
13. Use responsive variants to define an 8-col content section and a 4-col wide sidebar with your newly enabled breakpoint.

Branch: 03-theming

URL: http://localhost:8080/03/

Now that we have structure and basic theming setup. Let's start customizing and applying our "brand" colors.

Exercise

1. Go to theme settings stylesheet [_uswds-theme.scss]. Use color from either Banner or Identifier to define primary theme colors. Learn more about theme colors
2. Update Banner & Identifier theme settings with new primary token.
3. Set identifier secondary links to primary lightest color.
4. Modify theme setting for focus color and set to primary theme color.
5. Add base theme color settings to match your new primary color.
6. Add accent theme color settings to match your new primary colors. Hint: Use USWDS color wheel to help.
7. Find and update hero image theme setting. Use sample WEBP images from assets/project/img/hero directory.
8. Cleanup first callout card. Fix contrast issues.

Branch: 04-beyond

URL: http://localhost:8080/04/

Here we're going to refine our design customize some components.

Exercise

1. A custom hero.
2. Creating a nav component.
3. One method of extending language selector. We want to make a few customizations. Like remove the border, use a multi-column layout, and add some filtering.

• USWDS Docs [designsystem.digital.gov]
  • Theme settings page
  • Components
  • Color tokens
    • Overview; we'll look at color wheels for theming.
    • Theme tokens
    • State tokens
    • System tokens

• VS Code Better Comments extension; Improved code comment styles.
• VS Code Prettier extension: linting & formatting [marketplace.visualstudio.com]; For consistent code style & formatting.
• axe devtools [deque.com]; for a11y testing.