Getting started for designers

Overview of the theme

The Code for America, U. S. Web Design System (USWDS) theme adapts the USWDS to look like the Honeycrisp Design System. On this site, designers can learn how to design for the USWDS, create custom themes, and find guidance for component usage.

Comparison to Honeycrisp

Compared to Honeycrisp, the theme’s user interface (UI) looks and feels similar. In addition to how the design system works, there will be slight differences in how the theme displays. Examples include the following.

• Atomic properties or styles of the USWDS are defined using design tokens. USWDS design tokens have been used to adapt the USWDS to create this theme.

• Spacing in the USWDS is based on an 8px grid size, compared to Honeycrisp’s 5px grid size. All spacing increments are based on multiples of 8 instead of 5.

• The typography scale is customized to match Honeycrisp’s type sizing as closely as possible, but they are slightly different.

• Color values between the CfA USWDS theme and the Honeycrisp are not 1 to 1. The USWDS provides a robust color system that allows for nearest-neighbor matching. This helps ensure adequate color contrast for accessibility.

Each of these topics are explained in more detail below. Continue to use the Honeycrisp Design Library to create mockups with the understanding that they may not exactly match their live counterparts pixel to pixel.

The Honeycrisp Design Library can be used with our copy of the U.S. Web Design System (USWDS) community Figma file (created by TrussWorks).

Creating themes

Designers will likely need to create custom themes to adapt the system to fit another brand identity’s visual style. This may be for a government or civic organization. Many properties of the USWDS can be used to achieve custom themes (using design tokens). The Code for America USWDS Theme takes advantage of some of those properties. It also adds a layer of customization for components unavailable in the USWDS.

This section will cover some prerequisite topics for creating custom themes. Further sections will dive right into Figma so skip ahead if you feel comfortable with the basics.

Design tokens

The USWDS relies heavily on design tokens. It’s important to understand this concept before working with the system. The most important takeaways include the following.

• Design tokens are the “currency” used to customize themes.

• They make it easier for designers and engineers to share a common language necessary to complete a theme.

• Tokens designate the rules for color, typography, spacing, and more.

• Read the USWDS Design Tokens Guide by Bixal before getting started, "Understand the benefits" and "Learn the language" (both are embedded below).

Spacing

Honeycrisp and the USWDS grid systems are mobile-first and responsive. The Honeycrisp grid is based on multiples of 5px. The USWDS grid is based on multiples of 8px and provides half-unit (4px) and single-pixel values for slight nudging (2px and 1px). This theme uses the USWDS grid and deprecates the Honeycrisp grid.

• Continue to create designs for mobile devices.

• If you define any spacing on a grid or between components and other elements, remember to use multiples of 8px.

Color

Honeycrisp and the USWDS use theme color families, such as primary and secondary (and more), to determine the theme's appearance. The USWDS has more color families with predefined hues and grades for tints and shades in each family. These pre-defined values for every hue and grade ensure enough contrast between colors in various system components.

For the most part, using custom values in themes is discouraged. There are 42 hues, each with 10 tints and shades, making 470 possible color values. You can assign pre-defined system tokens to theme tokens to customize the appearance of your theme.

• To customize the theme, determine the theme color families you need to change (like primary, secondary, base, or warning).

• Fill all the grades in each family with the hue you want to use.

• More detailed instructions can be found in the Honeycrisp Design Library.

Typography

Honeycrisp and this theme are typeset using sans-serif “system” fonts. This means the typeface users visually read text with depends on the operating system they are using. For iOS or MacOS users, this may be SF Pro. For Android users, this may be Roboto. For Windows users, this may be Segoe UI.

Line heights for all USWDS fonts are “normalized” so that their vertical height takes up the same space. It additionally supports the following 9 typefaces:

• Georgia

• Helvetica

• Merriweather

• Open Sans

• Public Sans

• Roboto Mono

• Source Sans Pro

• Tahoma

• Verdana

You may customize the typeface for your theme by choosing one of the supported typefaces. Typefaces not in this list can also be used, but there are some special instructions to enable them (which can be found on the USWDS site).