Components

Upgrade to U.S. Web Design System v3

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.

All teams must now be using the v3 versions of our web-components. The Design System Team continues to roll out the new v3-based System including syncing color, typography, and spacing with the U.S. System.

How to use the new v3-based components

Designers

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

Migration strategy

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

Governance rules for using components

To ensure consistency and quality across our applications, all teams must follow these rules when using design system components:

• Do not use v1 components. Only use v3 components in your applications and pages. Using a v1 component will be considered a launch-blocking issue and must be fixed before your team can launch to production.
  • The only exception is if there is no v3 equivalent available.
• If your team is using a user interface element outside of the design system web components, that is coded to look and function like a design system web component, that is considered an imposter component and will be listed as a violation at your Staging Review. Any user interface element that can use a design system web component should use it. Any use of an imposter component will be considered a launch-blocking issue and must be fixed before your team can launch to production.
  • Exceptions to this are default links and buttons. HTML elements <button> and <a>, with the appropriate classes added for styling consistency, may be used. This only applies to elements styled as Button - Default and Link - Default variations. HTML elements styled as any other variation will be considered imposter components.

Examples of design system components can be found in Storybook or in this section (components are listed in the side navigation).

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.