Components

Upgrade to U.S. Web Design System v3

Many of the components the VA shares with the USWDS have been synced to the design, styling, and functionality of the US System while retaining elements necessary to the VA. Components that have been converted are marked with a badge USWDS v3 at the top of their component page.

We ask that teams begin to use these new versions of our web-components to aid in the process of upgrading VA.gov to USWDS v3. v3-based versions of the components are designed to sit alongside our current v1 based components and Formation. Thus for most converted components you may notice only slight differences in appearance or functionality. The Design System Team will be rolling out the new v3-based System over the upcoming months including syncing color, typography, and spacing with the U.S. System.

How to use the new v3-based components

Designers

Add the Component Symbol Library in Sketch to be able to use the new v3-based versions of our components.

Developers

Instructions are available for developers to be able to toggle components onto their v3-based version.

Governance rules for using v3-based components

v3-based versions of the components are designed to sit alongside our current v1 based components and Formation. Teams may begin using the new versions of our web-components with the following caveats:

• Do not mix and match different versions (v1 vs. v3) of the same component on the same page. For example, if you were to use the v3-based version of the accordion component on a page, that version must be used throughout that page (and ideally throughout your application as soon as possible).
• Do not mix and match v1 and v3 based form components in the same application flow. For example, if you were to use the v3-based version of the radio button component on the first step in an application, that version must be used on all subsequent steps throughout the flow.

Guidance for v3-based components

Guidance is in the process of being synced with the U.S. System. In the meantime, if you have a specific guidance question or concern with a v3-based component, reach out to the Design System Team.

What is the difference between components, templates, and patterns?

Components

Components are design elements that define a visual style and/or micro-interaction. A component is the smallest unit of measure within a design system. They can be considered concrete, a finite list: Button, accordion, table, etc.

Templates or Page layouts

Templates, or page layouts, compose components within a single page. A layout can contain multiple variations of a component depending on the context.

Patterns

Patterns incorporate one or more page layouts and components to create an interaction that can span multiple pages, a short or long time span, and potentially even multiple channels. Patterns might be unique to a site or an application and may evolve with changes in technology or after competitive analysis.

A pattern is more than the sum of its parts. Patterns are solutions. In the Design System, patterns demonstrate how design, content strategy, reusable components, and accessibility can be put together to solve common problems that all Veterans may experience on VA.gov.

Create or update a component

If you have a new component, or an update to an existing component, consider contributing back to the design system. Reach out to the Design System Team if you have questions.

Create or update a component