@nasa-hds/core 0.0.0

package/src/assets/img/hds-icons/view-single.svg

@@ -0,0 +1,4 @@
+<svg viewBox="-2 -2 24 24" xmlns="http://www.w3.org/2000/svg">
+<path d="M20 13L1.22392e-06 13L0 3L20 3L20 13Z" fill="currentColor"/>
+<rect y="15" width="8" height="2" fill="currentColor"/>
+</svg>

package/src/assets/img/hds-icons/x-circled.svg

@@ -0,0 +1,3 @@
+<svg viewBox="-2 -2 24 24" xmlns="http://www.w3.org/2000/svg">
+<path fill-rule="evenodd" clip-rule="evenodd" d="M10 19C14.9706 19 19 14.9706 19 10C19 5.02944 14.9706 1 10 1C5.02944 1 1 5.02944 1 10C1 14.9706 5.02944 19 10 19ZM6.41152 5L9.94841 8.53688L13.4853 5.00001L14.9 6.41054L11.361 9.94949L14.8968 13.4853L13.4853 14.899L9.94841 11.3621L6.41469 14.8958L5 13.4853L8.5358 9.94949L5.00004 6.41373L6.41152 5Z" fill="currentColor"/>
+</svg>

package/src/assets/img/nasa-branding/nasa-logo.svg

@@ -0,0 +1,52 @@
+<?xml version="1.0"?>
+<svg height="92" viewBox="0 0 110 92" width="110" xmlns="http://www.w3.org/2000/svg">
+<circle cx="50.049" cy="45" fill="#0b3d91" r="40.14"/>
+<g fill="#fff">
+<circle cx="47.679" cy="12.57" r=".45"/>
+<circle cx="52.299" cy="13.17" r=".45"/>
+<circle cx="58.359" cy="21.33" r=".45"/>
+<circle cx="25.119" cy="63.33" r=".45"/>
+<circle cx="26.289" cy="66.93" r=".45"/>
+<circle cx="20.709" cy="63.87" r=".337"/>
+<circle cx="39.009" cy="70.942" r=".338"/>
+<circle cx="67.711" cy="64.98" r=".337"/>
+<circle cx="76.052" cy="55.92" r=".338"/>
+<circle cx="35.169" cy="23.962" r=".337"/>
+<circle cx="44.349" cy="17.22" r=".337"/>
+<circle cx="43.352" cy="16.56" r=".337"/>
+<circle cx="42.452" cy="15.9" r=".337"/>
+<circle cx="36.609" cy="25.703" r=".337"/>
+<circle cx="50.131" cy="8.16" r=".337"/>
+<circle cx="52.352" cy="17.88" r=".337"/>
+<circle cx="48.849" cy="15.982" r=".337"/>
+<circle cx="42.849" cy="18.563" r=".337"/>
+<circle cx="69.309" cy="73.883" r=".337"/>
+<circle cx="24.549" cy="65.61" r=".338"/>
+<circle cx="48.009" cy="69.96" r=".338"/>
+<circle cx="31.531" cy="65.34" r=".338"/>
+<circle cx="34.449" cy="70.103" r=".338"/>
+<circle cx="55.929" cy="67.103" r=".337"/>
+<circle cx="67.771" cy="60.42" r=".337"/>
+<circle cx="76.749" cy="64.522" r=".337"/>
+<circle cx="79.809" cy="66.48" r=".337"/>
+<circle cx="80.312" cy="61.14" r=".337"/>
+<circle cx="35.671" cy="53.58" r=".337"/>
+<circle cx="35.799" cy="61.32" r=".45"/>
+<circle cx="38.499" cy="67.02" r=".45"/>
+<circle cx="70.839" cy="61.08" r=".45"/>
+<circle cx="82.479" cy="60.42" r=".45"/>
+<circle cx="76.719" cy="57.96" r=".45"/>
+<circle cx="70.839" cy="58.2" r=".45"/>
+<path d="M58.71 12.288l1.119-.107-1.117-.063c-.035-.216-.208-.385-.426-.413l-.107-1.114-.064 1.123c-.202.045-.357.214-.382.424l-1.144.104 1.152.062c.042.193.198.344.394.38l.104 1.148.061-1.146C58.507 12.651 58.671 12.492 58.71 12.288z"/>
+<path d="M39.824 24.746l1.119-.107-1.117-.063c-.034-.216-.208-.385-.426-.413l-.107-1.114-.063 1.123c-.203.045-.358.214-.383.424l-1.144.104 1.152.062c.042.193.198.344.394.38l.104 1.148.062-1.146C39.622 25.11 39.786 24.95 39.824 24.746z"/>
+<path d="M81.659 57.684l1.119-.107-1.117-.063c-.034-.216-.208-.385-.426-.413l-.107-1.114-.063 1.123c-.202.045-.357.214-.382.424l-1.144.104 1.152.062c.042.193.198.344.394.38l.104 1.148.062-1.146C81.456 58.048 81.62 57.889 81.659 57.684z"/>
+<path d="M36.044 74.906l1.119-.107-1.117-.063c-.035-.216-.208-.385-.426-.413l-.107-1.113-.063 1.122c-.203.045-.358.214-.383.424l-1.144.104 1.152.062c.042.193.198.345.394.38l.104 1.148.062-1.146C35.841 75.27 36.006 75.11 36.044 74.906z"/>
+<path d="M78.104 66.506l1.119-.107-1.117-.063c-.034-.216-.208-.385-.426-.413l-.107-1.114-.063 1.122c-.202.045-.357.214-.382.424l-1.144.104 1.152.062c.042.193.198.344.394.38l.104 1.148.062-1.146C77.901 66.87 78.066 66.71 78.104 66.506z"/>
+<path d="M59.568 35.385c-4.667 1.814-9.219 3.433-13.06 4.635-7.805 2.444-29.16 9.06-42.06 17.4l1.08.42c7.86-4.44 12.969-5.835 17.88-7.38 5.34-1.68 22.603-5.72 30.42-7.92 2.641-.743 5.734-1.716 9.01-2.9-.762-1.063-1.566-2.129-2.412-3.193C60.143 36.088 59.856 35.734 59.568 35.385zM65.27 43.244c-1.13.763-2.077 1.372-2.74 1.756-3.84 2.22-22.561 15-26.82 17.94s-16.08 14.1-19.56 17.34l-.12 1.319c11.22-10.08 14.74-12.566 19.2-15.959 5.52-4.2 16.939-11.97 20.82-14.46 3.71-2.38 7.056-4.569 10.059-6.572-.049-.082-.098-.164-.147-.247C65.736 43.99 65.505 43.618 65.27 43.244zM82.809 24.72c-5.466 3.204-14.081 7.071-22.439 10.352.2.245.399.492.597.741.934 1.176 1.815 2.36 2.644 3.545 6.57-2.42 13.779-5.668 19.499-9.599-2.725 2.582-11.734 9.315-17.227 13.068.283.461.557.922.822 1.381 8.322-5.569 13.922-9.668 17.185-12.409 4.5-3.78 14.76-12.24 18.66-23.58C95.709 16.92 87.621 21.899 82.809 24.72z" fill="#fc3d21"/>
+<path d="M44.884 54.939c-.885-1.114-2.109-2.606-3.028-3.763-1.229-1.547-2.366-3.11-3.408-4.671-.34.085-.679.17-1.018.255 1.258 1.963 2.655 3.923 4.177 5.839 1.112 1.4 2.123 2.527 2.641 3.228.105.142.313.456.594.874.324-.22.651-.442.981-.666C45.504 55.688 45.189 55.323 44.884 54.939zM51.344 60.803c-.727-.688-2.49-1.837-4.325-3.561-.405.278-.814.56-1.224.844 1.185 1.67 2.799 3.721 4.063 4.319C51.762 63.307 52.275 61.685 51.344 60.803zM60.967 35.813c-10.492-13.206-23.309-20.461-28.835-16.07-4.292 3.41-2.53 13.376 3.386 23.845.306-.105.609-.208.909-.31-5.971-10.2-7.605-19.679-3.557-22.896 5.087-4.042 17.37 3.241 27.558 16.064 2.109 2.654 3.963 5.318 5.533 7.915 6.012 9.95 7.857 18.948 3.703 22.621-1.271 1.124-5.155 1.565-10.243-.725-.071.089.043.33.132.389 4.392 1.766 8.599 2.439 10.723.752C75.38 63.342 71.459 49.019 60.967 35.813z"/>
+<path d="M15.969 37.38h6.72l5.64 9.57c0 0 0-6.93 0-7.47 0-.84-1.065-1.935-1.44-2.1.45 0 4.38 0 4.65 0-.285.075-1.2 1.185-1.2 2.1 0 .45 0 10.5 0 10.98 0 .675.975 1.605 1.44 1.965h-6.48l-5.73-9.615c0 0 0 7.17 0 7.56 0 .75.735 1.47 1.5 2.085h-4.95c.705-.3 1.38-1.245 1.44-1.995s0-10.425 0-10.845C17.559 38.7 16.674 37.95 15.969 37.38z"/>
+<path d="M77.439 52.425h8.94c-.495-.12-1.05-.705-1.35-1.485-.3-.78-5.04-13.56-5.04-13.56H76.59c-.964.694-1.997 1.426-3.1 2.197-.003.028-.006.056-.011.083-.148.9-2.808 10.534-2.97 11.01-.225.66-1.38 1.395-1.845 1.785h4.815c-.48-.54-.87-1.065-.78-1.665.09-.6.36-1.8.36-1.8h4.98c.225.6.393 1.139.48 1.65C78.624 51.255 77.994 51.945 77.439 52.425zM73.509 47.07l1.68-5.49 2.22 5.49H73.509zM72.752 37.928c.247-.182.495-.365.742-.548h-1.305C72.319 37.5 72.534 37.689 72.752 37.928z"/>
+<path d="M38.559 50.79c.09-.6.36-1.8.36-1.8h4.98c.225.6.393 1.139.48 1.65.105.615-.525 1.305-1.08 1.785h7.871c.164-.11.327-.22.49-.329-.305-.27-.586-.675-.771-1.156-.3-.78-5.04-13.56-5.04-13.56h-7.8c.375.345 1.455 1.275 1.29 2.28-.147.9-2.808 10.534-2.97 11.01-.225.66-1.38 1.395-1.845 1.785h4.815C38.859 51.915 38.469 51.39 38.559 50.79zM41.049 41.58l2.22 5.49h-3.9L41.049 41.58z"/>
+<path d="M65.748 44.848c-1.468.978-3.017 1.999-4.649 3.065.732.355 1.315.801 1.371 1.377.104 1.082-2.07 1.605-4.035 1.38-.393-.045-.779-.148-1.147-.286-.408.263-.82.528-1.238.796-.425.273-.941.609-1.53.997v1.553c.39-.765 1.243-1.45 1.905-1.485.285-.015 1.275.9 5.355.675 1.98-.109 5.805-2.22 5.745-4.65C67.489 46.834 66.739 45.714 65.748 44.848zM54.519 48.6v1.582c.361-.241.717-.478 1.066-.709C55.036 49.091 54.647 48.734 54.519 48.6zM64.353 43.855c-.38-.225-.765-.422-1.134-.596-1.92-.9-3.93-1.065-4.35-2.28-.296-.857.54-1.65 2.58-1.62 2.04.03 3.93 1.245 4.44 1.68v-3.87c-.15.15-.808.905-1.41.78-1.155-.24-3.12-.553-5.37-.54-2.58.015-4.8 2.009-4.875 4.53-.105 3.525 2.715 4.485 4.305 5.04.164.057.351.118.554.183 1.525-.992 2.731-1.756 3.437-2.163C63.004 44.726 63.625 44.334 64.353 43.855z"/>
+</g>
+</svg>

package/src/scss/_hds-config.scss

@@ -0,0 +1,18 @@
+// ============================================================
+// HDS Configuration Flags
+// @nasa/hds-core
+// ============================================================
+// Shared configuration consumed by multiple modules.
+// Must load before consumers (palettes, dataviz, custom-properties).
+//
+// PUBLIC API: These flags are configurable by consumers via @use ... with (...).
+// Listed in public-api.snapshot.txt.
+// ============================================================
+
+/// Enable dataviz token emission in hds-dataviz.scss
+/// @type Boolean
+$hds-enable-dataviz-tokens: false !default;
+
+/// Enable automatic dark mode detection via prefers-color-scheme
+/// @type Boolean
+$hds-enable-auto-dark-mode: false !default;

package/src/scss/_hds-dataviz-palettes.scss

@@ -0,0 +1,41 @@
+@use 'uswds-core' as *;
+@use 'hds-config' as *;
+@use 'hds-tokens' as *;
+
+@mixin scheme-dataviz-dark {
+  // ==========================================================
+  // Data visualization — categorical (dark backgrounds)
+  // ==========================================================
+  // Lighter USWDS equivalents for dark/black backgrounds.
+  // Light defaults are set in :root (base/_custom-properties.scss).
+  // Blue palette inherits light defaults (chart bg assumed light).
+  //
+  // Mapping (HDS Figma name → USWDS token):
+  //   cat-1:  Blue 60   → blue-50v
+  //   cat-2:  Red 50    → red-40v        (unchanged from light)
+  //   cat-3:  Orange 30 → orange-20v
+  //   cat-4:  Slate 60  → blue-cool-50
+  //   cat-5:  Gold 30   → gold-20
+  //   cat-6:  Blue 40   → blue-30v
+  //   cat-7:  Red 30    → red-20v
+  //   cat-8:  Slate 40  → blue-cool-30   (unchanged from light)
+  //   cat-9:  Purple 60 → indigo-warm-50v
+  //   cat-10: Yellow 30 → gold-20v
+  //   cat-11: Lime 60   → green-50v
+  //   cat-12: Aqua 40   → mint-cool-30v  (unchanged from light)
+  // ==========================================================
+  @if $hds-enable-dataviz-tokens {
+    --hds-dataviz-color-cat-1: #256ee4;
+    --hds-dataviz-color-cat-2: #ef483f;
+    --hds-dataviz-color-cat-3: #f29d49;
+    --hds-dataviz-color-cat-4: #487682;
+    --hds-dataviz-color-cat-5: #c2b47c;
+    --hds-dataviz-color-cat-6: #609af6;
+    --hds-dataviz-color-cat-7: #fa8c87;
+    --hds-dataviz-color-cat-8: #79a3ad;
+    --hds-dataviz-color-cat-9: #794be4;
+    --hds-dataviz-color-cat-10: #f5af0c;
+    --hds-dataviz-color-cat-11: #4b9609;
+    --hds-dataviz-color-cat-12: #0cc9ac;
+  }
+}

package/src/scss/_hds-mixins.scss

@@ -0,0 +1,423 @@
+// ============================================================
+// HDS Base — Shared Mixins
+// @nasa/hds-core
+// ============================================================
+// Produces zero CSS output. Provides tools used by base files
+// and components.
+//
+// CONTENTS:
+//   Accessibility — visually-hidden
+//   Focus         — hds-focus-ring, hds-focus-ring-size,
+//                   hds-focus-ring-inline
+//   Buttons       — button-styles (bundles button-padding-border,
+//                   button-typography, and button-color),
+//                   button-interactive-states, button-round
+//   Utility       — hds-utility-circle (pagination, icon buttons)
+//   Links         — hds-link-appearance, hds-link-hover
+//   Navigation    — hds-nav-hover-underline (breadcrumb, in-page nav,
+//                   side nav), hds-vertical-nav-links
+// ============================================================
+
+@use 'sass:map';
+@use 'uswds-core' as *;
+@use 'hds-tokens' as *;
+@use 'hds-typography' as *;
+
+// ------------------------------------------------------------
+// Accessibility
+// ------------------------------------------------------------
+
+@mixin visually-hidden {
+  border: 0;
+  clip-path: inset(50%);
+  height: 1px;
+  margin: -1px;
+  overflow: hidden;
+  padding: 0;
+  position: absolute;
+  width: 1px;
+  overflow-wrap: normal;
+}
+
+// ------------------------------------------------------------
+// Focus
+// ------------------------------------------------------------
+// Dashed focus ring for keyboard navigation. Palette-aware
+// via --hds-palette-focus-* custom properties defined in
+// base/_palettes.scss.
+//
+// Four color treatments matching Figma focus patterns:
+//   'default'  — C60 light / C30 dark
+//   'bold'     — C30 universal
+//   'subtle'   — C60 light / C40 dark
+//   'minimal'  — C30 light / C80 dark
+//
+// Standard properties: 1px stroke, 2,3 dasharray.
+//
+// Three application methods — pick by host layout:
+//   hds-focus-ring()        — block/flex elements (buttons,
+//                             pagination, accordion). SVG mask
+//                             on ::before (default) or ::after.
+//   hds-focus-ring-size()   — overrides circle ring geometry
+//                             on icon button size modifiers.
+//   hds-focus-ring-inline() — inline text elements (links,
+//                             unstyled buttons, breadcrumbs).
+//                             Four-sided repeating-linear-gradient
+//                             ring; fragments per line box on
+//                             multiline elements.
+// ------------------------------------------------------------
+
+// Fallback values for contexts without a palette wrapper.
+// Each maps to the light-scheme value for that treatment.
+$_focus-fallbacks: (
+  'default': $hds-color-carbon-60,
+  'bold': $hds-color-carbon-30,
+  'subtle': $hds-color-carbon-60,
+  'minimal': $hds-color-carbon-30,
+);
+
+// Rect SVG mask — module-level constant (never varies).
+// overflow="visible" lets the outer half of the 1px stroke
+// paint outside the SVG viewport; the pseudo's inset: -2px
+// provides that space so no edge is clipped.
+$_focus-ring-rect-svg: "data:image/svg+xml,%3Csvg width='100%25' height='100%25' overflow='visible' xmlns='http://www.w3.org/2000/svg'%3E%3Crect width='100%25' height='100%25' fill='none' stroke='black' stroke-width='1' stroke-dasharray='2%2C3' stroke-dashoffset='1' stroke-linecap='butt'/%3E%3C/svg%3E";
+
+// Block/flex elements (buttons, accordion, pagination, primary arrow).
+// $pseudo defaults to 'before' because component-owned trailing icons
+// (chevrons, arrows, active bars) conventionally live on ::after.
+// Pass $pseudo: 'after' only when the host already uses ::before.
+@mixin hds-focus-ring($color: 'default', $shape: 'rect', $pseudo: 'before', $circle-size-px: 24) {
+  $suffix: '';
+
+  @if $color != 'default' {
+    $suffix: '-#{$color}';
+  }
+
+  $prop: --hds-palette-focus#{$suffix};
+  $fallback: map.get($_focus-fallbacks, $color);
+
+  position: relative;
+  outline: none;
+
+  &::#{$pseudo} {
+    content: '';
+    position: absolute;
+    pointer-events: none;
+    background-color: var(#{$prop}, #{$fallback});
+    z-index: 1;
+
+    @if $shape == 'circle' {
+      $container-size: $circle-size-px + 6;
+      $center: $container-size * 0.5;
+      $radius: $center - 1.5;
+
+      top: 50%;
+      left: 50%;
+      width: #{$container-size}px;
+      height: #{$container-size}px;
+      margin-top: -#{$center}px;
+      margin-left: -#{$center}px;
+      mask-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='#{$container-size}' height='#{$container-size}' overflow='visible'%3E%3Ccircle cx='#{$center}' cy='#{$center}' r='#{$radius}' fill='none' stroke='black' stroke-width='1' stroke-dasharray='2,3' stroke-linecap='butt'/%3E%3C/svg%3E");
+      mask-size: 100% 100%;
+    } @else {
+      inset: -2px;
+      border-radius: inherit;
+      mask-image: url($_focus-ring-rect-svg);
+      mask-size: 100% 100%;
+    }
+  }
+}
+
+// Overrides circle ring geometry for icon button size modifiers
+// (--xs, --sm, --lg, etc.) without re-declaring the full mixin.
+@mixin hds-focus-ring-size($circle-size-px, $pseudo: 'before') {
+  $container-size: $circle-size-px + 6;
+  $center: $container-size * 0.5;
+  $radius: $center - 1.5;
+
+  &::#{$pseudo} {
+    width: #{$container-size}px;
+    height: #{$container-size}px;
+    margin-top: -#{$center}px;
+    margin-left: -#{$center}px;
+    mask-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='#{$container-size}' height='#{$container-size}' overflow='visible'%3E%3Ccircle cx='#{$center}' cy='#{$center}' r='#{$radius}' fill='none' stroke='black' stroke-width='1' stroke-dasharray='2,3' stroke-linecap='butt'/%3E%3C/svg%3E");
+  }
+}
+
+// Inline text elements (links, unstyled buttons, breadcrumbs).
+// Four repeating-linear-gradient layers draw the 2,3 dash spec
+// on all four edges. background-image on inline elements fragments
+// naturally per line box — each wrapped line gets its own ring.
+// The host must have padding: 0 4px (always-on) so the left/right
+// edges have space to render; hds-link-appearance provides this
+// for links and unstyled buttons. Breadcrumb sets it directly.
+@mixin hds-focus-ring-inline($color: 'default') {
+  $suffix: '';
+
+  @if $color != 'default' {
+    $suffix: '-#{$color}';
+  }
+
+  $prop: --hds-palette-focus#{$suffix};
+  $fallback: map.get($_focus-fallbacks, $color);
+
+  outline: none;
+
+  // Order: bottom, top, left, right
+  background-image:
+    repeating-linear-gradient(
+      to right,
+      var(#{$prop}, #{$fallback}) 0,
+      var(#{$prop}, #{$fallback}) 2px,
+      transparent 2px,
+      transparent 5px
+    ),
+    repeating-linear-gradient(
+      to right,
+      var(#{$prop}, #{$fallback}) 0,
+      var(#{$prop}, #{$fallback}) 2px,
+      transparent 2px,
+      transparent 5px
+    ),
+    repeating-linear-gradient(
+      to bottom,
+      var(#{$prop}, #{$fallback}) 0,
+      var(#{$prop}, #{$fallback}) 2px,
+      transparent 2px,
+      transparent 5px
+    ),
+    repeating-linear-gradient(
+      to bottom,
+      var(#{$prop}, #{$fallback}) 0,
+      var(#{$prop}, #{$fallback}) 2px,
+      transparent 2px,
+      transparent 5px
+    );
+  background-size:
+    100% 1px,
+    100% 1px,
+    1px 100%,
+    1px 100%;
+  background-position:
+    0 100%,
+    0 0,
+    0 0,
+    100% 0;
+  background-repeat: no-repeat;
+}
+
+// ------------------------------------------------------------
+// Buttons
+// ------------------------------------------------------------
+
+@mixin button-padding-border {
+  border-radius: $hds-border-radius;
+  border-style: solid;
+  border-width: $hds-border-width-thick;
+  padding-block: units(1.5);
+  padding-inline: units(2.5);
+}
+
+@mixin button-color {
+  background-color: var(--hds-palette-btn-primary-bg, #{$hds-color-nasa-red});
+  border-color: var(--hds-palette-btn-primary-bg, #{$hds-color-nasa-red});
+  color: var(--hds-palette-btn-filled-text, #{$hds-color-spacesuit-white});
+
+  svg {
+    fill: currentcolor;
+  }
+}
+
+@mixin button-styles {
+  @include button-padding-border;
+  @include hds-type('h5');
+  @include button-color;
+
+  text-decoration-line: none;
+}
+
+// Hover/active/focus states shared by .usa-button and the base
+// stock-button reset (base/_elements.scss). Defensive :not()
+// qualifiers prevent disabled buttons from picking up these states
+// regardless of source order.
+@mixin button-interactive-states {
+  &:hover:not(:disabled, [aria-disabled='true']),
+  &:active:not(:disabled, [aria-disabled='true']) {
+    background-color: $hds-color-nasa-red-shade;
+    text-decoration-line: none;
+  }
+
+  &:focus-visible:not(:disabled, [aria-disabled='true']) {
+    @include hds-focus-ring($color: 'bold');
+
+    text-decoration-line: none;
+  }
+}
+
+@mixin button-round {
+  align-items: center;
+  border-radius: 50%;
+  display: inline-flex;
+  height: 2em;
+  justify-content: center;
+  padding: 0;
+  width: 2em;
+}
+
+// ------------------------------------------------------------
+// Utility circle
+// ------------------------------------------------------------
+// Shared by pagination prev/next and icon buttons --utility.
+// Change once, both components update.
+//
+// Neutral adaptive circle container for UI controls (carousel,
+// accordion, pagination arrows). Palette-aware via custom
+// properties with light-palette fallbacks.
+//
+// Hover, focus, and disabled states are NOT in this mixin —
+// they differ between components (e.g. pagination disables
+// via aria-disabled on <a>, icon buttons via disabled on
+// <button>). Each component handles its own states.
+// ------------------------------------------------------------
+
+@mixin hds-utility-circle {
+  align-items: center;
+  background-color: var(--hds-palette-utility-fill, #{$hds-color-spacesuit-white});
+  border: $hds-border-width-thin solid var(--hds-palette-utility-stroke, #{$hds-color-carbon-20});
+  border-radius: 50%;
+  color: var(--hds-palette-utility-icon, #{$hds-color-carbon-black});
+  cursor: pointer;
+  display: inline-flex;
+  justify-content: center;
+  padding: 0;
+  position: relative;
+}
+
+// ------------------------------------------------------------
+// Link appearance
+// ------------------------------------------------------------
+// Dashed underline via repeating-linear-gradient rather than
+// text-decoration, matching the Figma 2,3 dash spec exactly.
+// Uses background-image so it fragments per line box on
+// multiline inline elements (no box-decoration-break needed
+// for background — inline elements fragment backgrounds
+// natively with clone).
+//
+// Horizontal padding (4px) per Figma focus ring spec — always
+// present so no layout shift occurs on focus.
+// ------------------------------------------------------------
+
+@mixin hds-link-appearance {
+  color: var(--hds-palette-link-text, #{$hds-color-carbon-90});
+  text-decoration: none;
+  display: inline;
+  padding: 0 4px;
+  margin: 0 -4px;
+  box-decoration-break: clone;
+  // stylelint-disable-next-line property-no-vendor-prefix
+  -webkit-box-decoration-break: clone;
+
+  // Dashed underline — content width only (excludes 4px padding each side)
+  background-image: repeating-linear-gradient(
+    to right,
+    var(--hds-palette-link-underline, #{$hds-color-carbon-60}) 0,
+    var(--hds-palette-link-underline, #{$hds-color-carbon-60}) 2px,
+    transparent 2px,
+    transparent 5px
+  );
+  background-size: calc(100% - 8px) 1px;
+  background-position: center 100%;
+  background-repeat: no-repeat;
+}
+
+@mixin hds-link-hover {
+  color: var(--hds-palette-link-text, #{$hds-color-carbon-90});
+
+  // Solid underline — same content-width constraint
+  background-image: linear-gradient(
+    to right,
+    var(--hds-palette-link-underline, #{$hds-color-carbon-60}),
+    var(--hds-palette-link-underline, #{$hds-color-carbon-60})
+  );
+  background-size: calc(100% - 8px) 1px;
+  background-position: center 100%;
+}
+
+// ------------------------------------------------------------
+// Navigation hover underline
+// ------------------------------------------------------------
+// Dashed underline that appears only on hover/focus.
+// Used by components where links have no default underline
+// but gain one on interaction: Breadcrumb, In-Page Navigation,
+// Side Navigation.
+//
+// Distinct from hds-link-appearance (always-visible underline
+// using --hds-palette-link-underline). Same mechanical
+// properties (dash style, thickness, offset) — could be
+// extracted to a shared base if a third variant appears.
+//
+// Color is currentColor — inherits from the component's own
+// hover color rule. Each component sets its own hover color
+// (e.g. --hds-palette-heading) before including this mixin.
+// ------------------------------------------------------------
+
+@mixin hds-nav-hover-underline {
+  text-decoration-color: currentcolor;
+  text-decoration-line: underline;
+  text-decoration-style: dashed;
+  text-decoration-thickness: 0.05em;
+  text-underline-offset: 0.25rem;
+}
+
+// ------------------------------------------------------------
+// Vertical navigation links
+// ------------------------------------------------------------
+// Shared typography, hover states, and active indicators for
+// vertical list-based navigation (In-Page Nav, Side Nav).
+//
+// Applies to: `a:not(.usa-button)`
+// ------------------------------------------------------------
+
+@mixin hds-vertical-nav-links {
+  font-weight: font-weight('normal');
+  letter-spacing: $hds-letter-spacing-1;
+  text-decoration: none;
+
+  &:hover {
+    background-color: transparent; // override USWDS solid fills
+
+    @include hds-nav-hover-underline;
+
+    text-decoration-color: var(--hds-palette-link-underline, #{$hds-color-carbon-60});
+  }
+
+  &:focus-visible {
+    @include hds-focus-ring;
+  }
+
+  &:not(.usa-current) {
+    color: var(--hds-palette-text, #{$hds-color-carbon-90});
+
+    &:visited {
+      color: var(--hds-palette-text, #{$hds-color-carbon-90});
+    }
+
+    &:hover {
+      color: var(--hds-palette-heading, #{$hds-color-carbon-black});
+    }
+  }
+
+  &.usa-current {
+    color: var(--hds-palette-text, #{$hds-color-carbon-90});
+    font-weight: font-weight('normal');
+
+    &::after {
+      background-color: var(--hds-palette-marker, #{$hds-color-nasa-blue});
+      border-radius: #{$hds-border-radius}; // Override USWDS pill with HDS default 0px border radius
+      width: $hds-border-width-thick;
+
+      // Note: components must handle top/bottom/left positioning
+      // of this pseudo-element according to their specific layout.
+    }
+  }
+}

package/src/scss/_hds-tokens.scss

@@ -0,0 +1,91 @@
+
+// Do not edit directly, this file was auto-generated.
+
+$hds-color-nasa-red: #f64137; // Primary NASA brand red. Red means 'go somewhere.' For primary actions navigating to a new page (.usa-button, .hds-btn--primary) and error/emergency alerts. Never for on-page actions, decorative use, or dataviz.
+$hds-color-nasa-red-tint: #ff5c52; // Lighter tint of NASA red. Used for hover states and error highlights.
+$hds-color-nasa-red-shade: #b60109; // Darker shade of NASA red. Used for button hover and error dark.
+$hds-color-nasa-blue: #1c67e3; // Primary NASA brand blue. Blue means 'do something here.' For on-page interactions (.usa-button--secondary, .usa-button--outline), controls, list markers, table headers, info alerts. Never for navigation CTAs or dataviz.
+$hds-color-nasa-blue-tint: #288bff; // Lighter tint of NASA blue. Used for active elements and dark palette buttons.
+$hds-color-nasa-blue-shade: #0b3d91; // Darker shade of NASA blue. Used for blue palette background.
+$hds-color-international-orange: #ea6f24; // Secondary brand accent. For status emphasis or decorative markers (blockquote icons). Never for primary actions. Decorative uses exempt from 3:1 contrast minimum.
+$hds-color-active-green: #47da84; // Semantic brand green. For active mission status and confirmation states. Never for branding, decorative backgrounds, or dataviz.
+$hds-color-carbon-10: #e3e3e3; // Off-white carbon neutral.
+$hds-color-carbon-20: #d1d1d1; // Very light carbon neutral.
+$hds-color-carbon-30: #b9b9bb; // Light carbon neutral.
+$hds-color-carbon-40: #959599; // Medium-light carbon neutral.
+$hds-color-carbon-50: #77777a; // Medium carbon neutral.
+$hds-color-carbon-60: #58585b; // Medium-dark carbon neutral.
+$hds-color-carbon-70: #444447; // Dark carbon neutral.
+$hds-color-carbon-80: #2e2e32; // Very dark carbon neutral.
+$hds-color-carbon-90: #17171b; // Darkest carbon neutral. Default background for dark mode.
+$hds-color-carbon-black: #000000; // Pure black for maximum contrast text and outlines.
+$hds-color-carbon-05: #f6f6f6; // Lightest carbon neutral. Alternate background for light mode.
+$hds-color-spacesuit-white: #ffffff; // Pure white for maximum contrast text and default light backgrounds.
+$hds-border-width-thin: 1px; // Role token for single-pixel borders: card, inputs, table.
+$hds-border-width-thick: 2px; // Role token for emphasis borders: button outlines, tag/chip outlines.
+$hds-border-radius: 0px; // Default sharp (square) corners for most HDS components: text button, card, modal, header/footer, etc.
+$hds-border-radius-control: 2px; // Subtle border radius used only for small interactive controls: checkbox, radio/input tile, select, text field and textarea, tag/chip, etc.
+$hds-focus-width: 1px; // Dashed stroke width. Standardized across all dashed focus rings.
+$hds-focus-style: dashed; // All dashed focus rings use a 2,3 dasharray.
+$hds-focus-offset: 1px; // Visual gap between element and ring. May be achieved differently per mechanic (negative inset, outline-offset, etc.) but the visual result is consistent.
+$hds-layout-max-width: 1200px; // Maximum content width. Aligns with desktop-lg breakpoint.
+$hds-layout-margin-mobile: 16px; // Site margins below desktop.
+$hds-layout-margin-desktop: 32px; // Site margins at desktop+.
+$hds-layout-gutter-sm: 4px; // Used on mobile and mobile-lg breakpoints.
+$hds-layout-gutter-md: 16px; // Used on tablet through desktop-lg breakpoints.
+$hds-layout-gutter-lg: 24px; // Used on widescreen breakpoint.
+$hds-layout-gutter-xl: 32px; // Grid gutter at TV breakpoint. Not yet implemented in SCSS.
+$hds-spacing-0: 0px; // Zero spacing. Use to explicitly collapse gaps.
+$hds-spacing-1: 8px; // Tightest content relationship. Use for closely related elements within a single component.
+$hds-spacing-2: 16px; // Element stacking. Default for horizontal and vertical spacing between sibling elements.
+$hds-spacing-3: 24px; // Content section separation within the same component area.
+$hds-spacing-4: 32px; // Component separation at mobile and tablet breakpoints.
+$hds-spacing-6: 48px; // Component separation at desktop breakpoints.
+$hds-spacing-8: 64px; // Section-level vertical padding for major layout blocks (.usa-section).
+$hds-spacing-9: 72px; // Component separation at widescreen and TV breakpoints.
+$hds-spacing-15: 120px; // Layout section division at desktop-lg and below.
+$hds-spacing-30: 240px; // Layout section division at TV breakpoint.
+$hds-spacing-0-5: 4px; // Intermediate. Compact table cell padding, sub-link gaps in in-page nav. Not for layout spacing.
+$hds-spacing-1-5: 12px; // Intermediate. Table cell padding, button block padding, nav indentation, list marker gaps. Most common component-internal value.
+$hds-spacing-2-5: 20px; // Intermediate. List item separation, button inline padding, form label margins, blockquote attribution spacing.
+$hds-breakpoint-mobile: 320px; // Smallest supported viewport.
+$hds-breakpoint-mobile-lg: 480px; // Large mobile. Grid gutter: 4px.
+$hds-breakpoint-tablet: 640px; // Tablet. Grid gutter increases to 16px.
+$hds-breakpoint-tablet-lg: 880px; // Large tablet.
+$hds-breakpoint-desktop: 1024px; // Desktop. Primary content breakpoint.
+$hds-breakpoint-desktop-lg: 1200px; // Large desktop. Container max-width aligns here.
+$hds-breakpoint-widescreen: 1400px; // Widescreen. Grid gutter increases to 24px. Not yet implemented in SCSS.
+$hds-breakpoint-tv: 1920px; // TV/large display. Grid gutter increases to 32px. Not yet implemented in SCSS.
+$hds-line-height-1: 1; // 100% used for h1, h2 display, numbers
+$hds-line-height-2: 1.15; // 115% used for h3 tight
+$hds-line-height-3: 1.35; // 135% used for h4, h6, caption, figcaption
+$hds-line-height-4: 1.5; // 150% used for intro text
+$hds-line-height-5: 1.62; // 162% used for body paragraph
+$hds-line-height-6: 1.75; // 175% used for overline, metadata, label
+$hds-letter-spacing-1: 0.025em; // Caption, metadata, nav links
+$hds-letter-spacing-2: 0.1em; // Code and pre blocks in prose
+$hds-letter-spacing-3: 0.15em; // Reserve to maintain parity with USWDS scale; not currently used in HDS
+$hds-letter-spacing-neg-5: -0.05em; // H1-2xl, H1-xl, number-lg
+$hds-letter-spacing-neg-4: -0.04em; // Reserved; not currently used
+$hds-letter-spacing-neg-3: -0.03em; // H1
+$hds-letter-spacing-neg-2: -0.02em; // H2, H3, H4, H5
+$hds-letter-spacing-neg-1: -0.01em; // H6, intro
+$hds-letter-spacing-auto: 0; // Normal letter spacing
+$hds-font-weight-light: 300; // Light weight used for number display styles
+$hds-font-weight-normal: 400; // Normal/regular weight used for body text
+$hds-font-weight-medium: 500; // Medium weight used for overline
+$hds-font-weight-semibold: 600; // Semibold weight used for h4, h5, h6
+$hds-font-weight-bold: 700; // Bold weight used for h1, h2, h3, display, metadata
+$hds-font-size-4xl: 7.5rem; // H1-2XL and Number-lg. Fluid target (clamp max); 120px at the 16px root.
+$hds-font-size-3xl: 5rem; // H1-xl. Fluid target (clamp max); 80px at the 16px root.
+$hds-font-size-2xl: 3rem; // H1 and Number-md. Fluid target (clamp max); 48px at the 16px root.
+$hds-font-size-xl: 2.25rem; // H2, Blockquote, and Number-sm. Fluid target (clamp max); 36px at the 16px root.
+$hds-font-size-lg: 1.75rem; // Number-xs. Fluid target (clamp max); 28px at the 16px root.
+$hds-font-size-md: 1.375rem; // H3. Fluid target (clamp max); 22px at the 16px root.
+$hds-font-size-sm: 1.125rem; // H4. Static; 18px at the 16px root.
+$hds-font-size-xs: 1rem; // H5, P, and Button. Static; 16px at the 16px root.
+$hds-font-size-2xs: 0.875rem; // H6 and Label (form). Static; 14px at the 16px root.
+$hds-font-size-3xs: 0.75rem; // Label (div), Figcaption, Overline, Caption, and Metadata. Static; 12px at the 16px root.
+$hds-font-family-heading: 'Inter', 'Helvetica Neue', Helvetica, Arial, sans-serif; // Heading font family for h1-h6 and display text
+$hds-font-family-body: 'Public Sans Web', 'Segoe UI', Roboto, Helvetica, Arial, sans-serif; // Body text and default paragraph font
+$hds-font-family-code: 'DM Mono', 'Consolas', 'Courier', monospace; // Monospace font for code blocks and inline code