> For the complete documentation index, see [llms.txt](https://wiki.simpler.grants.gov/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wiki.simpler.grants.gov/product/decisions/adr/2023-07-20-fe-design-system.md). # Use U.S. Web Design System for components and utility classes * Status: Accepted * Deciders: Loren, Rocket, Sawyer ## Context and Problem Statement Projects should avoid reinventing the wheel where possible. A common place to do this is in the UI, by using a design system for frontend components and utility classes. This can help avoid inconsistencies in the UI, and can reduce barriers for new developers. We want to use a design system that is: * Section 508 compliant * Open source * Well maintained and documented * Includes the typical components and design patterns needed for government websites ## Considered Options * [U.S. Web Design System (USWDS)](https://designsystem.digital.gov/) * [CMS Design System](https://design.cms.gov/) ## Decision Outcome The template will provide U.S. Web Design System styling out of the box. We will not follow their [install directions](https://designsystem.digital.gov/documentation/getting-started/developers), which suggests using Gulp as a task runner. Instead, to reduce the number of dependencies and configuration, we'll leverage Next.js's and Storybook's built-in Sass support. Copying the USWDS static assets into the project will be handled by a [`postinstall`](https://docs.npmjs.com/cli/v8/using-npm/scripts) script in `package.json`. ### Positive Consequences * USWDS is the most popular design system for U.S. government websites and is maintained by GSA employees. It is the recommended way to meet the website standards detailed in the [21st Century Integrated Digital Experience Act](https://digital.gov/resources/21st-century-integrated-digital-experience-act/). [More key benefits can be read about here](https://designsystem.digital.gov/about/key-benefits/). * [Project teams can theme the USWDS](https://www.navapbc.com/insights/us-web-design-system) if their project needs to match an existing brand. ### Negative Consequences * Unlike the CMS Design System, USWDS doesn't provide React components. Project teams will need to create their own React components that output USWDS markup, or install a third-party library like [`react-uswds`](https://github.com/trussworks/react-uswds). In the future, [the template could include this library by default](https://github.com/navapbc/template-application-nextjs/issues/19). * CMS projects may need to swap out USWDS for the CMS Design System, although the CMS Design System is based on USWDS, so this may not be necessary right away. ## Links * [Previous research was done by Kalvin Wang and Shannon Alexander Navarro related to USWDS React libraries](https://docs.google.com/document/d/1KRWzH_wJUPKkFmBlxj6SM2yN3W7Or89Wa4TBVM3Ksog/edit) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://wiki.simpler.grants.gov/product/decisions/adr/2023-07-20-fe-design-system.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.