@usefragments/ui 1.0.0

package/src/tokens/_derive.scss

@@ -0,0 +1,513 @@
+// ============================================
+// @usefragments/ui Token Derivation Functions
+// ============================================
+//
+// Functions that derive complete token sets from seed values.
+// These enable the seed-based design system where users configure
+// ~5-10 seeds and everything else derives automatically.
+//
+// ============================================
+
+@use 'sass:color';
+@use 'sass:math';
+@use 'palettes' as *;
+
+// --------------------------------------------
+// Color Utility Functions
+// --------------------------------------------
+
+/// Check if a color is considered "dark" (luminance < 0.5)
+/// @param {Color} $color - Color to check
+/// @return {Boolean} True if dark
+@function is-dark-color($color) {
+  // oklch lightness is perceptually uniform (0-1 range)
+  @return color.channel($color, 'lightness', $space: oklch) < 0.5;
+}
+
+/// Get appropriate contrast color (black or white)
+/// @param {Color} $bg-color - Background color
+/// @return {Color} Black or white for best contrast
+@function contrast-color($bg-color) {
+  @if is-dark-color($bg-color) {
+    @return #ffffff;
+  } @else {
+    @return #000000;
+  }
+}
+
+// --------------------------------------------
+// Accent Color Derivation
+// --------------------------------------------
+
+/// Derive hover state for accent color
+/// Handles extreme lightness values (near-black/near-white) by reversing
+/// the adjustment direction to ensure a visible hover state.
+/// @param {Color} $base - Base accent color
+/// @param {Boolean} $is-dark - Whether in dark mode
+/// @return {Color} Hover state color
+@function derive-accent-hover($base, $is-dark: false) {
+  $l: color.channel($base, 'lightness', $space: oklch);
+
+  @if $is-dark {
+    @if $l > 0.85 {
+      // Very light accent on dark bg: darken for visible hover
+      @return color.adjust($base, $lightness: -0.05, $space: oklch);
+    }
+    // Standard dark mode: lighten for hover
+    @return color.adjust($base, $lightness: 0.04, $space: oklch);
+  } @else {
+    @if $l < 0.15 {
+      // Very dark accent on light bg: lighten for visible hover
+      @return color.adjust($base, $lightness: 0.09, $space: oklch);
+    }
+    // Standard light mode: darken for hover
+    @return color.adjust($base, $lightness: -0.05, $space: oklch);
+  }
+}
+
+/// Derive active state for accent color
+/// Handles extreme lightness values (near-black/near-white) by reversing
+/// the adjustment direction to ensure a visible active/pressed state.
+/// @param {Color} $base - Base accent color
+/// @param {Boolean} $is-dark - Whether in dark mode
+/// @return {Color} Active state color
+@function derive-accent-active($base, $is-dark: false) {
+  $l: color.channel($base, 'lightness', $space: oklch);
+
+  @if $is-dark {
+    @if $l > 0.85 {
+      // Very light accent on dark bg: darken more for active
+      @return color.adjust($base, $lightness: -0.08, $space: oklch);
+    }
+    // Standard dark mode: lighten more for active
+    @return color.adjust($base, $lightness: 0.07, $space: oklch);
+  } @else {
+    @if $l < 0.15 {
+      // Very dark accent on light bg: lighten more for active
+      @return color.adjust($base, $lightness: 0.14, $space: oklch);
+    }
+    // Standard light mode: darken more for active
+    @return color.adjust($base, $lightness: -0.09, $space: oklch);
+  }
+}
+
+/// Derive the dark-mode accent from the brand.
+/// Chroma-aware: chroma is PRESERVED (never clamped), so a saturated brand stays
+/// vibrant in dark mode instead of washing out. Lightness is only lifted for
+/// near-grey/chroma-0 brands via the `0.95 - 2c` term — a vibrant brand (high c)
+/// keeps its own lightness, while a neutral grey brand (c≈0) lifts toward ~0.85 so
+/// it stays visible on dark surfaces where lightness is the only perceptual cue.
+/// Final lightness clamped to [0.55, 0.85]. Mirrors the runtime OKLCH derivation in
+/// _variables.scss (the SCSS-computed fallback for browsers without relative color).
+/// @param {Color} $brand - Brand color
+/// @return {Color} Dark-mode accent
+@function derive-dark-accent($brand) {
+  $l: color.channel($brand, 'lightness', $space: oklch);
+  $c: color.channel($brand, 'chroma', $space: oklch);
+  // color.channel returns lightness as a percentage; normalize to a unitless 0–1
+  // ratio so the comparisons below share a scale with the 0.55/0.85 bounds.
+  $l-num: $l;
+  @if not math.is-unitless($l) {
+    $l-num: math.div($l, 100%);
+  }
+  // grey-lift only kicks in for low-chroma brands; vibrant brands keep their own L.
+  $target-l: math.max($l-num, 0.95 - 2 * $c);
+  $clamped-l: math.max(0.55, math.min($target-l, 0.85));
+  @return oklch($clamped-l $c color.channel($brand, 'hue', $space: oklch));
+}
+
+// --------------------------------------------
+// Contrast Correction
+// --------------------------------------------
+
+/// Progressively darken (light mode) or lighten (dark mode) a foreground
+/// color until it meets the given WCAG contrast target against a background.
+/// Used to guarantee AAA (7:1) text contrast on tinted palette surfaces.
+/// @param {Color} $fg - Foreground color to adjust
+/// @param {Color} $bg - Background color to check against
+/// @param {Number} $target - Target contrast ratio (default: 7 for AAA)
+/// @param {Boolean} $is-dark - Whether in dark mode (lighten instead of darken)
+/// @return {Color} Adjusted foreground color meeting the target ratio
+@function ensure-contrast($fg, $bg, $target: 7, $is-dark: false) {
+  $adjusted: $fg;
+  @for $i from 1 through 40 {
+    @if wcag-contrast($adjusted, $bg) < $target {
+      @if $is-dark {
+        $adjusted: color.adjust($adjusted, $lightness: 2%, $space: oklch);
+      } @else {
+        $adjusted: color.adjust($adjusted, $lightness: -2%, $space: oklch);
+      }
+    }
+  }
+  @return $adjusted;
+}
+
+// --------------------------------------------
+// Surface/Background Derivation
+// --------------------------------------------
+
+/// Derive surface/background tokens from a neutral palette
+/// Maps shade levels to semantic surface tokens for visual depth layering.
+/// For colorful palettes (ice, earth, sand, fire), light mode uses tinted backgrounds.
+/// @param {Map} $palette - Neutral palette map
+/// @param {Boolean} $is-dark - Whether in dark mode
+/// @param {String} $palette-name - Palette name for colorful detection (default: 'stone')
+/// @return {Map} Surface token values
+@function derive-surfaces($palette, $is-dark: false, $palette-name: 'stone') {
+  @if $is-dark {
+    @if $palette-name == 'stone' or $palette-name == 'mono' {
+      @return (
+        primary: #000000,
+        secondary: #050505,
+        tertiary: #111111,
+        elevated: #151515,
+        subtle: #080808,
+        hover: rgba(255, 255, 255, 0.055),
+        active: rgba(255, 255, 255, 0.085)
+      );
+    }
+
+    // Dark mode: darker = more recessed, lighter = elevated
+    // Hover/active opacities tuned for subdued dense-UI aesthetic: hairlines and
+    // alpha overlays do most of the depth work rather than heavy color shifts.
+    @return (
+      primary: get-shade($palette, 950),           // Page background (darkest)
+      secondary: get-shade($palette, 900),         // Sidebar, panels
+      tertiary: get-shade($palette, 800),          // Content areas (lighter)
+      elevated: interpolate-shade($palette, 875),  // Cards (distinct from secondary)
+      subtle: interpolate-shade($palette, 925),    // Between primary and secondary
+      hover: rgba(255, 255, 255, 0.035),           // Interactive hover
+      active: rgba(255, 255, 255, 0.06)            // Interactive active
+    );
+  }
+
+  // Light mode: colorful palettes get tinted backgrounds
+  $is-colorful: $palette-name != 'stone';
+  @if $is-colorful {
+    @return (
+      primary: get-shade($palette, 50),            // Tinted page background
+      secondary: get-shade($palette, 100),         // Tinted secondary panels
+      tertiary: get-shade($palette, 200),          // Deeper tint for nested sections
+      elevated: #ffffff,                           // Cards, modals (floats above)
+      subtle: get-shade($palette, 50),             // Very subtle tinted background
+      hover: rgba(0, 0, 0, 0.04),                  // Interactive hover
+      active: rgba(0, 0, 0, 0.06)                  // Interactive active
+    );
+  }
+
+  // Stone palette: neutral white backgrounds
+  @return (
+    primary: #ffffff,                            // Page background (white)
+    secondary: get-shade($palette, 100),         // Sidebar, secondary panels
+    tertiary: get-shade($palette, 100),          // Nested sections
+    elevated: #ffffff,                           // Cards, modals (floats above)
+    subtle: get-shade($palette, 50),             // Very subtle backgrounds
+    hover: rgba(0, 0, 0, 0.04),                  // Interactive hover
+    active: rgba(0, 0, 0, 0.06)                  // Interactive active
+  );
+}
+
+/// Derive document/application canvas tokens used by base body styles and
+/// large layout containers. The defaults intentionally separate the page
+/// canvas from the primary main surface so app shells can expose chrome around
+/// the focused content region.
+/// @param {Map} $palette - Neutral palette map
+/// @param {Boolean} $is-dark - Whether in dark mode
+/// @param {String} $palette-name - Palette name for colorful detection
+/// @return {Map} Body and main background values
+@function derive-app-surfaces($palette, $is-dark: false, $palette-name: 'stone') {
+  @if $is-dark {
+    @if $palette-name == 'stone' or $palette-name == 'mono' or $palette-name == 'wind' {
+      @return (
+        body: #000000,
+        main: #050505
+      );
+    }
+
+    @return (
+      body: get-shade($palette, 800),
+      main: get-shade($palette, 900)
+    );
+  }
+
+  @if $palette-name == 'stone' or $palette-name == 'wind' {
+    @return (
+      body: get-shade($palette, 100),
+      main: #ffffff
+    );
+  }
+
+  @return (
+    body: get-shade($palette, 100),
+    main: get-shade($palette, 50)
+  );
+}
+
+// --------------------------------------------
+// Text Color Derivation
+// --------------------------------------------
+
+/// Derive text tokens from a neutral palette.
+/// For colorful palettes in light mode, applies ensure-contrast() to meet
+/// WCAG AAA (7:1) against tinted backgrounds (palette[50]).
+/// @param {Map} $palette - Neutral palette map
+/// @param {Boolean} $is-dark - Whether in dark mode
+/// @param {String} $palette-name - Palette name for background detection (default: 'stone')
+/// @return {Map} Text token values
+@function derive-text($palette, $is-dark: false, $palette-name: 'stone') {
+  @if $is-dark {
+    @if $palette-name == 'stone' or $palette-name == 'mono' {
+      @return (
+        primary: #ededed,
+        secondary: #a1a1a1,
+        tertiary: #7a7a7a,
+        inverse: #000000
+      );
+    }
+
+    // Dark mode: neutral white text on all palettes.
+    // Palette-tinted text (e.g. green-on-green-dark) looks muddy and reduces
+    // readability. Major polished dark themes use neutral white text regardless
+    // of background tint.
+    // Opacity ladder tuned for a subdued, product-chrome aesthetic — secondary
+    // and tertiary are lifted closer to primary so dense UI reads cleanly
+    // without needing to bump to primary for every chrome label.
+    @return (
+      primary: #ffffff,
+      secondary: rgba(255, 255, 255, 0.72),
+      tertiary: rgba(255, 255, 255, 0.5),
+      inverse: get-shade($palette, 900)            // Text on light accents
+    );
+  }
+
+  // Light mode background — stone uses white, colorful palettes use palette[50]
+  $bg: #ffffff;
+  @if $palette-name != 'stone' {
+    $bg: get-shade($palette, 50);
+  }
+
+  @return (
+    primary: get-shade($palette, 900),           // Main text (high contrast)
+    secondary: ensure-contrast(get-shade($palette, 600), $bg, 7),
+    tertiary: ensure-contrast(
+      color.mix(get-shade($palette, 600), get-shade($palette, 500), 20%), $bg, 7
+    ),
+    inverse: get-shade($palette, 100)            // Text on dark accents
+  );
+}
+
+// --------------------------------------------
+// Border Color Derivation
+// --------------------------------------------
+
+/// Derive border tokens from a neutral palette
+/// @param {Map} $palette - Neutral palette map
+/// @param {Boolean} $is-dark - Whether in dark mode
+/// @return {Map} Border token values
+@function derive-borders($palette, $is-dark: false, $palette-name: 'stone') {
+  @if $is-dark {
+    @if $palette-name == 'stone' or $palette-name == 'mono' {
+      @return (
+        default: rgba(255, 255, 255, 0.075),
+        strong: rgba(255, 255, 255, 0.14)
+      );
+    }
+
+    // Dark mode: subtle white-alpha hairlines. Tight opacities keep panel
+    // edges barely-there so borders define structure without adding visual
+    // weight — matches the dense dashboard aesthetic.
+    @return (
+      default: rgba(255, 255, 255, 0.055),
+      strong: rgba(255, 255, 255, 0.085)
+    );
+  } @else {
+    // Light mode: reduced opacity (ChatGPT --border-light ~5%)
+    @return (
+      default: rgba(0, 0, 0, 0.05),
+      strong: rgba(0, 0, 0, 0.10)
+    );
+  }
+}
+
+// --------------------------------------------
+// Shadow Derivation
+// --------------------------------------------
+
+/// Derive shadow tokens based on mode
+/// @param {Boolean} $is-dark - Whether in dark mode
+/// @return {Map} Shadow token values
+@function derive-shadows($is-dark: false) {
+  @if $is-dark {
+    // Dark mode: near-zero shadows — hairlines and alpha overlays carry
+    // elevation instead, matching dense product-chrome aesthetics.
+    @return (
+      sm: (0 1px 2px 0 rgba(0, 0, 0, 0.15)),
+      md: (0 2px 4px -1px rgba(0, 0, 0, 0.2), 0 1px 3px -2px rgba(0, 0, 0, 0.15)),
+      lg: (0 8px 12px -3px rgba(0, 0, 0, 0.25), 0 3px 5px -4px rgba(0, 0, 0, 0.18))
+    );
+  } @else {
+    // Light mode: flatter aesthetic — near-zero shadows so layout reads
+    // as structure rather than floating chrome.
+    @return (
+      sm: (0 1px 2px 0 rgba(0, 0, 0, 0.02)),
+      md: (0 2px 4px -1px rgba(0, 0, 0, 0.04), 0 1px 3px -2px rgba(0, 0, 0, 0.03)),
+      lg: (0 8px 12px -3px rgba(0, 0, 0, 0.06), 0 3px 5px -4px rgba(0, 0, 0, 0.04))
+    );
+  }
+}
+
+// --------------------------------------------
+// Scrollbar Derivation
+// --------------------------------------------
+
+/// Derive scrollbar tokens from a neutral palette
+/// @param {Map} $palette - Neutral palette map
+/// @param {Boolean} $is-dark - Whether in dark mode
+/// @return {Map} Scrollbar token values
+@function derive-scrollbar($palette, $is-dark: false) {
+  @if $is-dark {
+    @return (
+      track: get-shade($palette, 800),
+      thumb: get-shade($palette, 600),
+      thumb-hover: get-shade($palette, 500)
+    );
+  } @else {
+    @return (
+      track: get-shade($palette, 100),
+      thumb: get-shade($palette, 300),
+      thumb-hover: get-shade($palette, 400)
+    );
+  }
+}
+
+// --------------------------------------------
+// Semantic Color Backgrounds
+// --------------------------------------------
+
+/// Derive semantic background colors (danger, success, etc.)
+/// @param {Color} $color - The semantic color
+/// @param {Boolean} $is-dark - Whether in dark mode
+/// @return {Color} Background color with appropriate opacity
+@function derive-semantic-bg($color, $is-dark: false) {
+  @if $is-dark {
+    // Dark mode: slightly higher opacity for visibility
+    @return rgba($color, 0.15);
+  } @else {
+    // Light mode: subtle background
+    @return rgba($color, 0.1);
+  }
+}
+
+/// Derive hover state for semantic colors (like danger-hover)
+/// @param {Color} $color - The semantic color
+/// @return {Color} Hover state color
+@function derive-semantic-hover($color) {
+  @return color.adjust($color, $lightness: -0.05, $space: oklch);
+}
+
+// --------------------------------------------
+// Focus Ring Derivation
+// --------------------------------------------
+
+/// Derive focus ring color from brand/accent
+/// @param {Color} $brand - Brand color
+/// @param {Boolean} $is-dark - Whether in dark mode
+/// @return {Color} Focus ring color
+@function derive-focus-ring($brand, $is-dark: false) {
+  @if $is-dark {
+    // In dark mode with dark brand, use light focus ring
+    @if is-dark-color($brand) {
+      @return #f2f2f2;
+    }
+    @return $brand;
+  } @else {
+    // In light mode, use brand color
+    @return $brand;
+  }
+}
+
+// --------------------------------------------
+// Backdrop Derivation
+// --------------------------------------------
+
+/// Derive backdrop/overlay colors
+/// @param {Boolean} $is-dark - Whether in dark mode
+/// @return {Color} Backdrop color
+@function derive-backdrop($is-dark: false) {
+  @if $is-dark {
+    @return rgba(0, 0, 0, 0.8);
+  } @else {
+    @return rgba(0, 0, 0, 0.5);
+  }
+}
+
+// --------------------------------------------
+// WCAG 2.1 Contrast Utilities
+// --------------------------------------------
+
+/// Linearize an sRGB channel (0-255) per WCAG 2.1
+/// @param {Number} $channel-8bit - Channel value 0-255
+/// @return {Number} Linear value 0-1
+@function _srgb-linearize($channel-8bit) {
+  $srgb: math.div($channel-8bit, 255);
+  @if $srgb <= 0.04045 {
+    @return math.div($srgb, 12.92);
+  } @else {
+    @return math.pow(math.div($srgb + 0.055, 1.055), 2.4);
+  }
+}
+
+/// WCAG 2.1 relative luminance
+/// @param {Color} $color - Color to measure
+/// @return {Number} Relative luminance 0-1
+@function _wcag-luminance($color) {
+  $r: _srgb-linearize(color.channel($color, 'red', $space: rgb));
+  $g: _srgb-linearize(color.channel($color, 'green', $space: rgb));
+  $b: _srgb-linearize(color.channel($color, 'blue', $space: rgb));
+  @return 0.2126 * $r + 0.7152 * $g + 0.0722 * $b;
+}
+
+/// WCAG 2.1 contrast ratio between two colors
+/// @param {Color} $fg - Foreground color
+/// @param {Color} $bg - Background color
+/// @return {Number} Contrast ratio >= 1
+@function wcag-contrast($fg, $bg) {
+  $l1: _wcag-luminance($fg);
+  $l2: _wcag-luminance($bg);
+  $lighter: math.max($l1, $l2);
+  $darker: math.min($l1, $l2);
+  @return math.div($lighter + 0.05, $darker + 0.05);
+}
+
+// --------------------------------------------
+// Semantic Text Color Derivation
+// --------------------------------------------
+
+/// Derive a WCAG AA contrast-safe text color from a semantic color.
+/// Darkens (light mode) or lightens (dark mode) until 6:1 is met
+/// against ~white (light) or ~black (dark) page background.
+/// Target is 6:1 (above AA 4.5:1) to provide headroom for composited
+/// semantic backgrounds (rgba overlays) on tinted palette surfaces.
+/// @param {Color} $color - Base semantic color (e.g. danger, success)
+/// @param {Boolean} $is-dark - Whether in dark mode
+/// @return {Color} Adjusted color meeting 5.0:1 contrast on page bg
+@function derive-semantic-text($color, $is-dark: false) {
+  $target: 6;
+  $bg: #ffffff;
+  @if $is-dark {
+    $bg: #0a0a0a;
+  }
+  $adjusted: $color;
+
+  @for $i from 1 through 40 {
+    @if wcag-contrast($adjusted, $bg) < $target {
+      @if $is-dark {
+        $adjusted: color.adjust($adjusted, $lightness: 2%, $space: oklch);
+      } @else {
+        $adjusted: color.adjust($adjusted, $lightness: -2%, $space: oklch);
+      }
+    }
+  }
+
+  @return $adjusted;
+}