v0.8.0

Migration: CSS Custom Property Renames

Upgrading from 0.7.x? Several HDS CSS custom properties were renamed or removed in this release. If you reference any --hds-* properties directly in your own stylesheets, the renames below fail silently (your var() resolves to nothing or a fallback), so it's worth a find-and-replace before upgrading. Sass consumers should also skim the Focus Ring and Typography sections; those break at compile time, which is loud and easy to fix.

Color

• --hds-palette-error-border → --hds-palette-error-indicator

Border width (component-first naming)

• --hds-border-width-{accordion, button, card, input-tile, input-select, input-state, pagination, summary, table} → --hds-{component}-border-width

Border width scale (removed)

• --hds-border-size-1px → --hds-border-width-thin
• --hds-border-size-2px → --hds-border-width-thick
• --hds-border-size-{0, 05, 1, 105, 2}: no replacement (inline a literal value)

Border radius (component-first naming)

• --hds-border-radius-{button, card, checkbox, input-tile, modal, pagination, summary} → --hds-{component}-border-radius

Border radius scale (removed)

• --hds-border-radius-0 → --hds-border-radius
• --hds-border-radius-sm → --hds-border-radius-control
• --hds-border-radius-{md, lg, xl}: no replacement
• --hds-border-radius-pill: no replacement (use a literal value or define your own in @layer site)

Line height

• --hds-line-height-{body, heading, …} → --hds-line-height-1 through --hds-line-height-6 (USWDS scale numbering)

Minor Changes (inc. breaking changes for pre-v1.0)

• 72384f3: Border width token refactor

  New: $hds-border-width-thin (1px) and $hds-border-width-thick (2px). Role-based Sass variables that feed USWDS theme settings directly and emit --hds-border-width-thin / --hds-border-width-thick CSS custom properties for consumers without a Sass pipeline. Added to tokens.json as border.width.thin / border.width.thick.

  Breaking: $hds-border-sizes map and --hds-border-size-* CSS properties removed. The value-named USWDS-style scale was never used by HDS components. Migrate: --hds-border-size-1px → --hds-border-width-thin; --hds-border-size-2px → --hds-border-width-thick; all other entries (0, 05, 1, 105, 2) have no replacement and were USWDS mirrors not present in the HDS spec. The corresponding border.width.* token keys in tokens.json are replaced by border.width.thin / border.width.thick.

  Breaking: $hds-width-settings map removed. The per-component map only existed to feed USWDS theme settings; $hds-border-width-thin / $hds-border-width-thick now do this directly.

  Breaking: --hds-border-width-{component} renamed to --hds-{component}-border-width. All nine component CSS custom properties now follow component-first naming:

  Old	New
  --hds-border-width-accordion	--hds-accordion-border-width
  --hds-border-width-button	--hds-button-border-width
  --hds-border-width-card	--hds-card-border-width
  --hds-border-width-input-tile	--hds-input-tile-border-width
  --hds-border-width-input-select	--hds-input-select-border-width
  --hds-border-width-input-state	--hds-input-state-border-width
  --hds-border-width-pagination	--hds-pagination-border-width
  --hds-border-width-summary	--hds-summary-border-width
  --hds-border-width-table	--hds-table-border-width

• 9fd750b: Border radius token refactor

  New: $hds-border-radius (0px) and $hds-border-radius-control (2px). Role-based Sass variables establishing HDS's two border-radius values: sharp corners for most components, subtle rounding for small interactive controls. Feed USWDS theme settings directly and emit --hds-border-radius / --hds-border-radius-control as CSS custom properties for consumers without a Sass pipeline. Added to tokens.json as border.radius.default / border.radius.control.

  Breaking: $hds-border-radii map and --hds-border-radius-* scale removed. The value-named USWDS-style scale was never used by HDS components. Migrate: --hds-border-radius-0 → --hds-border-radius; --hds-border-radius-sm (2px) → --hds-border-radius-control; --hds-border-radius-md, -lg, -xl have no replacement. The corresponding scale keys in tokens.json are replaced by border.radius.default / border.radius.control.

  Breaking: $hds-radius-settings map removed. The per-component map only existed to feed USWDS theme settings; $hds-border-radius / $hds-border-radius-control now do this directly.

  Breaking: --hds-border-radius-{component} renamed to --hds-{component}-border-radius. All seven component CSS custom properties now follow component-first naming:

  Old	New
  --hds-border-radius-button	--hds-button-border-radius
  --hds-border-radius-card	--hds-card-border-radius
  --hds-border-radius-checkbox	--hds-checkbox-border-radius
  --hds-border-radius-input-tile	--hds-input-tile-border-radius
  --hds-border-radius-modal	--hds-modal-border-radius
  --hds-border-radius-pagination	--hds-pagination-border-radius
  --hds-border-radius-summary	--hds-summary-border-radius

• bd9dae6: Typography + content-styling subsystem

  Introduces a unified type ramp and a single-source content-styling engine, with a deliberately small public Sass surface ahead of v1.0.

  Added: New public file _hds-typography.scss:

  • Public mixins: hds-type($style) (17-entry ramp) and hds-type-classes (utility-class emitter). These are the only public type symbols.
  • New CSS classes: .hds-h1–.hds-h6, .hds-display-2xl, .hds-display-xl, .hds-stat-lg/md/sm/xs, plus .hds-prose-measure (from _prose.scss).
  • New custom properties: --hds-letter-spacing-* (11 keys), --hds-line-height-1 through --hds-line-height-6 (USWDS line-height scale numbering; replaces the USWDS-derived --hds-line-height-body/heading/… names), and --hds-palette-code (NASA Blue Shade on light palettes, NASA Blue Tint on dark, White on the blue palette: a Figma-matched accent, with per-palette values chosen so code reads as text at AA 4.5:1 rather than the 3:1 decorative-stroke threshold).

  Added: New .hds-global-styles opt-in scope. Adopters can opt a subtree into HDS bare-element content styling via class="hds-global-styles", with class="hds-global-styles-reset" carving out unstyled islands (CSS @scope + all: revert-layer). The same reset class is honored inside .usa-prose, so a single carve-out mechanism works across both opt-in scopes.

  Added: New Prose component (components/_prose.scss) that styles .usa-prose with the same content-styling engine.

  Fixed: Component line-heights updated throughout. List items, table headers/captions, breadcrumbs, and blockquote attributions now emit the raw HDS scale instead of USWDS's rounded lh(), tightening their line-height by ~0.05. Every content-layer line-height now traces to the raw --hds-line-height-* scale (no USWDS per-family lh()/line-height() normalization); bespoke fluid sizes use the internal fluid-size() helper (no hand-expanded clamp() literals); figcaption routes through hds-type('caption') so it matches .hds-caption.

  Removed: Intentional pre-v1.0 public-surface reductions. No adopter is expected to depend on these; content styling is delivered via .hds-global-styles / .usa-prose / the global content flag, not by calling mixins:

  • Removed mixins: hds-overline-label, intro-text (single consumers inlined to hds-type()); hds-metadata-type (demoted to internal metadata-type); hds-content-rules (moved to base/_content-rules.scss and demoted to internal content-rules).
  • Removed variables: $hds-type-fluid-min-vw, $hds-type-fluid-max-vw (now private $_fluid-min-vw/$_fluid-max-vw, set to the mobile→desktop-lg range 320→1200px); $hds-line-height-scale map (flattened to scalar $hds-line-height-1 through $hds-line-height-6); $hds-type-scale (dead code).
  • Deleted file: components/_text-styles.scss (superseded by hds-type-classes + _prose.scss).

• 8354f2f: Focus ring system: breaking changes

  Breaking: hds-focus-ring signature changed. The $width, $method, and $offset parameters have been removed. New signature: hds-focus-ring($color, $shape, $pseudo, $circle-size-px). Update any call sites that passed non-default parameters.

  Breaking: hds-focus-ring and hds-focus-ring-size default $pseudo flipped from 'after' to 'before'. If you were calling either mixin without an explicit $pseudo argument, the focus ring now renders on ::before. Pass $pseudo: 'after' to restore the previous behavior.

  Breaking: $hds-focus-widths Sass map removed. The unified ring system bakes 1px directly into the SVG mask. Inline the value at any call sites that referenced this map.

  Breaking: hds-link-appearance and hds-link-hover now render underlines via repeating-linear-gradient instead of text-decoration. If you were overriding text-decoration on elements that receive these mixins, those overrides no longer apply. Use background-image: none to suppress the underline instead.

• ad744ad: Focus ring system: new mixins

  Added: hds-focus-ring-inline mixin...

v0.7.2

Breaking Changes

CSS bundle architecture has changed. Review the updated load contract in README before upgrading.

• hds.css is now self-contained. It includes all USWDS components, themed and unthemed. The two-file mandatory load requirement is removed.
• hds-uswds.css is now utilities-only. Load it only if your site uses USWDS utility classes (padding-*, margin-*, etc.). If you don't use utility classes, you no longer need this file.
• CSS cascade layers are now enforced. Layer order: uswds / uswds-utilities / hds-base / hds-components / hds-dataviz. Custom overrides should target the appropriate layer.
• Unminified CSS files are no longer included in dist/. Reference .min.css files only.

Mandatory load is now 43 KB gzipped, down from 101 KB across two required files.

Bug Fixes

P0 -- Public Sans was silently falling back to system fonts sitewide. public-sans was incorrectly listed in $theme-typeface-tokens, which caused USWDS to treat it as a custom font and never generate @font-face rules for it. All Public Sans text was rendering in the system default font. (#59)

Inter and DM Mono were loading incomplete font sets. Source files were a partial mix of woff, ttf, and woff2 formats, causing weight-specific fallbacks to Arial and system monospace. Replaced with canonical woff2-only sets trimmed to confirmed-used weights. (#59)

Visually-hidden mixin used deprecated clip property. Replaced with clip-path. (#56)

Stylelint was flagging compiled CSS in dist/. Added .stylelintignore to exclude dist/ from both CLI and VS Code extension linting. (af25288)

Improvements

Font duplication eliminated. @font-face declarations dropped from 144 to 6 by fixing a meta.load-css() compilation issue that was emitting fonts once per package. (#60)

Font files trimmed to woff2-only. dist/assets/fonts/ drops 36 redundant woff/ttf files. All browsers in .browserslistrc support woff2. (#59, #60)

New --hds-font-family-* custom properties added to the public API surface. (#59)

Build pipeline simplified -- one PostCSS pass per bundle, down from two. Intermediate unminified files are cleaned up automatically. (#60)

Cascade layers for USWDS integration -- HDS styles now wrap USWDS in @layer uswds, eliminating load-order specificity conflicts. (#52)

Developer / Tooling

Four linters now configured and passing clean: Prettier (#54), Stylelint (#55), ESLint (#57), remark-lint (#58).

Windows / Git Bash local dev compatibility fixes. (#53)

Artifacts

• hds-core-v0.7.2-dist.zip -- compiled CSS and font assets

Known Deferred Items

• Inter Display variable weights -- pending introduction of display-size tokens
• Variable font loading -- blocked on USWDS skeleton team alignment, deferred post-v1.0
• hds-uswds.css is larger than expected at 47.9 KB gzipped for a utilities-only bundle. Investigation ongoing; does not affect mandatory load.

v0.7.1

This will be the first published release of HDS Core. It introduces a new build system, a three-bundle CSS architecture, and significant improvements to component theming and accessibility. Note there are breaking changes from the previous version (v0.6.0).

Highlights

New build system. Replaced Gulp + @uswds/compile with native Dart Sass + PostCSS. The USWDS gulp ecosystem depends on the deprecated Dart Sass Legacy JS API. This migration puts HDS Core on a modern, sustainable compilation pipeline.

Three-bundle architecture. HDS Core now ships three CSS bundles instead of one:

• hds.css - selective USWDS components + all HDS theming (279 KB / 27 KB gzipped)
• hds-uswds.css - remaining USWDS components and utilities (696 KB / 74 KB gzipped)
• hds-dataviz.css - data visualization color tokens and custom properties (small today, designed to grow as HDS dataviz patterns expand)

New sites load only hds.css for a 70% smaller payload compared to the previous single 895 KB bundle. Sites that need full USWDS coverage add hds-uswds.css. Sites with charts or data visualizations add hds-dataviz.css.

Design tokens. HDS Core now ships tokens.json in the W3C Design Tokens Community Group (DTCG) 2025.10 format. 309 tokens across seven domain groups (color, spacing, breakpoint, border, focus, layout, dataviz). Token $description fields include machine-readable usage constraints for design tooling and AI-assisted development workflows. A Style Dictionary example configuration is included for teams running custom token pipelines.

Accessibility improvements. Focus states migrated from :focus to :focus-visible across all components. Focus ring system standardized via shared tokens and mixins. Chromatic visual regression testing added for palette accessibility verification across all six HDS color palettes. Focus ring contrast values are under active review for WCAG 1.4.11 compliance (Issue #40).

Breaking Changes

If upgrading from v0.6.0, the following changes require action:

CSS bundle renamed and split. styles.css is removed. Replace with hds.css. Sites needing full USWDS coverage must also load hds-uswds.css before hds.css (load order determines cascade priority).

<!-- HDS only (most sites) -->
<link rel="stylesheet" href="hds.min.css" />

<!-- Full USWDS coverage -->
<link rel="stylesheet" href="hds-uswds.min.css" />
<link rel="stylesheet" href="hds.min.css" />

Typography utilities consolidated. .hds-label and .hds-eyebrow removed. Replace with .hds-overline.

Focus states changed. All :focus pseudo-classes migrated to :focus-visible. No code changes required but interactive elements will no longer show focus rings on mouse click, only on keyboard navigation.

Link underlines. Global link underline style changed from dotted to dashed, matching NASA.gov production styling.

Build system. Gulp tasks removed. Use npm run build for all compilation. See ARCHITECTURE.md for details.

Added

• Blockquote component with palette-adaptive token
• List component styles with marker palette token
• Prose component styles and documentation
• Side Navigation component with multi-level support
• Data visualization color tokens (categorical + sequential)
• Design tokens file (tokens.json) in W3C DTCG 2025.10 format
• Style Dictionary example configuration (tools/sd-example/)
• Section 508 accessibility checklist
• Guides: React setup, USWDS migration
• USWDS package hash verification on install
• Chromatic visual regression testing infrastructure

Changed

• In-Page Navigation restyled to match Figma specifications
• Icon buttons refactored to 2-layer architecture with Figma-accurate focus and hover states
• Focus rings standardized via shared tokens and mixins
• SCSS split from monolithic file into modular base/ and components/ directories

Fixed

• Pagination: invisible page numbers on dark palettes
• Pagination: arrows disappearing at high browser zoom
• Breadcrumb: buggy focus ring on first item
• Button: squished circle on primary external arrows
• Grid: visible gutters in documentation
• CSS load order corrected in hds-uswds.scss code comment

Internal

• Removed: gulp, gulp-clean-css, gulp-rename, gulp-svg-sprite, gulp-terser, @uswds/compile
• Added: sass, postcss, postcss-cli, autoprefixer, cssnano, svg-sprite
• Updated: vitest, playwright, prettier, Storybook packages

v0.6.0

Icon renames, size scale, sidebar variants, palette fixes

Breaking changes

15 icons renamed for consistency with USWDS naming conventions. Update any <use href="...#icon-name"> references:

Old name	New name
subscribe	notification
tag-activity	tag-edit
tag-article	tag-bookmark
tag-bio	tag-person
tag-blog	tag-comment
tag-encyclopedia	tag-reference
tag-feature	tag-star
tag-file	tag-folder
tag-infographic	tag-graph
tag-media-advisory	tag-announcement
tag-press-release	tag-document
tag-previously-aired	tag-repeat
tag-sound	tag-audio
tag-subscribe	tag-mail
tag-video	tag-play

Changed

• Secondary filled button now uses NASA Blue (#1C67E3) on all palettes (previously NASA Blue Tint on dark palettes). Passes WCAG AA on all backgrounds.
• Secondary filled button on blue palette automatically renders as outline (transparent background, NASA Blue border) since the filled variant blends into the palette background.
• Table on blue palette now uses the light table variant (white surface) instead of dark.
• Icon button states — hover, active, and disabled styles added for all roles (CTA, secondary, outline, utility, social) across all six palettes.

Improved

• Storybook sidebar — all component stories refactored from single Playground to individual variant stories with focused controls.
• Storybook branding — top-left shows NASA meatball + "HDS Core" text.
• Viewport presets — 7 USWDS breakpoints + TV (deferred) available in toolbar.
• Sidebar sort order — Guidance page always appears first, stories follow export order.

Dependencies

• @chromatic-com/storybook 5.0.2 → 5.1.1
• vitest 4.1.0 → 4.1.2
• @vitest/browser-playwright 4.1.0 → 4.1.2
• @vitest/coverage-v8 4.1.0 → 4.1.2

Full Changelog: v0.5.0...v0.6.0

v0.5.0

What's Changed

• Typography refactor, devcontainer setup, code comment cleanup, added font smoothing in #22
• Add automated testing, fix unstyled button, streamline docs in #25
• v0.5.0 - Table, Form Elements, Codespaces workflow, docs in #28

Full Changelog: v0.4.0...v0.5.0

v0.4.0

Pre-release. Not for production use.

Components and Storybook documentation

• 2 top-level Storybook pages added: Overview, Getting Started, Roadmap (with redundant content removed from repo .md files)
• 4 Foundations pages added: Accessibility, Color Palettes, Data Visualization, Data Visualization Palettes
• 3 components styled and documented: Accordion, Pagination, Site Alert
• Remaining Storybook pages audited and cleaned up: Deduplication, cross-linking, conversion to .mdx, alignment with DOCUMENTATION.md conventions

Bug fixes and small enhancements

• Typography refactor and mixin updates (#19)
• Added font smoothing (#17)
• Remove generated namespace IDs from SVG sprite

Infrastructure

• Added devcontainer.json to fix build errors in new Codespaces
• Now loading USWDS JS in Storybook for accordions and other JS-dependent components
• Added LICENSE.md and CREDITS.md
• Updated remaining root-level .md docs to dedupe with new Storybook-first documentation approach

What's next

See #8 (and add comments on any components you need for your site!)

Full Changelog: v0.3.1...v0.4.0

v0.3.1 - Storybook docs infrastructure + first 5 components

Pre-release. Not for production use.

Storybook documentation

• 2-tab pattern established: Guidance (MDX) + Playground per component
• 5 components documented: Button, Link, Icon Button, Breadcrumb, Intro Text
• Shared icon helper with categorized HDS/USWDS icon arrays
• Palette switcher toolbar for testing all 6 palettes
• Note callout system (USWDS/Figma/Code variants)

CSS fixes

• Breadcrumb: slash separators, palette-aware colors, hover states
• Intro Text: corrected to match Figma spec (size, weight, line-height, letter-spacing)
• Icon Button interactive role: hardcoded colors instead of palette vars
• Breadcrumb separator: forward slash override (from nasa.gov production pattern)

Infrastructure

• Prettier configured (proseWrap: never)
• Storybook: dynamic source, disabled save-from-UI
• Component roadmap published as GitHub Discussion

What's next

See #8 (and add comments on any components you need for your site!)