About

What is a design system at Code for America?

A foundation of shared practices and reusable components guided by design strategy and clear standards that can be used by and adapted to the evolving needs of products, services, and the teams using them.

Design systems are made of tools, like this theme, to achieve a shared understanding of how to solve recurring problems through design. These tools are applied to other platforms, products, or application frameworks. At Code for America, our design system is called Honeycrisp. It was organized around design practices, patterns, and component libraries to create products such as GetCalFresh, GetYourRefund, and MNBenefits.

The U.S. Web Design System

The USWDS is an ecosystem crafted to elevate the design standard across federal agencies. Developed by the United States Digital Service (USDS) and 18F, it represents a commitment to accessibility, usability, inclusion, and seamless experience for everyone in the United States interacting with digital government services. Among its core features are:

• accessibility-first components and patterns,

• user-centric design principles,

• familiarity across government,

• mobile-first design,

• and open-source collaboration.

Our model of adoption

In early 2022, the Code for America Safety Net Innovation Lab’s platform team investigated migrating from our internal design system, Honeycrisp, to the USWDS. The main benefits we anticipate gaining from adopting the USWDS include the following:

• easier customization,

• increased team efficiency and autonomy,

• and a better product for our government partners

Other important considerations included:

• alignment with our principles,

• culture fit,

• making the right thing easy to do,

• and expanding our impact.

The Code for America, U.S. Web Design System theme

This theme is an adaption of the USWDS^*. It uses “design tokens” to make the USWDS resemble the Honeycrisp Design System. It also includes components from the Honeycrisp design system that do not exist in the USWDS. The theme gives us a balance of leveraging our existing practice of good form design with all of the benefits of the USWDS.

Who this is for

This theme is for Code for America teams creating applications that are based on the Honeycrisp Design System and want to transition to an adapted version of the USWDS^*.

• Designers will be able to more easily customize the theme based on the needs of their projects. For engineers, these custom themes are more easily implemented using Sass configuration methods.

• More components, currently unavailable in Honeycrisp, can be used in designs. Some examples include:

  • the Combobox; USWDS documentation | Figma component,

  • the Date Picker; USWDS documentation | Figma component,

  • the Time Picker; USWDS documentation | Figma component,

  • the Icon List; USWDS documentation | Figma component,

  • and others; browse all USWDS components | Figma component library.

Please remember, however, that due to the Form Flow Builder’s focus on a limited set of components, we have not recreated all of the USWDS components in this theme.

For designers

• The Honeycrisp Design Library can continue to create high-fidelity mockups and prototypes.

• Understanding on when or not to use certain components is clearer, leveraging USWDS guidance.

On this site, designers can understand the differences between Honeycrisp and the USWDS and learn how to create new themes.

For engineers

• The USWDS provides a robust set of CSS utilities that can be used to make small modifications to components or templates. Utilities can also be used to create entirely new components.

• Code snippets for each component are rendered using pre-built Thymeleaf template fragments and ERB templates that can be included in your project. Parameters can be passed to these components to customize their appearance.

On this site, engineers can reference documentation for migration from the Honeycrisp codebase to the theme codebase component replacements.

For others

This theme and the USWDS can be used by everyone working on platforms, products, or application frameworks to make educated decisions about how their end-users should experience digital services. Even if you aren't using the design or component library. Use the documentation on components and patterns to guide decisions on how you build.

* There are generally three approaches to using a design system: adopting an existing design system, adapting an existing design system, or creating your own proprietary or custom design system. From Design Systems 101 (nngroup.com)