bitwrench 2.0.12 → 2.0.14

package/dist/bitwrench-lean.es5.js

@@ -1,4 +1,4 @@
-/*! bitwrench-lean v2.0.12 | BSD-2-Clause | https://deftio.github.com/bitwrench/pages */
+/*! bitwrench-lean v2.0.14 | BSD-2-Clause | https://deftio.github.com/bitwrench/pages */
 (function (global, factory) {
   typeof exports === 'object' && typeof module !== 'undefined' ? module.exports = factory() :
   typeof define === 'function' && define.amd ? define(factory) :
@@ -189,14 +189,14 @@
    */
 
   var VERSION_INFO = {
-    version: '2.0.12',
+    version: '2.0.14',
     name: 'bitwrench',
     description: 'A library for javascript UI functions.',
     license: 'BSD-2-Clause',
     homepage: 'https://deftio.github.com/bitwrench/pages',
     repository: 'git+https://github.com/deftio/bitwrench.git',
     author: 'manu a. chatterjee <deftio@deftio.com> (https://deftio.com/)',
-    buildDate: '2026-03-07T22:31:35.755Z'
+    buildDate: '2026-03-08T08:04:06.572Z'
   };
 
   /**
@@ -445,6 +445,28 @@
     return relativeLuminance(hex) > 0.179 ? '#000' : '#fff';
   }
 
+  /**
+   * Shift a color's hue toward a target hue by a given amount.
+   * Uses shortest-arc interpolation on the hue wheel.
+   * @param {string} sourceHex - Color to shift
+   * @param {string} targetHex - Color whose hue to shift toward
+   * @param {number} [amount=0.20] - 0 = no shift, 1 = full shift to target hue
+   * @returns {string} Harmonized hex color
+   */
+  function harmonize(sourceHex, targetHex, amount) {
+    if (amount === undefined) amount = 0.20;
+    if (amount === 0) return sourceHex;
+    var srcHsl = hexToHsl(sourceHex);
+    var tgtHsl = hexToHsl(targetHex);
+
+    // Shortest-arc hue interpolation
+    var diff = tgtHsl[0] - srcHsl[0];
+    if (diff > 180) diff -= 360;
+    if (diff < -180) diff += 360;
+    var newHue = (srcHsl[0] + diff * amount + 360) % 360;
+    return hslToHex([newHue, srcHsl[1], srcHsl[2]]);
+  }
+
   /**
    * Derive a full shade palette for a single semantic color.
    * @param {string} hex - Base color hex
@@ -465,29 +487,126 @@
   }
 
   /**
-   * Derive complete palette from a theme config object.
-   * @param {Object} config - Theme config with primary, secondary, tertiary, etc.
-   * @returns {Object} Full palette with shades for all 8 semantic colors + tertiary
+   * Derive the alternate (luminance-inverted) version of a single seed color.
+   * Preserves hue, mirrors lightness, adjusts saturation for readability.
+   * @param {string} hex - Seed hex color
+   * @returns {string} Alternate hex color
    */
-  function derivePalette(config) {
-    var defaults = {
+  function deriveAlternateSeed(hex) {
+    var hsl = hexToHsl(hex);
+    var h = hsl[0],
+      s = hsl[1],
+      l = hsl[2];
+    var altL, altS;
+    if (l > 50) {
+      // Light color → make dark. Map 50-100 → 30-10 range
+      altL = clip(100 - l - 10, 8, 40);
+      // Reduce saturation slightly — vivid colors at low lightness look garish
+      altS = clip(s * 0.85, 0, 100);
+    } else {
+      // Dark color → make light. Map 0-50 → 65-92 range
+      altL = clip(100 - l + 10, 60, 92);
+      // Slightly increase saturation for light variant
+      altS = clip(s * 1.1, 0, 100);
+    }
+    return hslToHex([h, altS, altL]);
+  }
+
+  /**
+   * Determine whether a palette config is "light-flavored" based on
+   * the average luminance of its seed colors.
+   * @param {Object} config - Theme config with primary, secondary hex colors
+   * @returns {boolean} true if the seeds are predominantly light
+   */
+  function isLightPalette(config) {
+    var lum = relativeLuminance(config.primary);
+    if (config.secondary) lum = (lum + relativeLuminance(config.secondary)) / 2;
+    if (config.tertiary) lum = (lum * 2 + relativeLuminance(config.tertiary)) / 3;
+    return lum > 0.179;
+  }
+
+  /**
+   * Derive a complete alternate config from a primary theme config.
+   * Each seed color is luminance-inverted; semantic colors are adjusted for
+   * the new luminance context.
+   * @param {Object} config - Primary theme config
+   * @returns {Object} Alternate theme config (same shape, inverted lightness)
+   */
+  function deriveAlternateConfig(config) {
+    var alt = {};
+    // Invert the user's seed colors
+    alt.primary = deriveAlternateSeed(config.primary);
+    alt.secondary = deriveAlternateSeed(config.secondary);
+    alt.tertiary = config.tertiary ? deriveAlternateSeed(config.tertiary) : alt.primary;
+
+    // Derive alternate surface colors from primary hue
+    var priHsl = hexToHsl(config.primary);
+    var h = priHsl[0];
+    var isLight = isLightPalette(config);
+    if (isLight) {
+      // Primary is light → alternate needs dark surfaces
+      alt.light = hslToHex([h, Math.min(priHsl[1], 15), 15]);
+      alt.dark = hslToHex([h, 5, 88]);
+    } else {
+      // Primary is dark → alternate needs light surfaces
+      alt.light = hslToHex([h, Math.min(priHsl[1], 10), 96]);
+      alt.dark = hslToHex([h, 10, 18]);
+    }
+
+    // Semantic colors: harmonize toward primary, then invert for alternate
+    var amt = config.harmonize !== undefined ? config.harmonize : 0.20;
+    var semanticDefaults = {
       success: '#198754',
       danger: '#dc3545',
-      warning: '#ffc107',
-      info: '#0dcaf0',
-      light: '#f8f9fa',
-      dark: '#212529'
+      warning: '#f0ad4e',
+      info: '#17a2b8'
     };
+    var semantics = ['success', 'danger', 'warning', 'info'];
+    for (var i = 0; i < semantics.length; i++) {
+      var key = semantics[i];
+      var seed = config[key] || semanticDefaults[key];
+      var harmonized = harmonize(seed, config.primary, amt);
+      alt[key] = deriveAlternateSeed(harmonized);
+    }
+
+    // Semantic colors are already harmonized+inverted — don't re-harmonize in derivePalette
+    alt.harmonize = 0;
+    return alt;
+  }
+
+  /**
+   * Derive complete palette from a theme config object.
+   * Semantic colors are harmonized toward the primary hue (configurable).
+   * Light/dark surface colors are tinted with the primary hue.
+   * @param {Object} config - Theme config with primary, secondary, tertiary, etc.
+   * @param {number} [config.harmonize=0.20] - Hue shift amount for semantic colors (0-1)
+   * @returns {Object} Full palette with shades for all 9 semantic colors
+   */
+  function derivePalette(config) {
+    var amt = config.harmonize !== undefined ? config.harmonize : 0.20;
+    var pri = config.primary;
+    var priHsl = hexToHsl(pri);
+    var h = priHsl[0];
+
+    // Semantic defaults — harmonized toward primary hue
+    var successBase = harmonize(config.success || '#198754', pri, amt);
+    var dangerBase = harmonize(config.danger || '#dc3545', pri, amt);
+    var warningBase = harmonize(config.warning || '#f0ad4e', pri, amt);
+    var infoBase = harmonize(config.info || '#17a2b8', pri, amt);
+
+    // Light/dark: derive from primary hue with low saturation (if not user-supplied)
+    var lightBase = config.light || hslToHex([h, 8, 97]);
+    var darkBase = config.dark || hslToHex([h, 10, 13]);
     var palette = {
       primary: deriveShades(config.primary),
       secondary: deriveShades(config.secondary),
       tertiary: deriveShades(config.tertiary),
-      success: deriveShades(config.success || defaults.success),
-      danger: deriveShades(config.danger || defaults.danger),
-      warning: deriveShades(config.warning || defaults.warning),
-      info: deriveShades(config.info || defaults.info),
-      light: deriveShades(config.light || defaults.light),
-      dark: deriveShades(config.dark || defaults.dark)
+      success: deriveShades(successBase),
+      danger: deriveShades(dangerBase),
+      warning: deriveShades(warningBase),
+      info: deriveShades(infoBase),
+      light: deriveShades(lightBase),
+      dark: deriveShades(darkBase)
     };
     return palette;
   }
@@ -559,6 +678,88 @@
     }
   };
 
+  // ---- Typography scale presets ----
+
+  var TYPE_RATIO_PRESETS = {
+    tight: 1.125,
+    normal: 1.200,
+    relaxed: 1.250,
+    dramatic: 1.333
+  };
+
+  /**
+   * Generate a modular type scale from a base size and ratio.
+   * @param {number} base - Base font size in px (default 16)
+   * @param {number} ratio - Scale ratio (default 1.200)
+   * @returns {Object} { xs, sm, base, lg, xl, '2xl', '3xl', '4xl' } in px
+   */
+  function generateTypeScale(base, ratio) {
+    if (!base) base = 16;
+    if (!ratio) ratio = 1.200;
+    return {
+      xs: Math.round(base / (ratio * ratio)),
+      sm: Math.round(base / ratio),
+      base: base,
+      lg: Math.round(base * ratio),
+      xl: Math.round(base * ratio * ratio),
+      '2xl': Math.round(base * Math.pow(ratio, 3)),
+      '3xl': Math.round(base * Math.pow(ratio, 4)),
+      '4xl': Math.round(base * Math.pow(ratio, 5))
+    };
+  }
+
+  // ---- Elevation (shadow depth) presets ----
+
+  var ELEVATION_PRESETS = {
+    flat: {
+      sm: 'none',
+      md: 'none',
+      lg: 'none',
+      xl: 'none'
+    },
+    sm: {
+      sm: '0 1px 2px rgba(0,0,0,0.05)',
+      md: '0 1px 3px rgba(0,0,0,0.08)',
+      lg: '0 2px 6px rgba(0,0,0,0.10)',
+      xl: '0 4px 12px rgba(0,0,0,0.12)'
+    },
+    md: {
+      sm: '0 1px 3px rgba(0,0,0,0.08)',
+      md: '0 2px 6px rgba(0,0,0,0.12)',
+      lg: '0 4px 12px rgba(0,0,0,0.16)',
+      xl: '0 8px 24px rgba(0,0,0,0.20)'
+    },
+    lg: {
+      sm: '0 2px 4px rgba(0,0,0,0.10)',
+      md: '0 4px 12px rgba(0,0,0,0.16)',
+      lg: '0 8px 24px rgba(0,0,0,0.22)',
+      xl: '0 16px 48px rgba(0,0,0,0.28)'
+    }
+  };
+
+  // ---- Motion (transition) presets ----
+
+  var MOTION_PRESETS = {
+    reduced: {
+      fast: '0ms',
+      normal: '0ms',
+      slow: '0ms',
+      easing: 'linear'
+    },
+    standard: {
+      fast: '100ms',
+      normal: '200ms',
+      slow: '300ms',
+      easing: 'ease-out'
+    },
+    expressive: {
+      fast: '150ms',
+      normal: '300ms',
+      slow: '500ms',
+      easing: 'cubic-bezier(0.34, 1.56, 0.64, 1)'
+    }
+  };
+
   /**
    * Default palette config — matches existing hardcoded colors
    */
@@ -568,8 +769,8 @@
     tertiary: '#006666',
     success: '#198754',
     danger: '#dc3545',
-    warning: '#ffc107',
-    info: '#0dcaf0',
+    warning: '#b38600',
+    info: '#0891b2',
     light: '#f8f9fa',
     dark: '#212529'
   };
@@ -666,18 +867,31 @@
   };
 
   /**
-   * Resolve layout config to spacing + radius objects
-   * @param {Object} config - { spacing, radius, fontSize }
-   * @returns {Object} { spacing, radius, fontSize }
+   * Resolve layout config to spacing, radius, typeScale, elevation, and motion objects.
+   * @param {Object} config - { spacing, radius, fontSize, typeRatio, elevation, motion }
+   * @returns {Object} { spacing, radius, fontSize, typeScale, elevation, motion }
    */
   function resolveLayout(config) {
     var sp = config && config.spacing || 'normal';
     var rd = config && config.radius || 'md';
     var fs = config && config.fontSize || 1.0;
+
+    // typeRatio: accept preset name or number
+    var tr = config && config.typeRatio || 'normal';
+    var ratioNum = typeof tr === 'string' ? TYPE_RATIO_PRESETS[tr] || TYPE_RATIO_PRESETS.normal : tr;
+
+    // elevation: accept preset name or object
+    var el = config && config.elevation || 'md';
+
+    // motion: accept preset name or object
+    var mo = config && config.motion || 'standard';
     return {
       spacing: typeof sp === 'string' ? SPACING_PRESETS[sp] || SPACING_PRESETS.normal : sp,
       radius: typeof rd === 'string' ? RADIUS_PRESETS[rd] || RADIUS_PRESETS.md : rd,
-      fontSize: fs
+      fontSize: fs,
+      typeScale: generateTypeScale(16, ratioNum),
+      elevation: typeof el === 'string' ? ELEVATION_PRESETS[el] || ELEVATION_PRESETS.md : el,
+      motion: typeof mo === 'string' ? MOTION_PRESETS[mo] || MOTION_PRESETS.standard : mo
     };
   }
 
@@ -703,12 +917,13 @@
   // Themed CSS generators
   // =========================================================================
 
-  function generateTypographyThemed(scope, palette) {
+  function generateTypographyThemed(scope, palette, layout) {
+    var mot = layout.motion;
     var rules = {};
     rules[scopeSelector(scope, 'a')] = {
       'color': palette.primary.base,
       'text-decoration': 'none',
-      'transition': 'color 0.15s'
+      'transition': 'color ' + mot.fast + ' ' + mot.easing
     };
     rules[scopeSelector(scope, 'a:hover')] = {
       'color': palette.primary.hover,
@@ -727,7 +942,8 @@
       'border-radius': rd.btn
     };
     rules[scopeSelector(scope, '.bw-btn:focus-visible')] = {
-      'outline': '0',
+      'outline': '2px solid currentColor',
+      'outline-offset': '2px',
       'box-shadow': '0 0 0 3px ' + palette.primary.focus
     };
 
@@ -809,14 +1025,15 @@
     var rules = {};
     var sp = layout.spacing;
     var rd = layout.radius;
+    var elev = layout.elevation;
     rules[scopeSelector(scope, '.bw-card')] = {
       'background-color': '#fff',
       'border': '1px solid ' + palette.light.border,
       'border-radius': rd.card,
-      'box-shadow': '0 1px 3px rgba(0,0,0,.06), 0 1px 2px rgba(0,0,0,.04)'
+      'box-shadow': elev.sm
     };
     rules[scopeSelector(scope, '.bw-card:hover')] = {
-      'box-shadow': '0 4px 12px rgba(0,0,0,.1), 0 2px 4px rgba(0,0,0,.06)'
+      'box-shadow': elev.md
     };
     rules[scopeSelector(scope, '.bw-card-body')] = {
       'padding': sp.card
@@ -862,6 +1079,8 @@
     };
     rules[scopeSelector(scope, '.bw-form-control:focus')] = {
       'border-color': palette.primary.border,
+      'outline': '2px solid ' + palette.primary.base,
+      'outline-offset': '-1px',
       'box-shadow': '0 0 0 0.25rem ' + palette.primary.focus
     };
     rules[scopeSelector(scope, '.bw-form-control::placeholder')] = {
@@ -1009,7 +1228,8 @@
       'border-color': palette.light.border
     };
     rules[scopeSelector(scope, '.bw-page-link:focus')] = {
-      'box-shadow': '0 0 0 0.25rem ' + palette.primary.focus
+      'outline': '2px solid ' + palette.primary.base,
+      'outline-offset': '-2px'
     };
     rules[scopeSelector(scope, '.bw-page-item.bw-active .bw-page-link')] = {
       'color': palette.primary.textOn,
@@ -1165,12 +1385,12 @@
     };
     return rules;
   }
-  function generateModalThemed(scope, palette) {
+  function generateModalThemed(scope, palette, layout) {
     var rules = {};
     rules[scopeSelector(scope, '.bw-modal-content')] = {
       'background-color': '#fff',
       'border-color': palette.light.border,
-      'box-shadow': '0 0.5rem 1rem rgba(0,0,0,0.15)'
+      'box-shadow': layout.elevation.lg
     };
     rules[scopeSelector(scope, '.bw-modal-header')] = {
       'border-bottom-color': palette.light.border
@@ -1183,12 +1403,12 @@
     };
     return rules;
   }
-  function generateToastThemed(scope, palette) {
+  function generateToastThemed(scope, palette, layout) {
     var rules = {};
     rules[scopeSelector(scope, '.bw-toast')] = {
       'background-color': '#fff',
       'border-color': 'rgba(0,0,0,0.1)',
-      'box-shadow': '0 0.5rem 1rem rgba(0,0,0,0.15)'
+      'box-shadow': layout.elevation.lg
     };
     rules[scopeSelector(scope, '.bw-toast-header')] = {
       'border-bottom-color': 'rgba(0,0,0,0.05)'
@@ -1201,12 +1421,12 @@
     });
     return rules;
   }
-  function generateDropdownThemed(scope, palette) {
+  function generateDropdownThemed(scope, palette, layout) {
     var rules = {};
     rules[scopeSelector(scope, '.bw-dropdown-menu')] = {
       'background-color': '#fff',
       'border-color': palette.light.border,
-      'box-shadow': '0 0.5rem 1rem rgba(0,0,0,0.15)'
+      'box-shadow': layout.elevation.md
     };
     rules[scopeSelector(scope, '.bw-dropdown-item')] = {
       'color': palette.dark.base
@@ -1267,7 +1487,7 @@
    * @returns {Object} CSS rules object
    */
   function generateThemedCSS(scopeName, palette, layout) {
-    return Object.assign({}, generateResetThemed(scopeName, palette), generateTypographyThemed(scopeName, palette), generateButtons(scopeName, palette, layout), generateAlerts(scopeName, palette, layout), generateBadges(scopeName, palette), generateCards(scopeName, palette, layout), generateForms(scopeName, palette, layout), generateNavigation(scopeName, palette), generateTables(scopeName, palette, layout), generateTabs(scopeName, palette), generateListGroups(scopeName, palette, layout), generatePagination(scopeName, palette), generateProgress(scopeName, palette), generateHero(scopeName, palette), generateBreadcrumbThemed(scopeName, palette), generateSpinnerThemed(scopeName, palette), generateCloseButtonThemed(scopeName, palette), generateSectionsThemed(scopeName, palette), generateAccordionThemed(scopeName, palette), generateCarouselThemed(scopeName, palette), generateModalThemed(scopeName, palette), generateToastThemed(scopeName, palette), generateDropdownThemed(scopeName, palette), generateSwitchThemed(scopeName, palette), generateSkeletonThemed(scopeName, palette), generateAvatarThemed(scopeName, palette), generateUtilityColors(scopeName, palette));
+    return Object.assign({}, generateResetThemed(scopeName, palette), generateTypographyThemed(scopeName, palette, layout), generateButtons(scopeName, palette, layout), generateAlerts(scopeName, palette, layout), generateBadges(scopeName, palette), generateCards(scopeName, palette, layout), generateForms(scopeName, palette, layout), generateNavigation(scopeName, palette), generateTables(scopeName, palette, layout), generateTabs(scopeName, palette), generateListGroups(scopeName, palette, layout), generatePagination(scopeName, palette), generateProgress(scopeName, palette), generateHero(scopeName, palette), generateBreadcrumbThemed(scopeName, palette), generateSpinnerThemed(scopeName, palette), generateCloseButtonThemed(scopeName, palette), generateSectionsThemed(scopeName, palette), generateAccordionThemed(scopeName, palette), generateCarouselThemed(scopeName, palette), generateModalThemed(scopeName, palette, layout), generateToastThemed(scopeName, palette, layout), generateDropdownThemed(scopeName, palette, layout), generateSwitchThemed(scopeName, palette), generateSkeletonThemed(scopeName, palette), generateAvatarThemed(scopeName, palette), generateUtilityColors(scopeName, palette));
   }
 
   // =========================================================================
@@ -1617,11 +1837,23 @@
   // =========================================================================
 
   /**
-   * Structural styles contain only layout, sizing, spacing, and behavior
-   * properties. No colors, backgrounds, shadows, or border-colors.
-   * These never change with themes.
+   * Structural styles — layout, sizing, spacing, positioning, and behavior.
    *
-   * @returns {Object} CSS rules object
+   * POLICY: No colors, backgrounds, shadows, or border-colors in this function.
+   * All cosmetic values belong in `defaultStyles.*` sections (unthemed defaults)
+   * or in `generateThemedCSS()` (theme-driven colors).
+   *
+   * Exception: `.bw-progress-bar-striped` uses rgba(255,255,255,.15) for the
+   * stripe pattern overlay. This is theme-neutral — a semi-transparent white
+   * gradient that creates visible stripes on any background color.
+   *
+   * Architecture:
+   *   getStructuralStyles()  → layout-only rules (never change with themes)
+   *   defaultStyles.*        → cosmetic defaults (colors, shadows, borders)
+   *   generateThemedCSS()    → palette-driven cosmetics from seed colors
+   *   generateAlternateCSS() → alternate palette (luminance-inverted)
+   *
+   * @returns {Object} CSS rules object (layout-only, theme-independent)
    */
   function getStructuralStyles() {
     var rules = {};
@@ -1730,7 +1962,7 @@
       'font-size': '0.875rem',
       'font-family': 'inherit',
       'border-radius': '6px',
-      'transition': 'all 0.15s cubic-bezier(0.4, 0, 0.2, 1)',
+      'transition': 'all 0.15s ease-out',
       'gap': '0.5rem'
     };
     rules['.bw-btn:hover'] = {
@@ -1741,7 +1973,8 @@
       'transform': 'translateY(0)'
     };
     rules['.bw-btn:focus-visible'] = {
-      'outline': '0'
+      'outline': '2px solid currentColor',
+      'outline-offset': '2px'
     };
     rules['.bw-btn:disabled'] = {
       'opacity': '0.5',
@@ -1770,7 +2003,7 @@
       'background-clip': 'border-box',
       'border': '1px solid transparent',
       'border-radius': '8px',
-      'transition': 'box-shadow 0.2s cubic-bezier(0.4,0,0.2,1), transform 0.2s cubic-bezier(0.4,0,0.2,1)',
+      'transition': 'box-shadow 0.2s ease-out, transform 0.2s ease-out',
       'margin-bottom': '1.5rem',
       'overflow': 'hidden'
     };
@@ -1803,7 +2036,7 @@
       'font-size': '0.875rem'
     };
     rules['.bw-card-hoverable'] = {
-      'transition': 'all 0.3s cubic-bezier(0.4, 0, 0.2, 1)'
+      'transition': 'all 0.3s ease-out'
     };
     rules['.bw-card-img-top'] = {
       'width': '100%',
@@ -1841,11 +2074,12 @@
       'appearance': 'none',
       'border': '1px solid transparent',
       'border-radius': '6px',
-      'transition': 'border-color 0.15s ease-in-out, box-shadow 0.15s ease-in-out',
+      'transition': 'border-color 0.15s ease-out, box-shadow 0.15s ease-out',
       'font-family': 'inherit'
     };
     rules['.bw-form-control:focus'] = {
-      'outline': '0'
+      'outline': '2px solid currentColor',
+      'outline-offset': '-1px'
     };
     rules['.bw-form-control::placeholder'] = {
       'opacity': '1'
@@ -1874,6 +2108,18 @@
       'resize': 'vertical'
     };
 
+    // Form validation (structural)
+    rules['.bw-valid-feedback'] = {
+      'display': 'block',
+      'font-size': '0.875rem',
+      'margin-top': '0.25rem'
+    };
+    rules['.bw-invalid-feedback'] = {
+      'display': 'block',
+      'font-size': '0.875rem',
+      'margin-top': '0.25rem'
+    };
+
     // Form checks (structural)
     Object.assign(rules, {
       '.bw-form-check': {
@@ -2014,8 +2260,8 @@
     // Badges (structural)
     rules['.bw-badge'] = {
       'display': 'inline-block',
-      'padding': '.4em .75em',
-      'font-size': '.875em',
+      'padding': '0.375rem 0.625rem',
+      'font-size': '0.875rem',
       'font-weight': '600',
       'line-height': '1.3',
       'text-align': 'center',
@@ -2027,12 +2273,12 @@
       'display': 'none'
     };
     rules['.bw-badge-sm'] = {
-      'font-size': '.75em',
-      'padding': '.25em .5em'
+      'font-size': '0.75rem',
+      'padding': '0.25rem 0.5rem'
     };
     rules['.bw-badge-lg'] = {
-      'font-size': '1em',
-      'padding': '.5em .9em'
+      'font-size': '1rem',
+      'padding': '0.5rem 0.875rem'
     };
     rules['.bw-badge-pill'] = {
       'border-radius': '50rem'
@@ -2053,7 +2299,7 @@
       'overflow': 'hidden',
       'text-align': 'center',
       'white-space': 'nowrap',
-      'transition': 'width .6s ease',
+      'transition': 'width 0.3s ease-out',
       'font-weight': '600'
     };
     rules['.bw-progress-bar-striped'] = {
@@ -2093,7 +2339,7 @@
       'cursor': 'pointer',
       'border': 'none',
       'background': 'transparent',
-      'transition': 'color 0.15s, border-color 0.15s',
+      'transition': 'color 0.15s ease-out, background-color 0.15s ease-out, border-color 0.15s ease-out',
       'font-family': 'inherit'
     };
     rules['.bw-nav-tabs .bw-nav-link'] = {
@@ -2157,7 +2403,13 @@
       'pointer-events': 'none'
     };
     rules['a.bw-list-group-item'] = {
-      'cursor': 'pointer'
+      'cursor': 'pointer',
+      'transition': 'background-color 0.15s ease-out, color 0.15s ease-out'
+    };
+    rules['a.bw-list-group-item:focus-visible, .bw-list-group-item:focus-visible'] = {
+      'z-index': '2',
+      'outline': '2px solid currentColor',
+      'outline-offset': '-2px'
     };
     rules['.bw-list-group-flush'] = {
       'border-radius': '0'
@@ -2188,7 +2440,7 @@
       'margin-left': '-1px',
       'line-height': '1.25',
       'text-decoration': 'none',
-      'transition': 'color 0.15s ease-in-out, background-color 0.15s ease-in-out, border-color 0.15s ease-in-out'
+      'transition': 'color 0.15s ease-out, background-color 0.15s ease-out, border-color 0.15s ease-out'
     };
     rules['.bw-page-item:first-child .bw-page-link'] = {
       'margin-left': '0',
@@ -2199,6 +2451,11 @@
       'border-top-right-radius': '0.375rem',
       'border-bottom-right-radius': '0.375rem'
     };
+    rules['.bw-page-link:focus-visible'] = {
+      'z-index': '3',
+      'outline': '2px solid currentColor',
+      'outline-offset': '-2px'
+    };
 
     // Breadcrumb (structural)
     rules['.bw-breadcrumb'] = {
@@ -2219,6 +2476,13 @@
       'padding-right': '0.5rem',
       'content': '"/"'
     };
+    rules['.bw-breadcrumb-item a'] = {
+      'text-decoration': 'none',
+      'transition': 'color 0.15s ease-out'
+    };
+    rules['.bw-breadcrumb-item.active'] = {
+      'font-weight': '500'
+    };
 
     // Hero (structural)
     rules['.bw-hero'] = {
@@ -2530,7 +2794,7 @@
       'overflow-anchor': 'none',
       'cursor': 'pointer',
       'font-family': 'inherit',
-      'transition': 'color 0.15s ease-in-out, background-color 0.15s ease-in-out'
+      'transition': 'color 0.15s ease-out, background-color 0.15s ease-out'
     };
     rules['.bw-accordion-button::after'] = {
       'flex-shrink': '0',
@@ -2540,7 +2804,7 @@
       'content': '""',
       'background-repeat': 'no-repeat',
       'background-size': '1.25rem',
-      'transition': 'transform 0.2s ease-in-out'
+      'transition': 'transform 0.2s ease-out'
     };
     rules['.bw-accordion-button:not(.bw-collapsed)::after'] = {
       'transform': 'rotate(-180deg)'
@@ -2559,7 +2823,9 @@
 
     // Modal (structural)
     rules['.bw-modal'] = {
-      'display': 'none',
+      'display': 'flex',
+      'align-items': 'center',
+      'justify-content': 'center',
       'position': 'fixed',
       'top': '0',
       'left': '0',
@@ -2569,13 +2835,14 @@
       'overflow-x': 'hidden',
       'overflow-y': 'auto',
       'opacity': '0',
-      'transition': 'opacity 0.15s linear'
+      'visibility': 'hidden',
+      'pointer-events': 'none',
+      'transition': 'opacity 0.2s ease, visibility 0.2s ease'
     };
     rules['.bw-modal.bw-modal-show'] = {
-      'display': 'flex',
-      'align-items': 'center',
-      'justify-content': 'center',
-      'opacity': '1'
+      'opacity': '1',
+      'visibility': 'visible',
+      'pointer-events': 'auto'
     };
     rules['.bw-modal-dialog'] = {
       'position': 'relative',
@@ -2642,7 +2909,7 @@
     };
     rules['.bw-carousel-track'] = {
       'display': 'flex',
-      'transition': 'transform 0.4s ease',
+      'transition': 'transform 0.3s ease-out',
       'height': '100%'
     };
     rules['.bw-carousel-slide'] = {
@@ -2772,15 +3039,23 @@
       'top': '100%',
       'left': '0',
       'z-index': '1000',
-      'display': 'none',
+      'display': 'block',
       'min-width': '10rem',
       'padding': '0.5rem 0',
       'margin': '0.125rem 0 0',
       'background-clip': 'padding-box',
-      'border-radius': '6px'
+      'border-radius': '6px',
+      'opacity': '0',
+      'visibility': 'hidden',
+      'transform': 'translateY(-4px)',
+      'pointer-events': 'none',
+      'transition': 'opacity 0.15s ease, transform 0.15s ease, visibility 0.15s ease'
     };
     rules['.bw-dropdown-menu.bw-dropdown-show'] = {
-      'display': 'block'
+      'opacity': '1',
+      'visibility': 'visible',
+      'transform': 'translateY(0)',
+      'pointer-events': 'auto'
     };
     rules['.bw-dropdown-menu-end'] = {
       'left': 'auto',
@@ -2800,6 +3075,10 @@
       'font-size': '0.9375rem',
       'transition': 'background-color 0.15s, color 0.15s'
     };
+    rules['.bw-dropdown-item:focus-visible'] = {
+      'outline': '2px solid currentColor',
+      'outline-offset': '-2px'
+    };
     rules['.bw-dropdown-divider'] = {
       'height': '0',
       'margin': '0.5rem 0',
@@ -2820,7 +3099,7 @@
       'background-position': 'left center',
       'background-repeat': 'no-repeat',
       'background-size': 'contain',
-      'transition': 'background-position 0.15s ease-in-out, background-color 0.15s ease-in-out',
+      'transition': 'background-position 0.15s ease-out, background-color 0.15s ease-out',
       'cursor': 'pointer'
     };
     rules['.bw-form-switch .bw-switch-input:checked'] = {
@@ -2893,6 +3172,401 @@
       'font-size': '1.5rem'
     };
 
+    // Stat card (structural)
+    rules['.bw-stat-card'] = {
+      'border-radius': '8px',
+      'padding': '1.25rem',
+      'border-left': '4px solid transparent',
+      'transition': 'box-shadow 0.15s ease-out, transform 0.15s ease-out'
+    };
+    rules['.bw-stat-card:hover'] = {
+      'transform': 'translateY(-1px)'
+    };
+    rules['.bw-stat-icon'] = {
+      'font-size': '1.5rem',
+      'margin-bottom': '0.5rem'
+    };
+    rules['.bw-stat-value'] = {
+      'font-size': '2rem',
+      'font-weight': '700',
+      'line-height': '1.2'
+    };
+    rules['.bw-stat-label'] = {
+      'font-size': '0.875rem',
+      'margin-top': '0.25rem'
+    };
+    rules['.bw-stat-change'] = {
+      'font-size': '0.875rem',
+      'font-weight': '500',
+      'margin-top': '0.5rem'
+    };
+
+    // Tooltip (structural)
+    rules['.bw-tooltip-wrapper'] = {
+      'position': 'relative',
+      'display': 'inline-block'
+    };
+    rules['.bw-tooltip'] = {
+      'position': 'absolute',
+      'z-index': '999',
+      'padding': '0.375rem 0.75rem',
+      'border-radius': '4px',
+      'font-size': '0.875rem',
+      'white-space': 'nowrap',
+      'pointer-events': 'none',
+      'opacity': '0',
+      'visibility': 'hidden',
+      'transition': 'opacity 0.15s ease, visibility 0.15s ease, transform 0.15s ease'
+    };
+    rules['.bw-tooltip.bw-tooltip-show'] = {
+      'opacity': '1',
+      'visibility': 'visible'
+    };
+    rules['.bw-tooltip-top'] = {
+      'bottom': '100%',
+      'left': '50%',
+      'transform': 'translateX(-50%) translateY(-4px)',
+      'margin-bottom': '4px'
+    };
+    rules['.bw-tooltip-top.bw-tooltip-show'] = {
+      'transform': 'translateX(-50%) translateY(0)'
+    };
+    rules['.bw-tooltip-bottom'] = {
+      'top': '100%',
+      'left': '50%',
+      'transform': 'translateX(-50%) translateY(4px)',
+      'margin-top': '4px'
+    };
+    rules['.bw-tooltip-bottom.bw-tooltip-show'] = {
+      'transform': 'translateX(-50%) translateY(0)'
+    };
+    rules['.bw-tooltip-left'] = {
+      'right': '100%',
+      'top': '50%',
+      'transform': 'translateY(-50%) translateX(-4px)',
+      'margin-right': '4px'
+    };
+    rules['.bw-tooltip-left.bw-tooltip-show'] = {
+      'transform': 'translateY(-50%) translateX(0)'
+    };
+    rules['.bw-tooltip-right'] = {
+      'left': '100%',
+      'top': '50%',
+      'transform': 'translateY(-50%) translateX(4px)',
+      'margin-left': '4px'
+    };
+    rules['.bw-tooltip-right.bw-tooltip-show'] = {
+      'transform': 'translateY(-50%) translateX(0)'
+    };
+
+    // Search input (structural)
+    rules['.bw-search-input'] = {
+      'position': 'relative',
+      'display': 'flex',
+      'align-items': 'center'
+    };
+    rules['.bw-search-input .bw-search-field'] = {
+      'padding-right': '2.5rem'
+    };
+    rules['.bw-search-clear'] = {
+      'position': 'absolute',
+      'right': '0.5rem',
+      'display': 'flex',
+      'align-items': 'center',
+      'justify-content': 'center',
+      'width': '1.5rem',
+      'height': '1.5rem',
+      'border': 'none',
+      'background': 'none',
+      'font-size': '1.25rem',
+      'cursor': 'pointer',
+      'padding': '0',
+      'border-radius': '50%',
+      'transition': 'color 0.15s ease-out'
+    };
+
+    // Range slider (structural)
+    rules['.bw-range-wrapper'] = {
+      'margin-bottom': '1rem'
+    };
+    rules['.bw-range-label'] = {
+      'display': 'flex',
+      'justify-content': 'space-between',
+      'align-items': 'center',
+      'margin-bottom': '0.5rem',
+      'font-size': '0.875rem',
+      'font-weight': '500'
+    };
+    rules['.bw-range-value'] = {
+      'font-weight': '600'
+    };
+    rules['.bw-range'] = {
+      'width': '100%',
+      'height': '0.5rem',
+      'padding': '0',
+      'appearance': 'none',
+      'border': 'none',
+      'border-radius': '0.25rem',
+      'cursor': 'pointer',
+      'outline': 'none'
+    };
+    rules['.bw-range:disabled'] = {
+      'opacity': '0.5',
+      'cursor': 'not-allowed'
+    };
+
+    // Media object (structural)
+    rules['.bw-media'] = {
+      'display': 'flex',
+      'align-items': 'flex-start',
+      'gap': '1rem'
+    };
+    rules['.bw-media-reverse'] = {
+      'flex-direction': 'row-reverse'
+    };
+    rules['.bw-media-img'] = {
+      'border-radius': '50%',
+      'object-fit': 'cover',
+      'flex-shrink': '0'
+    };
+    rules['.bw-media-body'] = {
+      'flex': '1',
+      'min-width': '0'
+    };
+    rules['.bw-media-title'] = {
+      'margin': '0 0 0.25rem 0',
+      'font-size': '1rem',
+      'font-weight': '600',
+      'line-height': '1.3'
+    };
+
+    // File upload (structural)
+    rules['.bw-file-upload'] = {
+      'display': 'flex',
+      'flex-direction': 'column',
+      'align-items': 'center',
+      'justify-content': 'center',
+      'padding': '2rem',
+      'border': '2px dashed transparent',
+      'border-radius': '8px',
+      'cursor': 'pointer',
+      'text-align': 'center',
+      'position': 'relative',
+      'transition': 'border-color 0.15s ease-out, background-color 0.15s ease-out'
+    };
+    rules['.bw-file-upload-icon'] = {
+      'font-size': '2rem',
+      'margin-bottom': '0.5rem'
+    };
+    rules['.bw-file-upload-text'] = {
+      'font-size': '0.875rem'
+    };
+    rules['.bw-file-upload-input'] = {
+      'position': 'absolute',
+      'width': '1px',
+      'height': '1px',
+      'padding': '0',
+      'margin': '-1px',
+      'overflow': 'hidden',
+      'clip': 'rect(0,0,0,0)',
+      'border': '0'
+    };
+
+    // Timeline (structural)
+    rules['.bw-timeline'] = {
+      'position': 'relative',
+      'padding-left': '2rem'
+    };
+    rules['.bw-timeline-item'] = {
+      'position': 'relative',
+      'padding-bottom': '1.5rem'
+    };
+    rules['.bw-timeline-item:last-child'] = {
+      'padding-bottom': '0'
+    };
+    rules['.bw-timeline-marker'] = {
+      'position': 'absolute',
+      'left': '-1.75rem',
+      'top': '0.25rem',
+      'width': '0.75rem',
+      'height': '0.75rem',
+      'border-radius': '50%'
+    };
+    rules['.bw-timeline-content'] = {
+      'padding-left': '0.5rem'
+    };
+    rules['.bw-timeline-date'] = {
+      'font-size': '0.75rem',
+      'margin-bottom': '0.25rem',
+      'font-weight': '500'
+    };
+    rules['.bw-timeline-title'] = {
+      'font-size': '1rem',
+      'font-weight': '600',
+      'margin': '0 0 0.25rem 0',
+      'line-height': '1.3'
+    };
+    rules['.bw-timeline-text'] = {
+      'font-size': '0.875rem',
+      'margin': '0',
+      'line-height': '1.5'
+    };
+
+    // Stepper (structural)
+    rules['.bw-stepper'] = {
+      'display': 'flex',
+      'gap': '0'
+    };
+    rules['.bw-step'] = {
+      'flex': '1',
+      'display': 'flex',
+      'flex-direction': 'column',
+      'align-items': 'center',
+      'text-align': 'center',
+      'position': 'relative'
+    };
+    rules['.bw-step-indicator'] = {
+      'width': '2rem',
+      'height': '2rem',
+      'border-radius': '50%',
+      'display': 'flex',
+      'align-items': 'center',
+      'justify-content': 'center',
+      'font-size': '0.875rem',
+      'font-weight': '600',
+      'position': 'relative',
+      'z-index': '1',
+      'transition': 'background-color 0.2s ease-out, color 0.2s ease-out'
+    };
+    rules['.bw-step-body'] = {
+      'margin-top': '0.5rem'
+    };
+    rules['.bw-step-label'] = {
+      'font-size': '0.875rem',
+      'font-weight': '500'
+    };
+    rules['.bw-step-description'] = {
+      'font-size': '0.75rem',
+      'margin-top': '0.125rem'
+    };
+
+    // Chip input (structural)
+    rules['.bw-chip-input'] = {
+      'display': 'flex',
+      'flex-wrap': 'wrap',
+      'align-items': 'center',
+      'gap': '0.375rem',
+      'padding': '0.375rem 0.5rem',
+      'border-radius': '6px',
+      'min-height': '2.5rem',
+      'cursor': 'text',
+      'transition': 'border-color 0.15s ease-out, box-shadow 0.15s ease-out'
+    };
+    rules['.bw-chip'] = {
+      'display': 'inline-flex',
+      'align-items': 'center',
+      'gap': '0.25rem',
+      'padding': '0.125rem 0.5rem',
+      'border-radius': '1rem',
+      'font-size': '0.8125rem',
+      'line-height': '1.5',
+      'white-space': 'nowrap'
+    };
+    rules['.bw-chip-remove'] = {
+      'display': 'inline-flex',
+      'align-items': 'center',
+      'justify-content': 'center',
+      'width': '1rem',
+      'height': '1rem',
+      'border': 'none',
+      'background': 'none',
+      'font-size': '0.875rem',
+      'cursor': 'pointer',
+      'padding': '0',
+      'border-radius': '50%',
+      'transition': 'color 0.15s ease-out, background-color 0.15s ease-out'
+    };
+    rules['.bw-chip-field'] = {
+      'flex': '1',
+      'min-width': '80px',
+      'border': 'none',
+      'outline': 'none',
+      'font-size': '0.875rem',
+      'padding': '0.125rem 0',
+      'background': 'transparent'
+    };
+
+    // Popover (structural)
+    rules['.bw-popover-wrapper'] = {
+      'position': 'relative',
+      'display': 'inline-block'
+    };
+    rules['.bw-popover-trigger'] = {
+      'cursor': 'pointer'
+    };
+    rules['.bw-popover'] = {
+      'position': 'absolute',
+      'z-index': '1000',
+      'min-width': '200px',
+      'max-width': '320px',
+      'border-radius': '8px',
+      'pointer-events': 'none',
+      'opacity': '0',
+      'visibility': 'hidden',
+      'transition': 'opacity 0.15s ease, visibility 0.15s ease, transform 0.15s ease'
+    };
+    rules['.bw-popover.bw-popover-show'] = {
+      'opacity': '1',
+      'visibility': 'visible',
+      'pointer-events': 'auto'
+    };
+    rules['.bw-popover-header'] = {
+      'padding': '0.625rem 0.875rem',
+      'font-weight': '600',
+      'font-size': '0.9375rem'
+    };
+    rules['.bw-popover-body'] = {
+      'padding': '0.75rem 0.875rem',
+      'font-size': '0.875rem',
+      'line-height': '1.5'
+    };
+    rules['.bw-popover-top'] = {
+      'bottom': '100%',
+      'left': '50%',
+      'transform': 'translateX(-50%) translateY(-8px)',
+      'margin-bottom': '8px'
+    };
+    rules['.bw-popover-top.bw-popover-show'] = {
+      'transform': 'translateX(-50%) translateY(0)'
+    };
+    rules['.bw-popover-bottom'] = {
+      'top': '100%',
+      'left': '50%',
+      'transform': 'translateX(-50%) translateY(8px)',
+      'margin-top': '8px'
+    };
+    rules['.bw-popover-bottom.bw-popover-show'] = {
+      'transform': 'translateX(-50%) translateY(0)'
+    };
+    rules['.bw-popover-left'] = {
+      'right': '100%',
+      'top': '50%',
+      'transform': 'translateY(-50%) translateX(-8px)',
+      'margin-right': '8px'
+    };
+    rules['.bw-popover-left.bw-popover-show'] = {
+      'transform': 'translateY(-50%) translateX(0)'
+    };
+    rules['.bw-popover-right'] = {
+      'left': '100%',
+      'top': '50%',
+      'transform': 'translateY(-50%) translateX(8px)',
+      'margin-left': '8px'
+    };
+    rules['.bw-popover-right.bw-popover-show'] = {
+      'transform': 'translateY(-50%) translateX(0)'
+    };
+
     // Bar chart (structural)
     rules['.bw-bar-chart-container'] = {
       'padding': '1rem',
@@ -2916,7 +3590,7 @@
     rules['.bw-bar'] = {
       'width': '100%',
       'border-radius': '3px 3px 0 0',
-      'transition': 'height 0.5s ease',
+      'transition': 'height 0.3s ease-out',
       'min-height': '4px'
     };
     rules['.bw-bar:hover'] = {
@@ -3215,6 +3889,16 @@
 
     // Responsive grid
     Object.assign(rules, defaultStyles.responsive);
+
+    // Accessibility: reduce motion for users who prefer it
+    rules['@media (prefers-reduced-motion: reduce)'] = {
+      '*, *::before, *::after': {
+        'animation-duration': '0.01ms !important',
+        'animation-iteration-count': '1 !important',
+        'transition-duration': '0.01ms !important',
+        'scroll-behavior': 'auto !important'
+      }
+    };
     return addUnderscoreAliases(rules);
   }
 
@@ -3223,9 +3907,25 @@
   // =========================================================================
 
   /**
-   * Add underscore aliases for all bw- selectors
+   * Add underscore aliases for all `.bw-` selectors.
+   *
+   * CSS CLASS NAMING CONVENTION:
+   *
+   * Canonical form:  `.bw-btn`, `.bw-card`, `.bw-table-hover`  (hyphens)
+   * Underscore alias: `.bw_btn`, `.bw_card`, `.bw_table_hover`  (underscores)
+   *
+   * Both forms are valid in HTML and produce identical results. The hyphen
+   * form is canonical (used in docs, generated CSS, component output).
+   * Underscore aliases exist because:
+   *   1. TACO attribute keys use underscores (`bw_id`, `bw_meta`) — no
+   *      quoting needed in JS object literals
+   *   2. Some users prefer underscores for consistency with JS identifiers
+   *
+   * Use `bw.normalizeClass()` to convert underscore classes to canonical
+   * hyphen form at runtime if needed.
+   *
    * @param {Object} rules - CSS rules object
-   * @returns {Object} - Rules with underscore aliases added
+   * @returns {Object} Rules with underscore aliases added (both forms work)
    */
   function addUnderscoreAliases(rules) {
     var result = {};
@@ -3245,6 +3945,27 @@
   // =========================================================================
   // Theme tokens (backwards compatible)
   // =========================================================================
+  //
+  // DESIGN NOTE — Why no CSS custom properties (CSS variables)?
+  //
+  // Bitwrench targets IE11 as Tier 1 (see dev/bw2x-compatibility.md).
+  // CSS custom properties (var(--color-primary)) are not supported in IE11.
+  //
+  // Instead, bitwrench uses class-scoped CSS generation:
+  //   1. `defaultStyles.*` provides hardcoded cosmetic defaults
+  //   2. `generateTheme(name, config)` generates a complete set of
+  //      class-scoped CSS rules from 3 seed colors (primary, secondary,
+  //      tertiary) — all components are restyled with the new palette
+  //   3. `generateAlternateCSS()` produces the alternate (dark/light)
+  //      variant scoped under `.bw-theme-alt`
+  //
+  // This achieves full theme customization without CSS variables:
+  //   bw.generateTheme('ocean', { primary: '#006666', secondary: '#cc6633' })
+  //   → generates .ocean .bw-btn-primary { background: #006666; } etc.
+  //
+  // When IE11 support is dropped, CSS custom properties can be added as
+  // an optimization (one rule with var() instead of many scoped rules).
+  // The generateTheme() API stays the same — only the output format changes.
 
   var theme = {
     colors: {
@@ -3252,8 +3973,8 @@
       secondary: '#6c757d',
       success: '#198754',
       danger: '#dc3545',
-      warning: '#ffc107',
-      info: '#0dcaf0',
+      warning: '#b38600',
+      info: '#0891b2',
       light: '#f8f9fa',
       dark: '#212529',
       white: '#fff',
@@ -3288,214 +4009,61 @@
         '4xl': '2.25rem',
         '5xl': '3rem'
       }
-    },
-    darkMode: false
+    }
   };
 
   /**
-   * Generate theme-aware dark mode CSS from a palette.
-   * Derives dark variants from the palette colors instead of using hardcoded values.
+   * Generate alternate-palette CSS scoped under `.bw-theme-alt`.
+   * Uses the same `generateThemedCSS()` pipeline as the primary palette —
+   * both sides go through identical code paths.
    *
-   * @param {Object} palette - From derivePalette()
-   * @returns {Object} CSS rules object for dark mode
+   * @param {string} name - Theme scope name (e.g. 'ocean'). '' for global.
+   * @param {Object} altPalette - From derivePalette(deriveAlternateConfig(...))
+   * @param {Object} layout - From resolveLayout()
+   * @returns {Object} CSS rules object scoped under .bw-theme-alt (+ optional .name)
    */
-  function generateDarkModeCSS(palette) {
-    var darkBg = adjustLightness(palette.primary.base, -15);
-    var darkBgHsl = hexToHsl(darkBg);
-    // Make it very dark (lightness 8-12%)
-    var bodyBg = hslToHex([darkBgHsl[0], Math.min(darkBgHsl[1], 30), 10]);
-    var surfaceBg = hslToHex([darkBgHsl[0], Math.min(darkBgHsl[1], 25), 15]);
-    var textColor = adjustLightness(palette.light.base, 5);
-    var borderColor = hslToHex([darkBgHsl[0], Math.min(darkBgHsl[1], 15), 30]);
-    return {
-      ':root.bw-dark': {
-        '--bw-body-color': textColor,
-        '--bw-body-bg': bodyBg
-      },
-      '.bw-dark body, :root.bw-dark body': {
-        'color': textColor,
-        'background-color': bodyBg
-      },
-      '.bw-dark .bw-card': {
-        'background-color': surfaceBg,
-        'border-color': borderColor,
-        'color': textColor
-      },
-      '.bw-dark .bw-card-header': {
-        'background-color': bodyBg,
-        'border-bottom-color': borderColor,
-        'color': textColor
-      },
-      '.bw-dark .bw-card-footer': {
-        'background-color': bodyBg,
-        'border-top-color': borderColor,
-        'color': textColor
-      },
-      '.bw-dark .bw-card-title': {
-        'color': textColor
-      },
-      '.bw-dark .bw-navbar': {
-        'background-color': surfaceBg,
-        'border-bottom-color': borderColor
-      },
-      '.bw-dark .bw-navbar-brand': {
-        'color': textColor
-      },
-      '.bw-dark .bw-navbar-nav .bw-nav-link': {
-        'color': adjustLightness(textColor, -15)
-      },
-      '.bw-dark .bw-navbar-nav .bw-nav-link:hover': {
-        'color': textColor
-      },
-      '.bw-dark .bw-form-control': {
-        'background-color': surfaceBg,
-        'border-color': borderColor,
-        'color': textColor
-      },
-      '.bw-dark .bw-form-label': {
-        'color': textColor
-      },
-      '.bw-dark .bw-form-text': {
-        'color': adjustLightness(textColor, -20)
-      },
-      '.bw-dark .bw-table': {
-        'color': textColor
-      },
-      '.bw-dark .bw-table > :not(caption) > * > *': {
-        'border-bottom-color': borderColor
-      },
-      '.bw-dark .bw-table > thead > tr > *': {
-        'background-color': bodyBg,
-        'color': adjustLightness(textColor, -10),
-        'border-bottom-color': borderColor
-      },
-      '.bw-dark .bw-table-striped > tbody > tr:nth-of-type(odd) > *': {
-        'background-color': 'rgba(255, 255, 255, 0.05)'
-      },
-      '.bw-dark .bw-alert': {
-        'border-color': borderColor
-      },
-      '.bw-dark .bw-list-group-item': {
-        'background-color': surfaceBg,
-        'border-color': borderColor,
-        'color': textColor
-      },
-      '.bw-dark .bw-badge': {
-        'color': textColor
-      },
-      '.bw-dark .bw-nav-tabs': {
-        'border-bottom-color': borderColor
-      },
-      '.bw-dark .bw-nav-link': {
-        'color': adjustLightness(textColor, -15)
-      },
-      '.bw-dark .bw-nav-tabs .bw-nav-link:hover': {
-        'color': textColor,
-        'border-bottom-color': borderColor
-      },
-      '.bw-dark .bw-pagination .bw-page-link': {
-        'background-color': surfaceBg,
-        'border-color': borderColor,
-        'color': textColor
-      },
-      '.bw-dark .bw-breadcrumb-item + .bw-breadcrumb-item::before': {
-        'color': adjustLightness(textColor, -20)
-      },
-      '.bw-dark .bw-breadcrumb-item.active': {
-        'color': adjustLightness(textColor, -10)
-      },
-      '.bw-dark .bw-hero-light': {
-        'background': surfaceBg,
-        'color': textColor
-      },
-      '.bw-dark .bw-progress': {
-        'background-color': surfaceBg
-      },
-      '.bw-dark .bw-section-subtitle': {
-        'color': adjustLightness(textColor, -15)
-      },
-      '.bw-dark .bw-close': {
-        'color': textColor
-      },
-      '.bw-dark .bw-accordion-item': {
-        'background-color': surfaceBg,
-        'border-color': borderColor
-      },
-      '.bw-dark .bw-accordion-button': {
-        'color': textColor
-      },
-      '.bw-dark .bw-accordion-button:not(.bw-collapsed)': {
-        'color': '#7dd3e0',
-        'background-color': 'rgba(125, 211, 224, 0.1)'
-      },
-      '.bw-dark .bw-accordion-button:hover': {
-        'background-color': bodyBg
-      },
-      '.bw-dark .bw-accordion-button:not(.bw-collapsed):hover': {
-        'background-color': 'rgba(125, 211, 224, 0.15)'
-      },
-      '.bw-dark .bw-accordion-button:focus-visible': {
-        'box-shadow': '0 0 0 0.2rem rgba(125, 211, 224, 0.3)'
-      },
-      '.bw-dark .bw-accordion-body': {
-        'border-top-color': borderColor
-      },
-      '.bw-dark .bw-carousel': {
-        'background-color': bodyBg
-      },
-      '.bw-dark .bw-carousel-control': {
-        'background-color': 'rgba(255,255,255,0.15)'
-      },
-      '.bw-dark .bw-carousel-control:hover': {
-        'background-color': 'rgba(255,255,255,0.25)'
-      },
-      '.bw-dark .bw-modal-content': {
-        'background-color': surfaceBg,
-        'border-color': borderColor
-      },
-      '.bw-dark .bw-modal-header': {
-        'border-bottom-color': borderColor
-      },
-      '.bw-dark .bw-modal-footer': {
-        'border-top-color': borderColor
-      },
-      '.bw-dark .bw-modal-title': {
-        'color': textColor
-      },
-      '.bw-dark .bw-toast': {
-        'background-color': surfaceBg,
-        'border-color': borderColor
-      },
-      '.bw-dark .bw-toast-header': {
-        'border-bottom-color': borderColor,
-        'color': textColor
-      },
-      '.bw-dark .bw-dropdown-menu': {
-        'background-color': surfaceBg,
-        'border-color': borderColor
-      },
-      '.bw-dark .bw-dropdown-item': {
-        'color': textColor
-      },
-      '.bw-dark .bw-dropdown-item:hover': {
-        'background-color': bodyBg
-      },
-      '.bw-dark .bw-dropdown-divider': {
-        'border-top-color': borderColor
-      },
-      '.bw-dark .bw-skeleton': {
-        'background': 'linear-gradient(90deg, ' + borderColor + ' 25%, ' + surfaceBg + ' 37%, ' + borderColor + ' 63%)'
-      },
-      '.bw-dark h1, .bw-dark h2, .bw-dark h3, .bw-dark h4, .bw-dark h5, .bw-dark h6': {
-        'color': textColor
-      },
-      '@media (prefers-color-scheme: dark)': {
-        ':root.bw-auto-dark body': {
-          'color': textColor,
-          'background-color': bodyBg
+  function generateAlternateCSS(name, altPalette, layout) {
+    // Generate themed CSS using the same pipeline as primary
+    var rawRules = generateThemedCSS('', altPalette, layout);
+
+    // Re-scope every selector under .bw-theme-alt (+ optional theme name)
+    var altPrefix = name ? '.' + name + '.bw-theme-alt' : '.bw-theme-alt';
+    var altRules = {};
+    for (var sel in rawRules) {
+      if (!rawRules.hasOwnProperty(sel)) continue;
+      if (sel.charAt(0) === '@') {
+        // @media / @keyframes — recurse into the block
+        var innerBlock = rawRules[sel];
+        var altInner = {};
+        for (var innerSel in innerBlock) {
+          if (!innerBlock.hasOwnProperty(innerSel)) continue;
+          altInner[altPrefix + ' ' + innerSel] = innerBlock[innerSel];
+        }
+        altRules[sel] = altInner;
+      } else {
+        // Regular selector — prefix with alt scope
+        // Handle comma-separated selectors
+        var parts = sel.split(',');
+        var scopedParts = [];
+        for (var i = 0; i < parts.length; i++) {
+          var s = parts[i].trim();
+          // 'body' selector gets special treatment: .bw-theme-alt body
+          if (s === 'body' || s.indexOf('body') === 0) {
+            scopedParts.push(altPrefix + ' ' + s);
+          } else {
+            scopedParts.push(altPrefix + ' ' + s);
+          }
         }
+        altRules[scopedParts.join(', ')] = rawRules[sel];
       }
+    }
+
+    // Add body-level overrides for the alternate surface
+    altRules[altPrefix + ' body, :root' + altPrefix + ' body'] = {
+      'color': altPalette.dark.base,
+      'background-color': altPalette.light.base
     };
+    return altRules;
   }
   function deepMerge(target, source) {
     for (var _i2 = 0, _Object$keys = Object.keys(source); _i2 < _Object$keys.length; _i2++) {
@@ -5263,8 +5831,10 @@
   /**
    * Generate responsive CSS with media query breakpoints.
    *
-   * Produces a CSS string with `@media` rules for sm (640px), md (768px),
-   * lg (1024px), and xl (1280px) breakpoints. Pass the result to `bw.injectCSS()`.
+   * Produces a CSS string with `@media (min-width)` rules for standard
+   * breakpoints. These match the grid system and theme.breakpoints:
+   *   sm: 576px, md: 768px, lg: 992px, xl: 1200px
+   * Pass the result to `bw.injectCSS()`.
    *
    * @param {string} selector - CSS selector
    * @param {Object} breakpoints - Object with keys: base, sm, md, lg, xl
@@ -5282,10 +5852,10 @@
    */
   bw.responsive = function (selector, breakpoints) {
     var sizes = {
-      sm: '640px',
+      sm: '576px',
       md: '768px',
-      lg: '1024px',
-      xl: '1280px'
+      lg: '992px',
+      xl: '1200px'
     };
     var parts = [];
     Object.keys(breakpoints).forEach(function (key) {
@@ -5422,7 +5992,8 @@
    * @returns {Element|null} Style element if in browser, null in Node.js
    * @category CSS & Styling
    * @see bw.setTheme
-   * @see bw.toggleDarkMode
+   * @see bw.applyTheme
+   * @see bw.toggleTheme
    * @example
    * bw.loadDefaultStyles();  // inject all default CSS
    */
@@ -5502,50 +6073,6 @@
     return bw.getTheme();
   };
 
-  /**
-   * Toggle dark mode on/off.
-   *
-   * Adds/removes the `bw-dark` class on `<html>` and injects dark mode CSS
-   * overrides. Pass `true`/`false` to force a mode, or omit to toggle.
-   *
-   * @param {boolean} [force] - Force dark (true) or light (false). Omit to toggle.
-   * @returns {boolean} Whether dark mode is now active
-   * @category CSS & Styling
-   * @see bw.setTheme
-   * @example
-   * bw.toggleDarkMode();        // toggle
-   * bw.toggleDarkMode(true);    // force dark
-   * bw.toggleDarkMode(false);   // force light
-   */
-  bw.toggleDarkMode = function (force) {
-    var isDark = force !== undefined ? force : !theme.darkMode;
-    theme.darkMode = isDark;
-    if (bw._isBrowser) {
-      var root = document.documentElement;
-      if (isDark) {
-        root.classList.add('bw-dark');
-        // Generate palette-aware dark mode CSS, or fall back to default
-        var palette = bw._activePalette || derivePalette(DEFAULT_PALETTE_CONFIG);
-        var darkRules = generateDarkModeCSS(palette);
-        var darkCSS = bw.css(darkRules);
-
-        // Remove existing dark styles to allow regeneration
-        var existing = document.getElementById('bw-dark-styles');
-        if (existing) existing.remove();
-        var styleEl = document.createElement('style');
-        styleEl.id = 'bw-dark-styles';
-        styleEl.textContent = darkCSS;
-        document.head.appendChild(styleEl);
-      } else {
-        root.classList.remove('bw-dark');
-        // Remove dark mode styles when switching to light
-        var darkEl = document.getElementById('bw-dark-styles');
-        if (darkEl) darkEl.remove();
-      }
-    }
-    return isDark;
-  };
-
   /**
    * Generate a complete, scoped theme from seed colors.
    *
@@ -5568,13 +6095,19 @@
    * @param {string} [config.spacing='normal'] - 'compact' | 'normal' | 'spacious'
    * @param {string} [config.radius='md'] - 'none' | 'sm' | 'md' | 'lg' | 'pill'
    * @param {number} [config.fontSize=1.0] - Base font size scale factor
+   * @param {string|number} [config.typeRatio='normal'] - 'tight' | 'normal' | 'relaxed' | 'dramatic' or a number
+   * @param {string} [config.elevation='md'] - 'flat' | 'sm' | 'md' | 'lg'
+   * @param {string} [config.motion='standard'] - 'reduced' | 'standard' | 'expressive'
+   * @param {number} [config.harmonize=0.20] - 0-1, semantic color hue shift toward primary
    * @param {boolean} [config.inject=true] - Inject into DOM (browser only)
-   * @returns {Object} { css, palette, name }
+   * @returns {Object} { css, palette, name, isLightPrimary, alternate: { css, palette } }
    * @category CSS & Styling
+   * @see bw.applyTheme
+   * @see bw.toggleTheme
    * @see bw.loadDefaultStyles
    * @example
-   * // Generate and inject an ocean theme
-   * bw.generateTheme('ocean', {
+   * // Generate and inject an ocean theme (primary + alternate)
+   * var theme = bw.generateTheme('ocean', {
    *   primary: '#0077b6',
    *   secondary: '#90e0ef',
    *   tertiary: '#00b4d8'
@@ -5583,14 +6116,16 @@
    * // Apply to a container
    * document.getElementById('app').classList.add('ocean');
    *
+   * // Toggle to alternate palette
+   * bw.toggleTheme();
+   *
    * // Generate CSS for static export (Node.js)
    * var result = bw.generateTheme('sunset', {
    *   primary: '#e76f51',
    *   secondary: '#264653',
-   *   tertiary: '#e9c46a',
    *   inject: false
    * });
-   * fs.writeFileSync('sunset.css', result.css);
+   * fs.writeFileSync('sunset.css', result.css + result.alternate.css);
    */
   bw.generateTheme = function (name, config) {
     if (!config || !config.primary || !config.secondary) {
@@ -5601,25 +6136,30 @@
     var fullConfig = Object.assign({}, DEFAULT_PALETTE_CONFIG, config);
     if (!config.tertiary) fullConfig.tertiary = fullConfig.primary;
 
-    // Derive palette
+    // Derive primary palette
     var palette = derivePalette(fullConfig);
 
-    // Store active palette for dark mode
-    bw._activePalette = palette;
-
     // Resolve layout
     var layout = resolveLayout(fullConfig);
 
-    // Generate themed CSS rules
+    // Generate primary themed CSS rules
     var themedRules = generateThemedCSS(name, palette, layout);
-
-    // Add underscore aliases
     var aliasedRules = addUnderscoreAliases(themedRules);
-
-    // Convert to CSS string
     var cssStr = bw.css(aliasedRules);
 
-    // Inject into DOM if requested and in browser
+    // Derive alternate palette (luminance-inverted)
+    var altConfig = deriveAlternateConfig(fullConfig);
+    var altPalette = derivePalette(altConfig);
+
+    // Generate alternate CSS scoped under .bw-theme-alt
+    var altRules = generateAlternateCSS(name, altPalette, layout);
+    var aliasedAltRules = addUnderscoreAliases(altRules);
+    var altCssStr = bw.css(aliasedAltRules);
+
+    // Determine if primary is light-flavored
+    var lightPrimary = isLightPalette(fullConfig);
+
+    // Inject both CSS sets into DOM if requested
     var shouldInject = config.inject !== false;
     if (shouldInject && bw._isBrowser) {
       var styleId = name ? 'bw-theme-' + name : 'bw-theme-default';
@@ -5627,6 +6167,11 @@
         id: styleId,
         append: false
       });
+      var altStyleId = name ? 'bw-theme-' + name + '-alt' : 'bw-theme-default-alt';
+      bw.injectCSS(altCssStr, {
+        id: altStyleId,
+        append: false
+      });
     }
 
     // Update bw.u color entries to reflect the palette
@@ -5645,11 +6190,65 @@
         color: '#ffffff'
       };
     }
-    return {
+
+    // Store active theme state
+    var result = {
       css: cssStr,
       palette: palette,
-      name: name
+      name: name,
+      isLightPrimary: lightPrimary,
+      alternate: {
+        css: altCssStr,
+        palette: altPalette
+      }
     };
+    bw._activeTheme = result;
+    bw._activeThemeMode = 'primary';
+    return result;
+  };
+
+  /**
+   * Apply a theme mode. Switches between primary and alternate palettes
+   * by adding/removing the `bw-theme-alt` class on `<html>`.
+   *
+   * @param {string} mode - 'primary' | 'alternate' | 'light' | 'dark'
+   * @returns {string} Active mode: 'primary' or 'alternate'
+   * @category CSS & Styling
+   * @see bw.generateTheme
+   * @see bw.toggleTheme
+   * @example
+   * bw.applyTheme('alternate');  // switch to alternate palette
+   * bw.applyTheme('dark');       // switch to whichever palette is darker
+   * bw.applyTheme('primary');    // switch back to primary palette
+   */
+  bw.applyTheme = function (mode) {
+    if (!bw._isBrowser) return mode || 'primary';
+    var root = document.documentElement;
+    var isLight = bw._activeTheme ? bw._activeTheme.isLightPrimary : true;
+    var wantAlt;
+    if (mode === 'primary') wantAlt = false;else if (mode === 'alternate') wantAlt = true;else if (mode === 'light') wantAlt = !isLight;else if (mode === 'dark') wantAlt = isLight;else wantAlt = false;
+    if (wantAlt) {
+      root.classList.add('bw-theme-alt');
+    } else {
+      root.classList.remove('bw-theme-alt');
+    }
+    bw._activeThemeMode = wantAlt ? 'alternate' : 'primary';
+    return bw._activeThemeMode;
+  };
+
+  /**
+   * Toggle between primary and alternate theme palettes.
+   *
+   * @returns {string} Active mode after toggle: 'primary' or 'alternate'
+   * @category CSS & Styling
+   * @see bw.applyTheme
+   * @see bw.generateTheme
+   * @example
+   * bw.toggleTheme();  // flip between primary and alternate
+   */
+  bw.toggleTheme = function () {
+    var current = bw._activeThemeMode || 'primary';
+    return bw.applyTheme(current === 'primary' ? 'alternate' : 'primary');
   };
 
   // Expose color utility functions on bw namespace
@@ -5661,10 +6260,18 @@
   bw.textOnColor = textOnColor;
   bw.deriveShades = deriveShades;
   bw.derivePalette = derivePalette;
+  bw.harmonize = harmonize;
+  bw.deriveAlternateSeed = deriveAlternateSeed;
+  bw.deriveAlternateConfig = deriveAlternateConfig;
+  bw.isLightPalette = isLightPalette;
 
   // Expose layout and theme presets
   bw.SPACING_PRESETS = SPACING_PRESETS;
   bw.RADIUS_PRESETS = RADIUS_PRESETS;
+  bw.TYPE_RATIO_PRESETS = TYPE_RATIO_PRESETS;
+  bw.ELEVATION_PRESETS = ELEVATION_PRESETS;
+  bw.MOTION_PRESETS = MOTION_PRESETS;
+  bw.generateTypeScale = generateTypeScale;
   bw.DEFAULT_PALETTE_CONFIG = DEFAULT_PALETTE_CONFIG;
   bw.THEME_PRESETS = THEME_PRESETS;
 
@@ -6753,9 +7360,13 @@
   /**
    * Create a sortable TACO table from an array of row objects.
    *
+   * Returns a bare `<table>` TACO — no wrapper, title, or responsive scroll.
+   * Use this when you need full control over table placement, or when embedding
+   * the table inside your own layout. For a ready-to-use table with title,
+   * responsive wrapper, and defaults (striped + hover), use `bw.makeDataTable()`.
+   *
    * Auto-detects columns from data keys if not specified. Supports click-to-sort
-   * headers with ascending/descending indicators. Returns a TACO object —
-   * render with `bw.DOM()` or `bw.html()`.
+   * headers with ascending/descending indicators.
    *
    * @param {Object} config - Table configuration
    * @param {Array<Object>} config.data - Array of row objects to display
@@ -7122,10 +7733,12 @@
   };
 
   /**
-   * Create a responsive data table with title and optional wrapper
+   * Create a ready-to-use data table with title and responsive wrapper.
    *
-   * Wraps bw.makeTable() output in a responsive container div.
-   * Adds an optional title heading above the table.
+   * Convenience wrapper around `bw.makeTable()` that adds a title heading,
+   * responsive horizontal scroll container, and defaults to striped + hover.
+   * Use this for the common case; use `bw.makeTable()` when you need a bare
+   * table element with no wrapper.
    *
    * @param {Object} config - Table configuration
    * @param {string} [config.title] - Table title heading