@nasa-hds/core
v0.10.0
Published
NASA Horizon Design System (HDS) Core — design tokens, base styles, and USWDS theme configuration.
Downloads
466
Readme
@nasa-hds/core
Pre-1.0: API and class names may change between minor versions.
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/uswds3.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
npm install --save-exact @nasa-hds/corePin the exact version while HDS is pre-v1.0: minor releases can rename custom properties and change component styling, so you want upgrades to happen when you choose.
@uswds/uswds is a peer dependency that npm 7 and later installs for you automatically. Install it explicitly (npm install --save-exact @nasa-hds/core @uswds/uswds) only when you want to pin its version yourself, or when your tooling does not auto-install peers. See Installation for the full setup.
What Ships
dist/
css/
hds.min.css # Required: all USWDS components + HDS theme
hds-uswds.min.css # Optional: USWDS utility classes (.padding-*, etc.)
hds-dataviz.min.css # Optional: data visualization color palettes
assets/
fonts/ # Inter, DM Mono, Public Sans (woff2)
img/ # USWDS images and HDS icons
js/
uswds-init.min.js # Runs early in <head>; readies interactive components (unmodified USWDS)
uswds.min.js # Component behavior; loaded deferred (unmodified USWDS)
src/
scss/ # Public Sass API: tokens, mixins, theme configUsage
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
Forward HDS Core once in your entry point:
@forward '@nasa-hds/core/scss';Then @use '@nasa-hds/core/scss' as *; in each of your own Sass files to reach HDS tokens, USWDS functions, and HDS mixins. Configure the two Sass load paths and forward before your own USWDS-touching Sass. See the Sass Configuration guide for the full setup.
Bundle Sizes (gzipped)
| File | Size | Notes |
| --------------------- | ------ | ----------------------------------------- |
| hds.min.css | 46 KB | Required; HDS/USWDS styles and components |
| hds-uswds.min.css | 47 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 checksSee 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
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.
