@fragments-sdk/ui 0.4.0 → 0.5.0

package/src/tokens/_density.scss

@@ -0,0 +1,171 @@
+// ============================================
+// @fragments/ui Density Scales
+// ============================================
+//
+// Defines 3 density presets that control spacing and sizing.
+// Each preset uses a different base unit to scale all spacing.
+//
+// ============================================
+
+@use 'sass:math';
+@use 'sass:map';
+
+// --------------------------------------------
+// Density Definitions
+// --------------------------------------------
+// Each density includes:
+// - base-unit: The fundamental spacing unit
+// - multipliers: Scale factors for spacing tokens
+
+$density-compact: (
+  base-unit: 6px,
+  base-font-size: 14px,
+  // Button heights (more compact)
+  button-height-sm: 24px,   // ~4 units
+  button-height-md: 30px,   // 5 units
+  button-height-lg: 36px,   // 6 units
+  // Input height
+  input-height: 32px,       // ~5.3 units
+  input-height-sm: 24px,    // 4 units
+  input-height-lg: 36px,    // 6 units
+  // Touch targets (minimum for accessibility)
+  touch-sm: 24px,
+  touch-md: 30px,
+  touch-lg: 36px
+);
+
+$density-default: (
+  base-unit: 7px,
+  base-font-size: 14px,
+  // Button heights (current values)
+  button-height-sm: 28px,   // 4 units
+  button-height-md: 36px,   // ~5 units
+  button-height-lg: 44px,   // ~6 units
+  // Input height
+  input-height: 40px,       // ~6 units
+  input-height-sm: 28px,    // 4 units
+  input-height-lg: 44px,    // ~6 units
+  // Touch targets
+  touch-sm: 24px,
+  touch-md: 32px,
+  touch-lg: 44px
+);
+
+$density-relaxed: (
+  base-unit: 8px,
+  base-font-size: 14px,
+  // Button heights (more spacious)
+  button-height-sm: 32px,   // 4 units
+  button-height-md: 40px,   // 5 units
+  button-height-lg: 48px,   // 6 units
+  // Input height
+  input-height: 44px,       // ~5.5 units
+  input-height-sm: 32px,    // 4 units
+  input-height-lg: 48px,    // 6 units
+  // Touch targets
+  touch-sm: 32px,
+  touch-md: 40px,
+  touch-lg: 48px
+);
+
+// --------------------------------------------
+// Density Map for Dynamic Access
+// --------------------------------------------
+$densities: (
+  "compact": $density-compact,
+  "default": $density-default,
+  "relaxed": $density-relaxed
+);
+
+// --------------------------------------------
+// Helper Functions
+// --------------------------------------------
+
+/// Get a density configuration by name
+/// @param {String} $name - Density name (compact, default, relaxed)
+/// @return {Map} The density configuration map
+@function get-density($name) {
+  @if not map.has-key($densities, $name) {
+    @warn "Unknown density '#{$name}'. Using 'default' as fallback.";
+    @return $density-default;
+  }
+  @return map.get($densities, $name);
+}
+
+/// Get a specific value from a density configuration
+/// @param {Map} $density - A density configuration map
+/// @param {String} $key - The key to retrieve
+/// @return {*} The value
+@function density-value($density, $key) {
+  @if not map.has-key($density, $key) {
+    @warn "Unknown density key '#{$key}'.";
+    @return null;
+  }
+  @return map.get($density, $key);
+}
+
+/// Derive spacing scale from base unit
+/// Returns a map with spacing tokens
+/// @param {Map} $density - A density configuration map
+/// @return {Map} Spacing tokens
+@function derive-spacing($density) {
+  $base: map.get($density, base-unit);
+  $font-size: map.get($density, base-font-size);
+
+  // Convert to rem based on font size
+  // 1 unit = base-unit / font-size * 1rem
+  $unit-rem: math.div($base, $font-size) * 1rem;
+
+  @return (
+    // Micro spacing (pixel-precise for tiny alignments)
+    px: 1px,
+    0-5: $unit-rem * 0.3,     // ~2px for 7px base
+    0-75: $unit-rem * 0.43,   // ~3px for 7px base
+
+    // Standard spacing scale
+    1: $unit-rem,             // 1 unit
+    2: $unit-rem * 2,         // 2 units
+    3: $unit-rem * 3,         // 3 units
+    4: $unit-rem * 4,         // 4 units
+    5: $unit-rem * 5,         // 5 units
+    6: $unit-rem * 6,         // 6 units
+    8: $unit-rem * 8,         // 8 units
+    10: $unit-rem * 10,       // 10 units
+    12: $unit-rem * 12        // 12 units
+  );
+}
+
+/// Derive container padding from density
+/// @param {Map} $density - A density configuration map
+/// @return {Map} Padding tokens
+@function derive-padding($density) {
+  $base: map.get($density, base-unit);
+  $font-size: map.get($density, base-font-size);
+  $unit-rem: math.div($base, $font-size) * 1rem;
+
+  @return (
+    // Container padding: Cards, Dialogs, Popovers
+    container-sm: $unit-rem * 3,   // 3 units
+    container-md: $unit-rem * 4,   // 4 units
+    container-lg: $unit-rem * 6,   // 6 units
+
+    // Inline padding: Alerts, Toasts
+    inline-sm: $unit-rem * 2,      // 2 units
+    inline-md: $unit-rem * 3,      // 3 units
+    inline-lg: $unit-rem * 4,      // 4 units
+
+    // Item padding: Accordion, Tabs, Menu items
+    item-sm: $unit-rem * 2,        // 2 units
+    item-md: $unit-rem * 3,        // 3 units
+    item-lg: $unit-rem * 4         // 4 units
+  );
+}
+
+/// Convert pixel value to rem based on density
+/// @param {Map} $density - A density configuration map
+/// @param {Number} $px - Pixel value to convert
+/// @return {Number} Value in rem
+@function px-to-rem($density, $px) {
+  $font-size: map.get($density, base-font-size);
+  @return math.div($px, $font-size) * 1rem;
+}

package/src/tokens/_derive.scss

@@ -0,0 +1,287 @@
+// ============================================
+// @fragments/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) {
+  $r: math.div(color.channel($color, 'red', $space: rgb), 255);
+  $g: math.div(color.channel($color, 'green', $space: rgb), 255);
+  $b: math.div(color.channel($color, 'blue', $space: rgb), 255);
+
+  // Relative luminance formula (simplified)
+  $luminance: 0.2126 * $r + 0.7152 * $g + 0.0722 * $b;
+
+  @return $luminance < 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
+/// @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) {
+  @if $is-dark {
+    // In dark mode, lighten for hover
+    @return color.scale($base, $lightness: 5%);
+  } @else {
+    // In light mode, darken for hover
+    @return color.scale($base, $lightness: -8%);
+  }
+}
+
+/// Derive active state for accent color
+/// @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) {
+  @if $is-dark {
+    // In dark mode, lighten more for active
+    @return color.scale($base, $lightness: 10%);
+  } @else {
+    // In light mode, darken more for active
+    @return color.scale($base, $lightness: -15%);
+  }
+}
+
+/// Derive a light variant of accent for dark mode
+/// Auto-lightens dark brand colors so they're visible on dark backgrounds
+/// @param {Color} $brand - Brand color
+/// @return {Color} Lightened accent for dark mode
+@function derive-dark-accent($brand) {
+  @if is-dark-color($brand) {
+    // If brand is dark, invert to light for dark mode
+    // Use a light gray as the dark mode accent
+    @return #f2f2f2;
+  } @else {
+    // If brand is already light, use it as-is or slightly adjust
+    @return color.scale($brand, $lightness: 10%);
+  }
+}
+
+// --------------------------------------------
+// Surface/Background Derivation
+// --------------------------------------------
+
+/// Derive surface/background tokens from a neutral palette
+/// Maps shade levels to semantic surface tokens for visual depth layering
+/// @param {Map} $palette - Neutral palette map
+/// @param {Boolean} $is-dark - Whether in dark mode
+/// @return {Map} Surface token values
+@function derive-surfaces($palette, $is-dark: false) {
+  @if $is-dark {
+    // Dark mode: darker = more recessed, lighter = elevated
+    @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: get-shade($palette, 900),          // Cards (slightly lighter than page)
+      subtle: interpolate-shade($palette, 925),    // Between primary and secondary
+      hover: rgba(255, 255, 255, 0.06),            // Interactive hover
+      active: rgba(255, 255, 255, 0.08)            // Interactive active
+    );
+  } @else {
+    // Light mode: lighter = more recessed, darker shades for depth
+    @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
+    );
+  }
+}
+
+// --------------------------------------------
+// Text Color Derivation
+// --------------------------------------------
+
+/// Derive text tokens from a neutral palette
+/// Maps shade levels to semantic text tokens with contrast verification
+/// @param {Map} $palette - Neutral palette map
+/// @param {Boolean} $is-dark - Whether in dark mode
+/// @return {Map} Text token values
+@function derive-text($palette, $is-dark: false) {
+  @if $is-dark {
+    // Dark mode: light text on dark backgrounds
+    @return (
+      primary: get-shade($palette, 100),           // Main text (light on dark)
+      secondary: get-shade($palette, 400),         // Secondary text
+      tertiary: get-shade($palette, 500),          // Muted text
+      inverse: get-shade($palette, 900)            // Text on light accents
+    );
+  } @else {
+    // Light mode: dark text on light backgrounds
+    @return (
+      primary: get-shade($palette, 900),           // Main text (high contrast)
+      secondary: get-shade($palette, 600),         // Secondary text
+      tertiary: get-shade($palette, 500),          // Muted/disabled text
+      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) {
+  @if $is-dark {
+    // Dark mode: subtle light borders
+    @return (
+      default: get-shade($palette, 800),           // Subtle dark borders
+      strong: get-shade($palette, 700)             // Prominent dark borders
+    );
+  } @else {
+    // Light mode: subtle dark borders
+    @return (
+      default: get-shade($palette, 200),           // Subtle borders
+      strong: get-shade($palette, 300)             // Prominent borders
+    );
+  }
+}
+
+// --------------------------------------------
+// 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: deeper shadows for depth
+    @return (
+      sm: (0 1px 2px 0 rgba(0, 0, 0, 0.3)),
+      md: (0 4px 6px -1px rgba(0, 0, 0, 0.4), 0 2px 4px -2px rgba(0, 0, 0, 0.3)),
+      lg: (0 10px 15px -3px rgba(0, 0, 0, 0.5), 0 4px 6px -4px rgba(0, 0, 0, 0.4))
+    );
+  } @else {
+    // Light mode: subtle shadows
+    @return (
+      sm: (0 1px 2px 0 rgba(0, 0, 0, 0.05)),
+      md: (0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -2px rgba(0, 0, 0, 0.1)),
+      lg: (0 10px 15px -3px rgba(0, 0, 0, 0.1), 0 4px 6px -4px rgba(0, 0, 0, 0.1))
+    );
+  }
+}
+
+// --------------------------------------------
+// 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.scale($color, $lightness: -10%);
+}
+
+// --------------------------------------------
+// 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);
+  }
+}

package/src/tokens/_index.scss

@@ -1,3 +1,41 @@
-// Forward both variables and mixins
+// ============================================
+// @fragments/ui Design Tokens Index
+// ============================================
+//
+// This module exports the complete token system.
+// Import with: @use '@fragments-sdk/ui/tokens';
+//
+// SEED-BASED CONFIGURATION:
+// Set seed variables before importing to customize your theme.
+// See _seeds.scss for available options.
+//
+// Example:
+//   $fui-brand: #0066ff;
+//   $fui-neutral: "steel";
+//   @use '@fragments-sdk/ui/tokens';
+//
+// ============================================
+
+// Forward seed configuration (for users to override)
+@forward 'seeds';
+
+// Forward palette definitions (for advanced customization)
+@forward 'palettes';
+
+// Forward density scales
+@forward 'density';
+
+// Forward radius styles
+@forward 'radius';
+
+// Forward derivation functions (for advanced users)
+@forward 'derive';
+
+// Forward computed values (internal use)
+@forward 'computed';
+
+// Forward main variables (includes all token definitions)
 @forward 'variables';
+
+// Forward mixins
 @forward 'mixins';

package/src/tokens/_mixins.scss

@@ -150,3 +150,44 @@
     0 0 0 var(--fui-focus-ring-offset, #{$fui-focus-ring-offset}) var(--fui-bg-primary, #{$fui-bg-primary}),
     0 0 0 calc(var(--fui-focus-ring-offset, #{$fui-focus-ring-offset}) + var(--fui-focus-ring-width, #{$fui-focus-ring-width})) var(--fui-color-danger, #{$fui-color-danger});
 }
+
+// ============================================
+// Size Variant Mixins
+// ============================================
+
+/// Control size mixin for standardized sizing across buttons, inputs, selects
+/// @param {String} $size - Size variant: 'sm', 'md', or 'lg'
+/// @param {String} $component - Component type: 'button', 'input', or 'select'
+@mixin control-size($size, $component: 'button') {
+  @if $size == 'sm' {
+    @if $component == 'input' {
+      height: var(--fui-input-height-sm, #{$fui-input-height-sm});
+      padding: 0 var(--fui-space-2, #{$fui-space-2});
+      font-size: var(--fui-font-size-xs, #{$fui-font-size-xs});
+    } @else {
+      height: var(--fui-button-height-sm, #{$fui-button-height-sm});
+      padding: 0 var(--fui-space-2, #{$fui-space-2});
+      font-size: var(--fui-font-size-xs, #{$fui-font-size-xs});
+    }
+  } @else if $size == 'md' {
+    @if $component == 'input' {
+      height: var(--fui-input-height, #{$fui-input-height});
+      padding: 0 var(--fui-space-3, #{$fui-space-3});
+      font-size: var(--fui-font-size-sm, #{$fui-font-size-sm});
+    } @else {
+      height: var(--fui-button-height-md, #{$fui-button-height-md});
+      padding: 0 var(--fui-space-4, #{$fui-space-4});
+      font-size: var(--fui-font-size-sm, #{$fui-font-size-sm});
+    }
+  } @else if $size == 'lg' {
+    @if $component == 'input' {
+      height: var(--fui-input-height-lg, #{$fui-input-height-lg});
+      padding: 0 var(--fui-space-4, #{$fui-space-4});
+      font-size: var(--fui-font-size-base, #{$fui-font-size-base});
+    } @else {
+      height: var(--fui-button-height-lg, #{$fui-button-height-lg});
+      padding: 0 var(--fui-space-5, #{$fui-space-5});
+      font-size: var(--fui-font-size-base, #{$fui-font-size-base});
+    }
+  }
+}