Design tokens

What are design tokens?

Design tokens are reusable names for the visual styles used throughout the VA Design System. The VA Design System builds on the design tokens provided by the U.S. Web Design System (USWDS), adding semantic and component tokens that adapt those foundational values for VA experiences.

Instead of hard-coding values like colors, spacing, typography, or shadows into every application, teams reference design tokens. Each token gives a reusable name to a visual style, allowing designers, developers, and tooling to reference the same concept without depending on its underlying value. By referencing the token instead of the value itself, applications automatically receive updates when the design system changes.

For example, instead of writing:

padding: 16px;
font-size: 17px;
color: #d54309;

You would use:

padding: var(--vads-spacing-2);
font-size: var(--vads-font-size-body-medium);
color: var(--vads-color-error);

Applications simply reference the appropriate design token rather than its underlying value.

The token listings in this section are generated directly from the @department-of-veterans-affairs/css-library package, so they always reflect the tokens that ship in the current release.

Generated from css-library v0.34.1 (Tue, 04 Aug 2026 20:19:43 GMT) — 376 tokens.

Why use design tokens?

Design tokens let teams build consistent experiences without needing to memorize or duplicate visual values.

By referencing tokens instead of hard-coded values, teams can:

• Build consistent experiences across VA products.
• Share the same design language across design, development, and tooling.
• Apply visual styles consistently across components and applications.
• Make changes in one place instead of many.
• Improve accessibility and visual consistency over time without requiring every application to update individual values.

Types

The VA Design System organizes tokens into three types. As tokens become more specific, they move from foundational or primitive values to semantic meaning to component-specific decisions.

Primitive

Primitive tokens are the foundational building blocks of the design system. Most primitive tokens originate from the U.S. Web Design System (USWDS) and define raw values such as colors, spacing, typography, elevation, and opacity. Primitive tokens answer the question:

What values are available?

Semantic

Semantic tokens describe the purpose of a design decision rather than the underlying value.

For example, a semantic token like vads-color-error communicates that the color is intended for error states. The underlying color may change over time, but the meaning—and where the token should be used—remains the same.

Semantic tokens answer the question:

What is this value used for?

Component

Component tokens are scoped to a specific component and represent decisions specific to that component.

Rather than requiring consumers to understand which colors, spacing, or typography a component uses internally, component tokens provide a stable interface for styling that component.

Component tokens answer the question:

How should this component be styled?

Choosing the right token

When selecting a token, work from the design problem you are trying to solve.

1. Start with the type of style you’re defining. Determine whether you’re styling color, spacing, typography, elevation, layout, or another design foundation.
2. Choose the token that best matches the design intent. Select tokens based on their meaning, not simply because they match a particular value.
3. Use the most specific token available.
   • Use component tokens when styling a specific component.
   • Otherwise, use semantic tokens that describe the purpose of the design decision.
   • Use primitive tokens only when a semantic or component token does not exist.
4. Use preferred tokens. When multiple tokens represent the same value, choose the preferred token for new and updated work.
5. Don’t approximate. If an appropriate token doesn’t exist, don’t substitute a “close enough” token. Consider whether a new token should be introduced instead.

Understanding token names

Token names become more specific from left to right. Each part adds information about what the token represents.

For example:

vads-color-error-dark

vads

System (namespace)

color

Category

error

State

dark

Scale

vads-forms-spacing-vertical-stack-default

vads

System (namespace)

forms

Group

spacing

Category

vertical-stack

Concept

default

Variant

Not every token includes every part of the naming taxonomy. Tokens include only the parts needed to describe what they represent.

Token naming conventions

A few naming conventions appear throughout the token library.

• p represents a decimal point in a numeric scale.
  • vads-spacing-1p5 = 1.5 units (12px)
  • vads-spacing-0p5 = 0.5 units (4px)
• neg- indicates a negative value.
  • vads-spacing-neg-2

Token naming taxonomy

The VA Design System follows a naming taxonomy inspired by Nathan Curtis’s work on design token naming. This taxonomy defines the vocabulary used to construct token names, making them consistent, predictable, and scalable. While no single token uses every part of the taxonomy, together these concepts provide the building blocks for naming every token.

Read more about Naming Tokens in Design Systems.

Namespace

System

Defines which design system a token originates from. :

Current values include:

• uswds — U.S. Web Design System primitive tokens.

• vads — VA Design System tokens.

Domain

Reserved for future use. May define large areas of related tokens that span multiple systems (for example, health or benefits).

Object

These levels describe the UI object a token applies to.

Group

Defines a family of related components.

Examples include forms and navigation.

Component

Defines a specific component.

Element

Defines an element within a component.

Base

These levels describe the design attribute represented by the token.

Category

High-level grouping.

Examples include color, elevation, typography, layout, and spacing.

Concept

Groups related tokens within a category.

Examples may include action, hub, inset, or vertical.

Property

Defines the design property represented by the token.

This is often synonymous with the corresponding CSS property.

Modifiers

Modifiers provide additional context.

Variant

Defines variations that distinguish different use cases.

Examples include primary, secondary, tertiary, heading, body, and default.

State

Defines interactive states.

Examples include hover, press, focus, and error.

Scale

Places a token within an intentional, ordered range of values.

Examples include heading levels (1–5) or t-shirt sizes (small, medium, large).

Mode

Reserved for future use. Will define the visual context in which the token should be used (for example light and dark modes).

Token categories

Now that you understand how tokens are named and organized, you can browse the available tokens by design foundation. Use the sub-pages to find tokens for a particular design foundation. Each category documents the available tokens, their values, and guidance for when and how they should be used.