Component proposal: Chart Library #6534

Component name

Chart Library
Chart Framework
Graph LIbrary

Component description

A chart library is a collection of reusable, standardized data visualization components — such as line charts, bar charts —that ensure consistency, accessibility, and ease of use across products.

Why USWDS needs this component

A chart library enables data visualization for communicating program performance, publishing research findings, and increasing transparency to the public.
Having a chart library would

• standardize, accessible visualizations that meet federal requirements
• enable consistency and trust in how government communicates data
• improve efficiency, reducing the burden on teams by offering ready-to-use patterns
• improve flexibility, ensuring charts work seamlessly with USWDS tokens, components, and theming

How the component works

The VA Clinical Design System has two charts available including the line and bar charts. The implementing product team will provide the data to enable visualization. The chart supports:

• Single or Multiple Series: Display one or more lines or bars to compare different data sets
• Customizable Axes: Both X and Y axes can be labeled for clarity
• Legend: A legend differentiates between multiple series, using distinct colors, shapes, or styles
• States: Includes hover and focus states, with tooltips on hover to display precise data values
• Reference lines: used to communicate thresholds, targets, or normal ranges

Real-world examples

Government Sites	Line Chart	Bar Chart
CDC > National Health and Nutrition Examination Survey
Federal Reserve
U.S Census Bureau

When to use this component and when to consider something else

Line Chart

Use a Line Chart in clinical settings when you need to:

• Track Patient Vital Signs Over Time: Visualize trends in heart rate, blood pressure, respiratory rate, or temperature to monitor patient stability or response to treatment.
• Monitor Lab Results or Biomarkers: Show fluctuations in blood glucose, cholesterol, or other lab values, making it easier to detect patterns or anomalies.
• Compare Pre- and Post-Treatment Outcomes: Illustrate changes in test results, such as improvement in kidney function or reduction in inflammation markers, before and after an intervention.
• Display Disease Progression or Recovery: Track the course of chronic conditions (e.g., Crohn’s disease, diabetes) and communicate expected outcomes or risks.

Avoid line charts when:

• Display Categorical or Static Data: Presenting categorical or one-time data like diagnosis types, patient gender distribution, or insurance types (use a different type of chart).
• Visualize Infrequent or Irregular Data Points: The data is infrequent or not continuous, making trends misleading or hard to interpret.
• Show a Snapshot or Single-Point Data: You need to show a snapshot of current patient data rather than progress or history (use cards, tables, or bar charts instead).

Bar Chart

Use a Bar Chart in clinical or operational settings when you need to:

• Compare values across categories: Visualize how data points differ by group (e.g., risk types, site locations, medications).
• Show snapshots of data: Display values at a single point in time or over defined intervals (e.g., patient counts per department).
• Highlight relative differences: Emphasize the magnitude between categories in a format that’s scannable and easy to interpret.
• Display disease progression or recovery: Track the course of chronic conditions (e.g., Crohn’s disease, diabetes) and communicate expected outcomes or risks.

Avoid bar charts when:

• Showing trends over time: Use a line chart instead if you need to visualize change over a continuous time range.
• Needing stacked comparisons: This bar chart does not support stacked bars. Use a different chart type if visualizing part-to-whole relationships.

Usability considerations

Line Chart

• Keep it Simple: Limit to 4 lines per chart to avoid clutter and ensure readability.
• Consistent Scales: Use the same scale for axes when comparing multiple charts or series.
• Label Clearly: Ensure axes, series, and data points are well-labeled.
• Appropriate Intervals: Choose time or category intervals that make trends clear but do not introduce unnecessary noise.
• Legend Use: Always provide a clear legend when displaying multiple series, and differentiate lines and shape with more than just color (e.g., square or circles).
• Start Axes at Zero: Where possible, start the Y-axis at zero to avoid misleading trends.

Accessibility considerations

Keyboard navigation:

• tab and shift+tab to enter and exit the chart
• arrow keys to navigate through the data points

Screen readers:

• hidden chart description to provide the objective of the chart
• hidden table as an alternate to the data points in the chart
• data can also be read from each data point

Responsiveness

• resizing the screen or on smaller devices, the text will wrap on the title and the legend
• the chart will compress at tablet breakpoint. At mobile breakpoint, the chart stops compressing and reveals a horizontal scrollbar to ensure readability

Links

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

Who’s involved

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