@department-of-veterans-affairs/clinical-design-system-single-value-viz

Single Value Visualization

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.

Installation instructions

yarn add @department-of-veterans-affairs/clinical-design-system-single-value-viz npm install @department-of-veterans-affairs/clinical-design-system-single-value-viz

About the Single Value Visualization

The SVV component communicates a single data point in a clear, scannable way. It may include a title, the primary value, and optional supporting text or visual indicators.

The component supports three variants:

• Basic: Displays the title and primary value only.
• With supporting text: Adds a secondary line of text for context (e.g., “Down by 10%”).
• With visual indicator: Adds a color bar beneath the value to emphasize direction, risk, or significance, along with supporting text.

This flexibility allows SVV to adapt to different levels of information density while maintaining readability. When to use the Single Value Visualization

Use SVV when you need to:

• Call out a single, high-priority metric in a dashboard, report, or detail view.
• Show indicators (e.g., risk scores, completion rates, vital sign metrics) in a compact format.
• Provide context on a value by indicating trends or thresholds (e.g., “High by 10%”).

When not to use the component

Avoid using SVV when:

• Multiple related metrics need comparison (use tables or charts instead).
• Rich visualizations (e.g., line charts, bar charts) are needed to show trends over time.
• Context is complex and cannot be captured in one supporting line.

Best Practices

• Keep it focused: Only use SVV 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 SVVs in grids or aligned layouts to make multiple values easier to scan

Accessibility

• 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 WCAG AAA - Graphical objects and user interface components contrast requirements.

Technical Documentation

Props

title*	
A required prop that titles the component.
string
	-	
keyValue*	
A required prop that renders text below the title.
string
	-	
barColor	
An optional prop that serves as a visual indicator of its status and spans the width of the key value's text. Accepts string literals of hexadecimal, RGB/RGBA, and named CSS colors. Invalid colors will cause the bar to not render as well as a console warning.
string
	-	
supportingText	
An optional prop that renders text below the key value and color bar.
string