Data Visualization: CSS Utilities & Chart Wrapper (Group A)

[abbybowman]

Feature name

Data Visualization: CSS Utilities & Chart Wrapper

Feature area

Component patterns (cards, search, archive layouts, etc.)

Describe the idea

Ship CSS utilities and a .hds-chart layout wrapper that implements the Figma Data Visualization spec's UI Shell, color utility classes, D3 integration selectors, tooltip styling, and interaction states. All pure SCSS, feature-flagged behind $hds-enable-dataviz-chart, shipping inside @nasa/hds-core.

What's Included

Task A0: SCSS Feature Flag (XS)

Add $hds-enable-dataviz-chart boolean flag (default false) gating all Group A output. Follows existing pattern of $hds-enable-dataviz for tokens.

Task A1: Categorical Utility Classes + Line Style Utilities (XS, good-first-issue)

• 12 .hds-dataviz-cat-{n} classes mapping fill, stroke, color to existing --hds-dataviz-cat-* custom properties via SCSS loop
• .hds-dataviz-line-dashed and .hds-dataviz-line-dotted with standardized stroke-dasharray values
• .hds-chart rect { rx: 0; ry: 0; } for sharp bar edges per spec
• Automatically dark-mode-aware via existing _scheme-dark overrides
• Pre-work: None — all tokens already exist

Task A2: D3 Structural Selectors (S)

• .hds-chart .tick line, .hds-chart .domain, .hds-chart .axis text targeting D3's well-known generated SVG class names
• Axis/gridline colors from existing HDS color tokens
• font-feature-settings: 'tnum' for tabular figures on axis text
• Public Sans for all chart text
• Pre-work: Verify dark mode token mapping — which --hds-color-* tokens for gridlines, axis lines, axis text

Task A3: .hds-chart Wrapper — Core Layout (M, needs-figma-values)

CSS grid layout shell implementing Figma Architecture → UI Shell. All slots optional — grid collapses gracefully when elements are absent.

┌──────────────────────────────────┐
│ ━━━━━ black top bar ━━━━━━━━━━━ │ border-top
│ [.hds-chart-title]   [controls] │
│ [.hds-chart-subtitle]           │
│ [.hds-chart-filters]            │ (optional — active filter chips)
│ [.hds-chart-tabs]               │ (optional)
├──────────────────────────────────┤
│ [.hds-chart-area]               │ (flexible height)
├──────────────────────────────────┤
│ [.hds-chart-zoom]               │ (optional)
│ [.hds-chart-legend]             │
│ [.hds-chart-description]        │ (optional)
│ [.hds-chart-citation]           │ (optional)
└──────────────────────────────────┘

Typography classes:

• .hds-chart-title — Inter Bold
• .hds-chart-subtitle — Inter Regular, smaller
• .hds-chart-description — body or small text
• .hds-chart-citation — small text, bold "Data source:" label pattern

Controls row: .hds-chart-controls — flexbox, right-aligned, houses existing HDS icon buttons and form elements.

Pre-work: Figma values needed (see Open Questions section below).

Task A4: .hds-chart Wrapper — Responsive Behavior (S)

• Legend flips from below chart to above chart at mobile breakpoint
• Controls row drops below title (own row) at mobile breakpoint
• Description/citation text size reduces at mobile
• Maps to existing HDS Core breakpoints
• Depends on A3

Task A5: .hds-chart Wrapper — Variants and States (S–M)

• .hds-chart--desc-side modifier — two-column grid with description beside chart area
• Loading state: [aria-busy="true"] centers placeholder in chart area
• Motion timing custom properties on .hds-chart scope:
  • --hds-motion-appear: 1000ms
  • --hds-motion-transition: 500ms
  • --hds-motion-curve: cubic-bezier(0.30, 0, 0.20, 1)
• Data table toggle via native <details class="hds-chart-data"> element — no JS required, pairs with existing HDS table component
• Optional: .hds-chart-empty and .hds-chart-error states (spec is silent — needs creative decision)
• Depends on A3

Task A6: Tooltip Styling (S, needs-figma-values)

• .hds-chart-tooltip class for developer-built tooltip divs (common with D3)
• Light and dark variants, palette-aware via _scheme-dark
• Color swatch indicator class for multi-dataset tooltip rows
• font-feature-settings: 'tnum' for numeric values
• Pre-work: Tooltip styling values from Figma (background, border, padding, shadow, border-radius)

Task A7: Hover Opacity Interaction (S)

• Non-hovered series reduce to ~0.3 opacity when any series is hovered
• Transition uses motion timing custom properties from A5
• Selector approach needs validation against real D3 output (:has(), [data-series] convention, or sibling combinators)
• Contributor must build test fixtures and document recommended markup pattern
• Graceful degradation in browsers without :has() (no interaction, no breakage)

Open Questions Requiring Figma Values

Before implementation, these values need to be extracted from the Figma Data Visualization spec. Alternative approach: map everything to closest existing USWDS type scale / spacing tokens for an "80% good enough" first pass, refine after creative review.

Value Needed	Figma Location	Fallback If Unknown
Black top bar thickness	Architecture → UI Shell	border-top: 0.25rem solid
Spacing between layout slots	Architecture → default layout	USWDS spacing units (1, 1.5, 2, 3)
Title font size + line height	Typography + Architecture	USWDS heading-lg or heading-xl
Subtitle font size + line height	Same	USWDS body or small
Description font size	Architecture → Description & Citations	USWDS body or small
Citation font size + style	Architecture → Description & Citations	USWDS small, bold label
Tooltip background, border, padding, shadow, border-radius	Interactions → Tooltips	Match existing HDS component patterns
Tooltip internal text sizes	Interactions → Tooltips variants	USWDS small
Controls row icon sizes + spacing	Architecture → Data Controls	Existing HDS icon button sizes
Legend swatch size, item spacing, text size	Architecture → Legends	12px square swatch, USWDS small text

Design Decisions for Contributor

Decision	Recommendation
Legend: HTML-built vs. library-native?	Ship .hds-chart-legend CSS for HTML legends built outside the chart. D3 devs build their own legends anyway. Highcharts/Plotly devs can opt in or keep library-native.
Empty/error states in scope?	Recommend including in A5 as simple centered text pattern. Spec is silent but practical need is universal.
Hover opacity value	0.3 for inactive elements — industry standard (Carbon uses 0.3, Highcharts defaults 0.2).
D3 hover selector approach	Test against real D3 output in A7, document recommended markup pattern.

Spec Sections Implemented by Group A

• Architecture → UI Shell (all 8 numbered elements)
• Look & Feel → Color (categorical utility classes)
• Look & Feel → Typography (title, subtitle, axis, hero number classes)
• Look & Feel → Style (sharp edges, axis/gridline styling, line variants)
• Look & Feel → Motion (timing custom properties)
• Interactions → Tooltips (container styling, light/dark variants)
• Interactions → Focus (hover opacity reduction)
• Interactions → Filters (chip slot in layout)
• Accessibility → text description (visible + sr-only patterns), data table toggle, focus-visible

What Group A Cannot Implement (Needs Group B or Docs Only)

Spec Guidance	Why	Where It Lives
Bar gap / spacing between bars	Library-internal config	Group B
Border width between pie/stacked segments	Library-internal config	Group B
Crosshair behavior	Library feature	Group B + docs
"Don't angle axis labels"	Library label rotation setting	Group B
Zoom/pan behavior	Library feature	Docs
Animation choreography (stagger, draw direction)	Imperative JS	Docs
Chart type guidance (no 3D, pie caution)	Design decision	Docs
Keyboard nav within chart SVG	Deep library territory	Docs (link WAI-ARIA Graphics Module)

Use case / user story

Multiple user stories served:

• As a developer starting a new greenfield NASA data site or microapp, I want a pre-built chart layout shell and color utilities so that I can focus on the visualization logic rather than reinventing the UI chrome around every chart.
• As a developer needing to restyle an existing D3 visualization, I want to wrap my chart in
  and swap hardcoded color attributes for .hds-dataviz-cat-{n} classes so that my chart matches HDS visual standards with minimal code changes, automatically supports dark mode, and has a consistent title/legend/description layout.
• As a developer needing to restyle an existing JS charting library (Highcharts, Plotly, Chart.js, etc.), I want at minimum a consistent layout wrapper (title, controls, legend, description) around my chart div so that the page-level presentation matches HDS even before library-specific theme configs are available (Group B).

Primary audience

Front-end developers

Is this already in the HDS Figma library?

✅ Yes — fully specced in HDS Figma

Figma reference

Data Visualization page in HDS Figma — covers Architecture (UI Shell), Look & Feel (Color, Typography, Style, Motion), Interactions, and Accessibility sections.

Implementation maturity

🔍 Seen elsewhere — exists in another design system or library (not NASA)

Prior art details

No other USWDS theme layer has attempted chart CSS utilities. Industry comparisons:

• IBM Carbon (@carbon/charts) — full React/Vue/Angular charting components wrapping D3. Much heavier approach than what we're proposing. Out of scope for CSS-only HDS Core.
• Shopify Polaris (@shopify/polaris-viz) — same pattern, D3 under the hood.
• Adobe Spectrum (@adobe/react-spectrum-charts) — uses Vega/D3 internally.
• Salesforce SLDS — ships design tokens as JS/JSON/SCSS + data viz color guidelines. Closest to our approach but ships no chart-specific CSS.
• UK GOV.UK — publishes accessible chart guidance + color palettes. No CSS.

Our approach is a middle ground: more actionable than token-only systems (SLDS, GOV.UK) but lighter than full component libraries (Carbon, Polaris). The key insight is that D3 generates SVG with predictable, well-known class names (.tick, .domain, .axis) that CSS can target directly, so a CSS-only design system can meaningfully style D3 chart internals without JavaScript.

Relationship to USWDS

Extends USWDS with something it doesn't provide

Potential breaking change?

No — purely additive

Alternatives considered

1. Full charting component library (Carbon model) — wraps D3 in React/Vue components. Trade-off: maximum control but massive ongoing maintenance burden, out of scope for CSS-only architecture.
2. Tokens only, no CSS utilities (current v1.0 state) — developers get color values but no layout, typography, or interaction CSS. Trade-off: minimal maintenance but spec guidance is unenforceable.
3. Skip chart wrapper, only ship utility classes — partial solution. Trade-off: colors are consistent but layout (title, legend, controls) remains inconsistent across sites.

Group A as proposed hits the 80% sweet spot: consistent layout + color + typography + interactions via CSS, without the maintenance burden of a component library.

Additional context

This is the first of two related ideas. Group A (this idea) ships the CSS foundation. #45 would then ship config files for Highcharts, Plotly, matplotlib, Tableau, and Power BI that encode the same design opinions in each library's native format. Together they cover the full Figma spec for all major audiences.

Audience coverage after Group A ships:

Audience	Coverage
D3 developers	✅ Fully served
Greenfield sites	✅ Fully served
Highcharts / Plotly / Chart.js	⚠️ Layout shell only — chart internals need Group B
matplotlib / Jupyter scientists	❌ Not served — need Group B
Tableau / Power BI analysts	❌ Not served — need Group B

Would you contribute to this?

Yes — I could submit a PR