Data Visualization: Token Bridge & Library Theme Configs (Group B)

[abbybowman]

Feature name

Data Visualization: Token Bridge & Library Theme Configs

Feature area

Design tokens (colors, typography, spacing)

Describe the idea

Ship hds-dataviz-tokens.mjs as the single source of truth for all dataviz design values, plus config/theme files for Highcharts, Plotly, matplotlib, Tableau, and Power BI. Files live in a themes/ directory within @nasa/hds-core, accessible via npm subpath exports (JS consumers) or direct download (Python/BI consumers).

Architecture

Source of truth flow:

DataVisualizationPalettes.stories.js     (existing — hex values)
            │
            ▼
hds-dataviz-tokens.mjs                   (B1 — canonical JS export)
    ╱       │       ╲          ╲              ╲
   ▼        ▼        ▼          ▼              ▼
.mplstyle  .json    .js       .tps           .json
(B2)      (B4)    (B3)       (B5)           (B6)
matplotlib Plotly  Highcharts Tableau      Power BI

All downstream configs are mechanical translations of the same values in different formats.

Packaging — subpath exports (decided):

{
  "exports": {
    ".": "./scss/index.scss",
    "./themes/tokens": "./themes/hds-dataviz-tokens.mjs",
    "./themes/highcharts": "./themes/hds-highcharts-theme.js",
    "./themes/plotly": "./themes/hds-plotly-template.json",
    "./themes/matplotlib": "./themes/hds.mplstyle",
    "./themes/tableau": "./themes/hds-tableau.tps",
    "./themes/powerbi": "./themes/hds-powerbi.json"
  },
  "files": ["scss/**", "themes/**"]
}

What's Included

Task B0: Package Architecture — Subpath Exports (S)

• Create themes/ directory
• Add exports mappings to package.json
• Add themes/** to files array
• Verify subpath imports work in Node.js and common bundlers (Vite, webpack)
• Verify existing SCSS imports are unaffected

Task B1: hds-dataviz-tokens.mjs (S)

Single source of truth ES module. All other Group B files derive from this.

// Conceptual structure
export const categorical = ['#hex1', '#hex2', /* ...12 */];
export const categoricalDark = ['#hex1', '#hex2', /* ...12 */];
export const sequential = {
  reds: ['#hex1', /* ...9 steps */],
  // ...11 families
};
export const diverging = {
  name1: ['#hex1', /* ...steps */],
  // ...3 palettes
};
export const fonts = {
  title: "'Inter', sans-serif",
  body: "'Public Sans', sans-serif",
  mono: "'DM Mono', monospace",
};
export const motion = {
  appear: 1000,
  transition: 500,
  easing: 'cubic-bezier(0.30, 0, 0.20, 1)',
};
export const axis = {
  gridlineColor: '#hex',
  lineColor: '#hex',
  labelColor: '#hex',
};

Hex values from DataVisualizationPalettes.stories.js (existing source of truth).

Pre-work: Extract diverging palette combinations from Figma (which 3 hue pairings, step counts, midpoint color).

Task B2: hds.mplstyle — matplotlib (XS, good-first-issue)

Standard matplotlib rcParams file (~30 lines):

axes.prop_cycle: cycler('color', ['hex1', 'hex2', ...])
font.family: sans-serif
font.sans-serif: Public Sans, DejaVu Sans
axes.titleweight: bold
axes.titlesize: 14
axes.labelsize: 10
axes.edgecolor: #hex
axes.grid: True
grid.color: #hex
grid.linewidth: 0.5
lines.linewidth: 2
figure.facecolor: white
axes.facecolor: white
axes.spines.top: False
axes.spines.right: False

Consumer usage:

plt.style.use('./path/to/hds.mplstyle')

Depends on B1 for canonical values.

Task B3: hds-highcharts-theme.js (S)

Highcharts setOptions() config (~50 lines):

export default {
  colors: [/* 12 categorical */],
  chart: {
    style: { fontFamily: "'Public Sans', sans-serif" },
    animation: { duration: 1000 },
    zoomType: 'xy',
  },
  title: { style: { fontFamily: "'Inter', sans-serif", fontWeight: 'bold' } },
  xAxis: { gridLineColor: '#hex', labels: { rotation: 0 }, crosshair: true },
  tooltip: { /* styling */ },
  plotOptions: {
    series: { states: { inactive: { opacity: 0.3 } } },
    bar: { borderRadius: 0, borderWidth: 1, pointPadding: 0.25 },
  },
};

Consumer usage:

import hdsTheme from '@nasa/hds-core/themes/highcharts';
Highcharts.setOptions(hdsTheme);

Pre-work: Pin supported version (recommend Highcharts 11+). Depends on B1.

Task B4: hds-plotly-template.json (S)

Plotly template (~80 lines). Works for both Plotly.js and Plotly.py:

{
  "layout": {
    "colorway": ["#hex1", "#hex2"],
    "font": { "family": "Public Sans, sans-serif" },
    "title": { "font": { "family": "Inter, sans-serif", "weight": "bold" } },
    "xaxis": { "gridcolor": "#hex", "linecolor": "#hex" },
    "yaxis": { "gridcolor": "#hex", "linecolor": "#hex" },
    "bargap": 0.5,
    "transition": { "duration": 500 }
  }
}

Consumer usage (JS):

import hdsTemplate from '@nasa/hds-core/themes/plotly';
Plotly.newPlot('chart', data, { template: hdsTemplate });

Consumer usage (Python):

import json
with open('hds-plotly-template.json') as f:
    hds = json.load(f)
fig.update_layout(template=hds)

Pre-work: Pin supported version (recommend Plotly 5+). Depends on B1.

Task B5: hds-tableau.tps (XS)

Tableau XML theme file (~40 lines):

<?xml version='1.0'?>
<workbook>
  <preferences>
    <color-palette name="HDS Categorical" type="regular">
      <color>#hex1</color>
      <!-- ...12 colors -->
    </color-palette>
    <color-palette name="HDS Sequential Reds" type="ordered-sequential">
      <!-- ...9 steps -->
    </color-palette>
    <!-- ...all 11 sequential + 3 diverging palettes -->
  </preferences>
</workbook>

Note: Tableau .tps controls color palettes only. Font/axis styling requires manual formatting — document on Storybook setup page.

Consumer usage:

1. Download from Storybook docs page
2. Place in My Tableau Repository/Preferences.tps
3. Restart Tableau Desktop
4. HDS palettes appear in color palette dropdown

Depends on B1.

Task B6: hds-powerbi.json (XS)

Power BI JSON theme (~60 lines):

{
  "name": "HDS Core",
  "dataColors": ["#hex1", "...12 categorical"],
  "textClasses": {
    "title": { "fontFace": "Inter, Segoe UI, sans-serif", "fontWeight": "bold" },
    "label": { "fontFace": "Public Sans, Segoe UI, sans-serif" },
    "callout": { "fontFace": "DM Mono, Consolas, monospace" }
  }
}

Note: Fonts must be available on user's machine or Power BI Service environment. Document Segoe UI as fallback on Storybook setup page.

Consumer usage:

1. Download from Storybook docs page
2. Power BI Desktop: View → Themes → Browse → select file
3. Or admin pushes via Power BI admin portal for org-wide adoption

Depends on B1.

Pre-Work Before Building

Item	Blocker For	Who
Extract diverging palette combinations from Figma (3 hue pairings, step counts, midpoint)	B1	Contributor with Figma access
Build diverging palette CSS custom properties + Storybook stories	B1	Contributor (follow existing sequential pattern)
Pin supported library versions	B3 (Highcharts 11+), B4 (Plotly 5+)	Contributor
Verify Tableau .tps format	B5	Contributor with Tableau Desktop access

Storybook Documentation Deliverables

Page	Audience	Content
Tableau Setup	Data analysts	Download link, installation steps with screenshots, palette preview, manual font/axis guidance
Power BI Setup	Data analysts	Download link, desktop + admin portal steps, font installation note
Plotly Setup	Web devs + Python scientists	npm import + Python file download examples, before/after
Highcharts Setup	Web devs	npm import, setOptions() code, before/after
matplotlib Setup	Python scientists	File download, plt.style.use() code, example output, font note

These pages live alongside the existing React Setup page and can be linked directly.

Use case / user story

Multiple user stories:

Highcharts developer (6 known sites — giovanni, fermi, gs671-suske, hitide, neoproperties, oltaris):
As a developer maintaining a Highcharts dashboard on a NASA science site, I want to import @nasa/hds-core/themes/highcharts and call Highcharts.setOptions(hdsTheme) so that all my charts (colors, fonts, gridlines, bar spacing, tooltips, animation) match HDS standards with a single line of code.

matplotlib / Jupyter scientist (large hidden audience behind JupyterHub):
As a scientist generating charts in Jupyter notebooks, I want to call plt.style.use('hds') so that every chart I produce — in notebooks, papers, and dashboards — uses NASA's official colors and typography without manually setting them on each plot.

Plotly.py scientist:
As a scientist building interactive Plotly charts in Python, I want to apply an HDS template so my visualizations match the design system whether they're viewed in a notebook, embedded on a web page, or exported to an image.

Tableau analyst (large internal audience):
As a data analyst building Tableau dashboards for NASA stakeholders, I want to import an HDS color palette into Tableau Desktop so that all my visualizations use consistent, accessible, on-brand colors without manually entering hex codes.

Power BI analyst:
As an analyst creating Power BI reports, I want to apply an HDS theme file so that my reports use official NASA colors and typography, and so that my organization's admin can push this theme to all users centrally.

D3 developer needing resolved values:
As a D3 developer who needs hex values for canvas rendering or image export (where CSS custom properties don't resolve), I want to import color arrays from @nasa/hds-core/themes/tokens so I have a single source of truth that stays in sync with the SCSS tokens.

Primary audience

Other (describe in your use case above)

Is this already in the HDS Figma library?

✅ Yes — fully specced in HDS Figma

Figma reference

Data Visualization page — Color (palettes), Typography (font use, hierarchy), Style (bar gaps, border widths, line styles), Motion (animation timing), Architecture (axis/gridline styling).

Implementation maturity

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

Prior art details

• Salesforce SLDS — ships design tokens as JS/JSON/SCSS with data viz color guidelines. Closest parallel but doesn't ship library-specific configs.
• IBM Carbon — @carbon/charts wraps D3 in components. Much heavier than config files.
• Shopify Polaris Tokens (@shopify/polaris-tokens) — uses npm subpath exports for different output formats (CSS, JSON). Our packaging approach follows this model.
• Matplotlib built-in styles — plt.style.use('ggplot'), plt.style.use('seaborn') etc. demonstrate the .mplstyle pattern is well-established and familiar to scientists.
• Highcharts official themes — highcharts/themes/dark-unica.js etc. demonstrate the setOptions() theme pattern.
• No other USWDS theme layer has attempted library-specific chart theme configs. HDS Core would be first.

Audience validated via Wappalyzer scan (March 2025) of ~97 NASA sites with JavaScript graphics detected. ~18-20 use actual charting libraries: D3 (10, 43%), Highcharts (6, 26%), Chart.js (3-4, 15%), Plotly (3, 13%), Bokeh (2, 9%). These numbers significantly undercount: Wappalyzer can't detect libraries behind reverse proxies, JupyterHub, or Tableau/Power BI platforms. The Python/BI audience is estimated 10-50× larger than what's visible in web scans.

Relationship to USWDS

Extends USWDS with something it doesn't provide

Potential breaking change?

No — purely additive

Alternatives considered

1. Ship theme configs in a separate package (@nasa/hds-dataviz-themes) — Monorepo with independent versioning. Trade-off: cleaner separation but adds monorepo tooling complexity, two publish processes, and friction for consumers who need two npm installs. Decided against for now — can migrate later if scale justifies it.
2. Ship only the JS token export, no library configs — Developers manually apply tokens to each library's API. Trade-off: less maintenance for us but shifts significant effort to every consumer site. The Figma spec's style opinions (bar gaps, border widths, gridline colors, animation timing) would remain documentation-only, unenforceable.
3. Ship full charting component library (Carbon model) — Wrap D3 in React/Vue components. Trade-off: maximum control but massive scope, ongoing maintenance, and out of scope for CSS-first HDS Core architecture.
4. JSON-as-source-of-truth / Style Dictionary — All tokens sourced from JSON, generated to every output format. Trade-off: eliminates manual sync but is a major architecture change affecting all HDS tokens, not just dataviz. Deferred as a separate architecture decision.

Additional context

This is the second of two related ideas. #44ships the CSS foundation. Group B (this idea) ships config files that encode the same design opinions in each library's native format. Together they implement the full Figma Data Visualization spec across all major audiences.

Audience coverage — incremental over Group A:

Audience	Group A Alone	After Group B
D3 developers	✅ Full	✅+ Resolved hex for canvas/export
Highcharts (6 sites)	⚠️ Shell only	✅ Full
Plotly.js (~3 sites)	⚠️ Shell only	✅ Full
Plotly.py / Jupyter	❌ Not served	✅ Full
matplotlib / Jupyter	❌ Not served	✅ Full
Tableau (large internal)	❌ Not served	✅ Full
Power BI (large internal)	❌ Not served	✅ Full
Chart.js (3-4 sites)	⚠️ Shell only	⚠️ DIY from token export
Bokeh (2 sites)	❌	⚠️ DIY from token export

Chart.js and Bokeh dedicated configs are deferred to the Ideas backlog — build when adoption signal grows.

Permanently underserved:

• FusionCharts (1 site, techport.nasa.gov) — proprietary, can DIY from token export
• Three.js / 3D viz (~10 sites) — not statistical charting, not target audience
• CMS-bound sites — heading to flagship WordPress CMS, charting is plugin-driven. Flag to CMS platform team.

Would you contribute to this?

Partially — I could help with design/research/testing