@nasa/hds-core

Pre-1.0: API and class names may change between minor versions. Not yet published to npm.

What is HDS Core?

NASA Horizon Design System (HDS) Core is a CSS design system built as a theme layer on top of the U.S. Web Design System (USWDS). It applies NASA brand typography, color, spacing and component styling as required by NASA's web modernization policy NID 2800.147 and design standards.

HDS Core is intended for standalone NASA websites, applications and platforms approved to operate outside of the agency's flagship content management system (www.nasa.gov and science.nasa.gov), as well as microapps and embeds within the flagship that aren't styled by the CMS theme.

Before adopting HDS Core, please read our Getting Started guide to confirm your project aligns with NASA's web modernization and consolidation strategy. Interagency, non-.gov, and other non-NASA-branded sites should use USWDS instead.

Requirements

• Node.js 20+
• npm 10+
• Peer dependency: @uswds/uswds 3.13+

Browser support: > 2%, last 2 versions, not dead (matches USWDS targets; IE not supported)

Documentation

Full documentation, component examples, and integration guides are published in a Storybook at https://nasa.github.io/hds-core/. Key pages include:

• Getting Started: Figure out whether HDS Core is the right tool for your project
• Installation: Technical setup for teams adopting HDS Core
• Guides for existing USWDS sites, React, no-build environments and Sass configuration

Installation

HDS Core is not yet published to npm. Install directly from GitHub:

npm install github:nasa/hds-core @uswds/uswds

What Ships

dist/
  css/
    hds.min.css         # Required: all USWDS components + HDS theme
    hds.min.css.map
    hds-uswds.min.css   # Optional: USWDS utility classes (.padding-*, etc.)
    hds-uswds.min.css.map
    hds-dataviz.min.css # Optional: data visualization color palettes
    hds-dataviz.min.css.map
  assets/
    fonts/              # Inter, DM Mono, Public Sans (woff2)
    img/                # USWDS images and HDS icons
  js/
    uswds.js            # USWDS JavaScript (unmodified)
src/
  scss/                 # Public Sass API: tokens, mixins, theme config

Usage

Required (all sites)

<link rel="stylesheet" href="node_modules/@nasa/hds-core/dist/css/hds.min.css" />

Optional: USWDS utility classes

For sites that rely on USWDS utility classes (.padding-2, .margin-top-3, etc.):

<link rel="stylesheet" href="node_modules/@nasa/hds-core/dist/css/hds-uswds.min.css" />
<link rel="stylesheet" href="node_modules/@nasa/hds-core/dist/css/hds.min.css" />

Load order does not matter. All styles use CSS cascade layers.

Optional: Data visualization

<link rel="stylesheet" href="node_modules/@nasa/hds-core/dist/css/hds-dataviz.min.css" />

Can be loaded standalone without hds.min.css for embedded chart contexts.

Sass API

@use '@nasa/hds-core/scss' as hds;

Exposes HDS tokens, mixins, and USWDS core utilities for use in your own Sass pipeline.

Bundle Sizes (gzipped)

File	Size	Notes
hds.min.css	43 KB	Required; HDS/USWDS styles and components
hds-uswds.min.css	48 KB	Optional; USWDS utility classes
hds-dataviz.min.css	1.2 KB	Optional; HDS data visualization styles

Contributing to HDS Core

npm install
npm run dev    # Sass watch + Storybook
npm test       # Unit tests + USWDS version checks

See CONTRIBUTING.md for guidelines on submitting changes, the public API contract and the versioning policy.

For architecture details and build pipeline documentation, see ARCHITECTURE.md.

License

@nasa/hds-core is released into the public domain under CC0 1.0, except for bundled fonts (SIL OFL 1.1) and NASA trademarks/insignia. See LICENSE.md for full terms and attribution.