@nasa-hds/core 0.0.0

package/src/scss/_hds-uswds-theme.scss

@@ -0,0 +1,471 @@
+// ============================================================
+// HDS USWDS Theme Settings
+// @nasa/hds-core
+// ============================================================
+// Configures USWDS with HDS values by passing HDS token values
+// into USWDS's theme settings system.
+//
+// This file must load BEFORE @forward "uswds" in hds.scss.
+//
+// ABOUT BASE COLOR APPROXIMATIONS
+// ---------------------------------
+// USWDS theme token settings require USWDS system color token
+// strings (e.g. "gray-50"), not arbitrary hex values. The HDS
+// Carbon scale doesn't have exact matches in USWDS's system
+// palette, so the base family uses closest approximations.
+//
+// Exact matches:
+//   base-lightest = "white"  → Spacesuit White (#FFFFFF)
+//   base-darkest  = "black"  → Carbon Black    (#000000)
+//   ink           = "black"  → Carbon Black    (#000000)
+//
+// Close matches (delta ≤ 5):
+//   base-lighter  = "gray-5"  → Carbon 05 (#F6F6F6 ≈ #f0f0f0)
+//   base-light    = "gray-10" → Carbon 10 (#E3E3E3 ≈ #e6e6e6)
+//   base          = "gray-50" → Carbon 50 (#77777A ≈ #757575)
+//   base-dark     = "gray-80" → Carbon 80 (#2E2E32 ≈ #2d2d2d)
+//   base-darker   = "gray-90" → Carbon 90 (#17171B ≈ #1b1b1b)
+//
+// All HDS custom and component styles use exact $hds-color-*
+// values (not USWDS color() calls) to ensure pixel-perfect
+// adherence to the HDS spec. USWDS components that render
+// visible Carbon colors are overridden in components/_table.scss
+// with exact HDS values.
+//
+// HDS-specific colors (Carbon mid-range, International Orange,
+// Active Green) are not registered with USWDS's utility system.
+// Use $hds-color-* Sass variables or var(--hds-color-*) CSS
+// custom properties for these colors.
+//
+// PRIMARY / SECONDARY SWAP
+// ---------------------------------
+// USWDS defaults: primary = blue, secondary = red.
+// HDS Core Proposal: primary = NASA Red, secondary = NASA Blue.
+// This file swaps the families so that USWDS components like
+// .usa-button automatically render with HDS brand colors.
+// See docs/DESIGN.md Class Naming Convention for rationale.
+// ============================================================
+
+@use 'hds-tokens' as hds;
+@use 'sass:map';
+@use 'uswds-core' with (
+  // ----------------------------------------------------------
+  // Build Config
+  // ----------------------------------------------------------
+  $output-these-utilities: (),
+  $theme-show-compile-warnings: false,
+  $theme-show-notifications: false,
+  $theme-respect-user-font-size: true,
+
+  // ----------------------------------------------------------
+  // Asset Paths
+  // ----------------------------------------------------------
+  $theme-image-path: '../assets/img',
+  $theme-font-path: '../assets/fonts',
+
+  // ----------------------------------------------------------
+  // Base Color Family — Carbon Scale
+  // ----------------------------------------------------------
+  // Closest USWDS system token approximations.
+  // See header comment for delta analysis.
+  // ----------------------------------------------------------
+  $theme-color-base-family: 'gray',
+  // Carbon is neutral gray, not gray-cool
+  $theme-color-base-lightest: 'white',
+  // Spacesuit White — exact
+  $theme-color-base-lighter: 'gray-5',
+  // Carbon 05 #F6F6F6 ≈ #f0f0f0
+  $theme-color-base-light: 'gray-10',
+  // Carbon 10 #E3E3E3 ≈ #e6e6e6
+  $theme-color-base: 'gray-50',
+  // Carbon 50 #77777A ≈ #757575
+  $theme-color-base-dark: 'gray-80',
+  // Carbon 80 #2E2E32 ≈ #2d2d2d
+  $theme-color-base-darker: 'gray-90',
+  // Carbon 90 #17171B ≈ #1b1b1b
+  $theme-color-base-darkest: 'black',
+  // Carbon Black — exact
+  $theme-color-base-ink: 'black',
+
+  // Carbon Black — exact
+  // ----------------------------------------------------------
+  // Primary Color Family — NASA Red
+  // ----------------------------------------------------------
+  // HDS primary = brand action color (CTA, navigation away).
+  // USWDS default was blue; swapped per HDS Core Proposal so
+  // .usa-button automatically renders NASA Red.
+  // ----------------------------------------------------------
+  $theme-color-primary-family: 'red',
+  $theme-color-primary-lighter: 'red-10',
+  $theme-color-primary-light: 'red-30',
+  $theme-color-primary: 'red-50',
+  $theme-color-primary-vivid: 'red-cool-50v',
+  $theme-color-primary-dark: 'red-60v',
+  $theme-color-primary-darker: 'red-70v',
+
+  // ----------------------------------------------------------
+  // Secondary Color Family — NASA Blue
+  // ----------------------------------------------------------
+  // HDS secondary = interactive/on-page actions.
+  // USWDS default was red; swapped per HDS Core Proposal so
+  // .usa-button--secondary automatically renders NASA Blue.
+  // ----------------------------------------------------------
+  $theme-color-secondary-family: 'blue',
+  $theme-color-secondary-lighter: 'blue-10v',
+  $theme-color-secondary-light: 'blue-40v',
+  $theme-color-secondary: 'blue-60v',
+  $theme-color-secondary-vivid: 'blue-warm-60v',
+  $theme-color-secondary-dark: 'blue-70v',
+  $theme-color-secondary-darker: 'blue-80v',
+
+  // ----------------------------------------------------------
+  // Accent Cool
+  // ----------------------------------------------------------
+  $theme-color-accent-cool-lighter: 'blue-cool-5v',
+  $theme-color-accent-cool-light: 'blue-cool-20v',
+  $theme-color-accent-cool: 'cyan-30v',
+  $theme-color-accent-cool-dark: 'blue-cool-40v',
+  $theme-color-accent-cool-darker: 'blue-cool-60v',
+
+  // ----------------------------------------------------------
+  // Accent Warm
+  // ----------------------------------------------------------
+  $theme-color-accent-warm-lighter: 'orange-10v',
+  $theme-color-accent-warm-light: 'orange-20v',
+  $theme-color-accent-warm: 'orange-40v',
+  $theme-color-accent-warm-dark: 'orange-50v',
+  $theme-color-accent-warm-darker: 'orange-60v',
+
+  // ----------------------------------------------------------
+  // State: Info
+  // ----------------------------------------------------------
+  $theme-color-info-lighter: 'cyan-5',
+  $theme-color-info-light: 'cyan-20',
+  $theme-color-info: 'cyan-30v',
+  $theme-color-info-dark: 'cyan-40v',
+  $theme-color-info-darker: 'blue-cool-60',
+
+  // ----------------------------------------------------------
+  // State: Error
+  // ----------------------------------------------------------
+  $theme-color-error-lighter: 'red-warm-10',
+  $theme-color-error-light: 'red-warm-30v',
+  $theme-color-error: 'red-warm-50v',
+  $theme-color-error-dark: 'red-60v',
+  $theme-color-error-darker: 'red-70',
+
+  // ----------------------------------------------------------
+  // State: Warning
+  // ----------------------------------------------------------
+  $theme-color-warning-lighter: 'yellow-5',
+  $theme-color-warning-light: 'yellow-10v',
+  $theme-color-warning: 'gold-20v',
+  $theme-color-warning-dark: 'gold-30v',
+  $theme-color-warning-darker: 'gold-50v',
+
+  // ----------------------------------------------------------
+  // State: Success
+  // ----------------------------------------------------------
+  $theme-color-success-lighter: 'green-cool-5v',
+  $theme-color-success-light: 'green-cool-10v',
+  $theme-color-success: 'green-cool-30v',
+  $theme-color-success-dark: 'green-cool-40v',
+  $theme-color-success-darker: 'green-cool-60v',
+
+  // ----------------------------------------------------------
+  // State: Disabled
+  // ----------------------------------------------------------
+  $theme-color-disabled-lighter: 'gray-20',
+  $theme-color-disabled-light: 'gray-40',
+  $theme-color-disabled: 'gray-50',
+  $theme-color-disabled-dark: 'gray-70',
+  $theme-color-disabled-darker: 'gray-90',
+
+  // ----------------------------------------------------------
+  // State: Emergency
+  // ----------------------------------------------------------
+  $theme-color-emergency: 'red-warm-60v',
+  $theme-color-emergency-dark: 'red-warm-80',
+
+  // ----------------------------------------------------------
+  // Color Schemes
+  // ----------------------------------------------------------
+  // HDS links use body text color (not brand color) for the
+  // text itself. The underline/arrow provides the visual
+  // affordance. These "ink" values prevent bare <a> tags from
+  // turning NASA Red after the primary/secondary swap.
+  // Full HDS link styling (underline, arrow) is applied via
+  // .usa-link overrides in components/_link.scss.
+  // ----------------------------------------------------------
+  $theme-body-background-color: 'white',
+  $theme-text-color: 'ink',
+  $theme-text-reverse-color: 'base-lightest',
+  $theme-link-color: 'ink',
+  $theme-link-visited-color: 'ink',
+  $theme-link-hover-color: 'ink',
+  $theme-link-active-color: 'ink',
+  $theme-link-reverse-color: 'base-lightest',
+  $theme-link-reverse-hover-color: 'base-lightest',
+  $theme-link-reverse-active-color: 'base-lightest',
+
+  // ----------------------------------------------------------
+  // Focus
+  // ----------------------------------------------------------
+  // HDS focus: 1px dashed, palette-aware via base/_focus.scss.
+  // These USWDS settings prevent the default blue ring from
+  // appearing on USWDS components. Exact HDS colors are
+  // applied via --hds-palette-muted in the :focus-visible
+  // rule; these are fallbacks only.
+  // ----------------------------------------------------------
+  // Carbon 60 #58585B ≈ gray-60 #565c65
+  $theme-focus-color: 'gray-60',
+  $theme-focus-offset: 2px,
+  $theme-focus-style: dashed,
+  // intentionally independent of border-width; may diverge for WCAG 2.2 focus-appearance (AAA)
+  $theme-focus-width: 1px,
+
+  // ----------------------------------------------------------
+  // Font Families
+  // ----------------------------------------------------------
+  $theme-font-type-sans: 'public-sans',
+  $theme-font-type-mono: 'dm-mono',
+  $theme-font-type-serif: 'inter',
+  $theme-font-role-heading: 'serif',
+  $theme-font-role-body: 'sans',
+  $theme-font-role-ui: 'serif',
+  $theme-font-role-code: 'mono',
+  $theme-font-role-alt: 'mono',
+
+  $theme-typeface-tokens: (
+    'inter': (
+      'display-name': 'Inter',
+      // Normalization disabled — $theme-respect-user-font-size: true
+      // Measured cap-height: 1490/2048 UPM = 72.8%
+      // (0.76px taller caps than Public Sans at 16px)
+      'cap-height': 364px,
+      'stack': "'Helvetica Neue', Helvetica, Arial, sans-serif",
+    ),
+    'dm-mono': (
+      'display-name': 'DM Mono',
+      // Normalization disabled — $theme-respect-user-font-size: true
+      // Measured cap-height: ~698/1000 UPM = 69.8%
+      // (0.22px taller caps than Public Sans at 16px)
+      'cap-height': 364px,
+      'stack': "'Consolas', 'Courier', monospace",
+    )
+  ),
+
+  $theme-font-serif-custom-src: (
+    dir: 'inter',
+    roman: (
+      100: false,
+      200: false,
+      300: 'Inter-Light',
+      400: 'Inter-Regular',
+      500: 'Inter-Medium',
+      600: 'Inter-SemiBold',
+      700: 'Inter-Bold',
+      800: false,
+      900: false,
+    ),
+    italic: (
+      100: false,
+      200: false,
+      300: 'Inter-LightItalic',
+      400: 'Inter-Italic',
+      500: 'Inter-MediumItalic',
+      600: 'Inter-SemiBoldItalic',
+      700: 'Inter-BoldItalic',
+      800: false,
+      900: false,
+    )
+  ),
+
+  // DM Mono only ships Light (300), Regular (400), and
+  // Medium (500) weights.
+  $theme-font-mono-custom-src: (
+      dir: 'dm-mono',
+      roman: (
+        100: false,
+        200: false,
+        300: 'DMMono-Light',
+        400: 'DMMono-Regular',
+        500: 'DMMono-Medium',
+        600: false,
+        700: false,
+        800: false,
+        900: false,
+      ),
+      italic: (
+        100: false,
+        200: false,
+        300: 'DMMono-LightItalic',
+        400: 'DMMono-Italic',
+        500: 'DMMono-MediumItalic',
+        600: false,
+        700: false,
+        800: false,
+        900: false,
+      )
+    ),
+
+  // ----------------------------------------------------------
+  // Type Scale
+  // ----------------------------------------------------------
+  $theme-type-scale-3xs: 1,
+  $theme-type-scale-2xs: 3,
+  $theme-type-scale-xs: 5,
+  $theme-type-scale-sm: 7,
+  $theme-type-scale-md: 9,
+  $theme-type-scale-lg: 11,
+  $theme-type-scale-xl: 13,
+  $theme-type-scale-2xl: 15,
+  $theme-type-scale-3xl: 18,
+
+  // ----------------------------------------------------------
+  // Element Type Defaults
+  // ----------------------------------------------------------
+  $theme-body-font-family: 'body',
+  $theme-body-font-size: 'xs',
+  $theme-h1-font-size: '2xl',
+  $theme-h2-font-size: 'xl',
+  $theme-h3-font-size: 'md',
+  $theme-h4-font-size: 'sm',
+  $theme-h5-font-size: 'xs',
+  $theme-h6-font-size: '2xs',
+  $theme-small-font-size: '3xs',
+  $theme-display-font-size: '3xl',
+
+  // ----------------------------------------------------------
+  // Line Heights & Weights
+  // ----------------------------------------------------------
+  // USWDS scale integers for unstyled elements (HDS overrides these).
+  $theme-body-line-height: 5,
+  // → 1.62
+  $theme-heading-line-height: 1,
+  // → 1.0
+  $theme-lead-line-height: 4,
+  // → 1.5
+  $theme-input-line-height: 2,
+  // → 1.15
+  $theme-font-weight-thin: false,
+  $theme-font-weight-light: hds.$hds-font-weight-light,
+  $theme-font-weight-normal: hds.$hds-font-weight-normal,
+  $theme-font-weight-medium: hds.$hds-font-weight-medium,
+  $theme-font-weight-semibold: hds.$hds-font-weight-semibold,
+  $theme-font-weight-bold: hds.$hds-font-weight-bold,
+  $theme-font-weight-heavy: false,
+  // ----------------------------------------------------------
+  // Grid & Layout
+  // ----------------------------------------------------------
+  $theme-utility-breakpoints: (
+      'card': false,
+      'card-lg': false,
+      'mobile': true,
+      'mobile-lg': true,
+      'tablet': true,
+      'tablet-lg': true,
+      'desktop': true,
+      'desktop-lg': true,
+      'widescreen': true
+    ),
+
+  $theme-column-gap-sm: 2px,
+  $theme-column-gap-md: 2,
+  $theme-column-gap-lg: 3,
+  $theme-column-gap-mobile: '05',
+  $theme-column-gap-desktop: 2,
+  // USWDS Constraint: The layout grid natively only supports a two-tier mobile/desktop gutter split.
+  // The proposal specifies wider gutters at widescreen (grid-gap-3 = 24px) and tv (grid-gap-4 = 32px),
+  // which cannot be applied natively via these theme settings.
+  $theme-site-margins-breakpoint: 'desktop',
+  $theme-site-margins-width: 4,
+  $theme-site-margins-mobile-width: 2,
+  $theme-grid-container-max-width: 'desktop-lg',
+  $theme-footer-max-width: 'widescreen',
+  $theme-header-max-width: 'widescreen',
+  $theme-header-min-width: 'desktop',
+
+  // ----------------------------------------------------------
+  // Table Settings
+  // ----------------------------------------------------------
+  // Closest USWDS token approximations for table colors.
+  // Exact HDS values are applied via component overrides in
+  // components/_table.scss. These settings provide valid
+  // USWDS tokens for structural styles (layout, spacing,
+  // variant logic) and prevent color() function errors.
+  //
+  // Sorted column backgrounds have no close USWDS match —
+  // they're NASA Blue tints in light mode and white tints in
+  // dark mode. Using "gray-5" as a structural placeholder;
+  // overridden with exact hex in components.
+  // ----------------------------------------------------------
+  $theme-table-background-color: 'white',
+  $theme-table-text-color: 'ink',
+  $theme-table-header-background-color: 'gray-10',
+  $theme-table-header-text-color: 'ink',
+  $theme-table-border-color: 'gray-10',
+  $theme-table-stripe-background-color: 'gray-5',
+  $theme-table-stripe-text-color: 'default',
+  $theme-table-sorted-background-color: 'gray-5',
+  $theme-table-sorted-stripe-background-color: 'gray-5',
+  $theme-table-sorted-header-background-color: 'gray-10',
+  $theme-table-sorted-icon-color: 'blue-60v',
+  $theme-table-unsorted-icon-color: 'gray-50',
+  $theme-table-sticky-top-offset: 0,
+
+  // ----------------------------------------------------------
+  // Form Settings
+  // ----------------------------------------------------------
+  // Figma shows input values, help text, and error messages in
+  // Public Sans (body). Labels and legends are overridden to
+  // Inter (heading) in components/_form.scss.
+  //
+  // Input background: left at USWDS default. Checkbox/radio
+  // indicator backgrounds are set via ::before in
+  // components/_form.scss using --hds-palette-input-bg to
+  // avoid leaking white bg to fieldsets and group containers.
+  //
+  // Checkbox/radio size: USWDS default is 2.5 units (20px).
+  // Figma shows 18px (2.25 units — not a clean USWDS token).
+  // Keeping default, flagged for creative director review.
+  // ----------------------------------------------------------
+  $theme-form-font-family: 'body',
+
+  // ----------------------------------------------------------
+  // Component Settings
+  // ----------------------------------------------------------
+  // Border radius
+  $theme-button-border-radius: hds.$hds-border-radius,
+  $theme-card-border-radius: hds.$hds-border-radius,
+  $theme-checkbox-border-radius: hds.$hds-border-radius-control,
+  $theme-input-tile-border-radius: hds.$hds-border-radius-control,
+  $theme-modal-border-radius: hds.$hds-border-radius,
+  $theme-pagination-button-border-radius: hds.$hds-border-radius,
+  $theme-summary-box-border-radius: hds.$hds-border-radius,
+
+  // Border / stroke width
+  $theme-button-stroke-width: hds.$hds-border-width-thick,
+  $theme-card-border-width: hds.$hds-border-width-thin,
+  $theme-input-select-border-width: hds.$hds-border-width-thin,
+  $theme-input-tile-border-width: hds.$hds-border-width-thin,
+  $theme-input-state-border-width: hds.$hds-border-width-thin,
+  $theme-pagination-button-border-width: hds.$hds-border-width-thin,
+  $theme-summary-box-border-width: hds.$hds-border-width-thin,
+
+  // Button typography
+  $theme-button-font-family: 'heading',
+
+  // Pagination
+  $theme-pagination-font-family: 'heading',
+
+  // ----------------------------------------------------------
+  // In-Page Navigation
+  // ----------------------------------------------------------
+  $theme-in-page-nav-background-color: 'white',
+  $theme-in-page-nav-background-padding: 0,
+  $theme-in-page-nav-background-radius: 0,
+  $theme-in-page-nav-bar-color: 'secondary',
+  $theme-in-page-nav-bar-width: hds.$hds-border-width-thick,
+  $theme-in-page-nav-font-family: 'heading'
+);

package/src/scss/base/_component-properties.scss

@@ -0,0 +1,56 @@
+// ============================================================
+// HDS Component-Level Custom Properties
+// @nasa/hds-core
+// ============================================================
+// Component-specific CSS custom properties derived from USWDS
+// theme settings. These provide customization hooks for CSS-only
+// consumers who cannot access Sass variables or theme settings.
+//
+// These are semantic aliases, not primitives. They map from
+// USWDS theme token values to component-namespaced custom
+// properties for easier theming in @layer site.
+//
+// Generated custom properties from tokens.json live in
+// _custom-properties.scss. This file contains manual component
+// derivations that don't belong in the design token source.
+// ============================================================
+
+@use 'hds-tokens' as hds;
+@use 'hds-uswds-theme';
+@use 'uswds-core' as *;
+
+@layer hds-base {
+  :root {
+    // ========================================================
+    // Component Border Radius
+    // ========================================================
+    // Derived from USWDS $theme-*-border-radius settings,
+    // which pull from HDS primitives ($hds-border-radius,
+    // $hds-border-radius-control).
+
+    --hds-button-border-radius: #{$theme-button-border-radius};
+    --hds-card-border-radius: #{$theme-card-border-radius};
+    --hds-checkbox-border-radius: #{$theme-checkbox-border-radius};
+    --hds-input-tile-border-radius: #{$theme-input-tile-border-radius};
+    --hds-modal-border-radius: #{$theme-modal-border-radius};
+    --hds-pagination-border-radius: #{$theme-pagination-button-border-radius};
+    --hds-summary-border-radius: #{$theme-summary-box-border-radius};
+
+    // ========================================================
+    // Component Border Width
+    // ========================================================
+    // Derived from USWDS $theme-*-border-width / stroke-width
+    // settings, which pull from HDS primitives
+    // ($hds-border-width-thin, $hds-border-width-thick).
+
+    --hds-accordion-border-width: 0; // HDS design: no border
+    --hds-button-border-width: #{$theme-button-stroke-width};
+    --hds-card-border-width: #{$theme-card-border-width};
+    --hds-input-select-border-width: #{$theme-input-select-border-width};
+    --hds-input-state-border-width: #{$theme-input-state-border-width};
+    --hds-input-tile-border-width: #{$theme-input-tile-border-width};
+    --hds-pagination-border-width: #{$theme-pagination-button-border-width};
+    --hds-summary-border-width: #{$theme-summary-box-border-width};
+    --hds-table-border-width: #{hds.$hds-border-width-thin};
+  }
+}