Component proposal: Single Value Visualization (SVV) #6526

Component name

• Single Value Visualization
• Single Value Indicator
• Single Value Card

Component description

The Single Value Visualization (SVV) is a compact visual component that highlights one key metric, value, or indicator. It is designed to stand out for quick, high-impact communication of important clinical or operational data.

Why USWDS needs this component

Government data can be often complex and voluminous. By highlighting one specific number—such as the current unemployment rate, the number of new COVID-19 cases, or the total number of registered voters—the component allows users to quickly grasp the most critical information without having to interpret a chart or table.

How the component works

The SVV supports three variants:

Basic	With supporting text	With visual indicator
displays the title and primary value only	adds a secondary line of text for context	adds a color bar beneath the value to emphasize direction, risk, or significance, along with supporting text

Real-world examples

Government Sites	Screenshot
USA Spending
U.S. Federal Housing
US Federal Housing

When to use this component and when to consider something else

When to use:

• call out a single, high-priority metric in a dashboard, report, or detail view
• show indicators in a compact format
• provide context on a value by indicating trends or thresholds

When not to use:

• multiple related metrics need comparison (use tables or charts instead)
• rich visualizations are needed to show trends over time
• content is complex and cannot be captured in one supporting line

Usability considerations

• Keep it focused: Only use SW for the most critical, standalone metrics.
• Be concise: Use short labels and values that are immediately scannable.
• Provide context: Where relevant, add supporting text (e.g., percentage change, status).
• Use indicators carefully: Apply the color bar only when a visual cue adds clarity, and ensure the chosen color has sufficient contrast to meet accessibility standards (WCAG AAA - Graphical objects). Use the information, warning, error, and success color palette provided by the design system for consistency.
• Maintain accessibility: Do not rely on color alone, pair color bars with supporting text to ensure information is clear for all users.
• Consistent placement: Use SWs in grids or aligned layouts to make multiple values easier to scan

Accessibility considerations

• Color bar: The color bar is purely presentational and it will be hidden from screen readers.
  This prevents redundant or confusing information for assistive technology users.
• Value context: The value is associated with its title and supporting text. This ensures that screen reader users hear the value with full context (e.g., "5-year ASCVD Risk 35.84%, High by 10%" rather than only "35.84%").
• Do not rely on color alone: Always pair the visual indicator (color bar) with supporting text to communicate meaning.
• Contrast: Ensure that all colors used in the supporting text and indicators meet WAG AAA - Graphical objects and user interface components contrast requirements.

Links

• Figma - Clinical Design System UI Kit
• Storybook - Engineer Documentation
• VA Clinical Design System Documentation

Who’s involved

@aklausmeier VA Design and Product Owner
@sangmee-specht Engineer
@helene-mccarron Tech Lead
@juanpasten-tw Design Lead
@adlco Product Manager Lead
@obliviga Accessibility Specialist Engineer
@bennguyenhcd Researcher