@fragments-sdk/ui 0.14.0 → 0.15.1

package/src/tokens/_density.scss

@@ -34,10 +34,16 @@ $density-compact: (
   // 4 units
   input-height-lg: 36px,
   // 6 units
-  // Touch targets (minimum for accessibility)
+  // Touch targets (WCAG 2.5.8: minimum 24px)
   touch-sm: 24px,
-  touch-md: 30px,
-  touch-lg: 36px,
+  // 24px = WCAG AA floor
+  touch-md: 28px,
+  // -12.5% from default
+  touch-lg: 38px,
+  // -13.6% from default
+  // Sidebar navigation
+  sidebar-item-height: 30px,
+  // ~5 units
 );
 
 $density-default: (
@@ -57,10 +63,15 @@ $density-default: (
   // 4 units
   input-height-lg: 44px,
   // ~6 units
-  // Touch targets
+  // Touch targets (baseline)
   touch-sm: 24px,
+  // WCAG AA floor
   touch-md: 32px,
   touch-lg: 44px,
+  // WCAG AAA recommended
+  // Sidebar navigation
+  sidebar-item-height: 35px,
+  // 5 units
 );
 
 $density-relaxed: (
@@ -80,10 +91,16 @@ $density-relaxed: (
   // 4 units
   input-height-lg: 48px,
   // 6 units
-  // Touch targets
-  touch-sm: 32px,
-  touch-md: 40px,
+  // Touch targets (proportional from default, not blown out)
+  touch-sm: 28px,
+  // +17% from default (was 32px / +33%)
+  touch-md: 36px,
+  // +12.5% from default (was 40px / +25%)
   touch-lg: 48px,
+  // +9% from default (unchanged)
+  // Sidebar navigation
+  sidebar-item-height: 38px,
+  // ~4.75 units
 );
 
 // --------------------------------------------

package/src/tokens/_derive.scss

@@ -112,16 +112,44 @@
   }
 }
 
+// --------------------------------------------
+// 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%);
+      } @else {
+        $adjusted: color.adjust($adjusted, $lightness: -2%);
+      }
+    }
+  }
+  @return $adjusted;
+}
+
 // --------------------------------------------
 // Surface/Background Derivation
 // --------------------------------------------
 
 /// Derive surface/background tokens from a neutral palette
-/// Maps shade levels to semantic surface tokens for visual depth layering
+/// 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) {
+@function derive-surfaces($palette, $is-dark: false, $palette-name: 'stone') {
   @if $is-dark {
     // Dark mode: darker = more recessed, lighter = elevated
     @return (
@@ -133,47 +161,69 @@
       hover: rgba(255, 255, 255, 0.05),            // Interactive hover (subtle)
       active: rgba(255, 255, 255, 0.08)            // Interactive active
     );
-  } @else {
-    // Light mode: lighter = more recessed, darker shades for depth
+  }
+
+  // Light mode: colorful palettes get tinted backgrounds
+  $is-colorful: $palette-name != 'stone';
+  @if $is-colorful {
     @return (
-      primary: #ffffff,                            // Page background (white)
-      secondary: get-shade($palette, 100),         // Sidebar, secondary panels
-      tertiary: get-shade($palette, 100),          // Nested sections
+      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 backgrounds
+      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
+  );
 }
 
 // --------------------------------------------
 // Text Color Derivation
 // --------------------------------------------
 
-/// Derive text tokens from a neutral palette
-/// Maps shade levels to semantic text tokens with contrast verification
+/// 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) {
+@function derive-text($palette, $is-dark: false, $palette-name: 'stone') {
   @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
+      // 90/10 mix of palette[400]/palette[500] for WCAG AAA 7:1
+      // against palette[950] backgrounds (pure palette[500] gives ~4.1:1)
+      tertiary: color.mix(get-shade($palette, 500), get-shade($palette, 400), 10%),
       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
-    );
   }
+
+  // Light mode background — stone uses white, colorful palettes use palette[50]
+  $bg: if($palette-name != 'stone', get-shade($palette, 50), #ffffff);
+
+  @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
+  );
 }
 
 // --------------------------------------------

package/src/tokens/_mixins.scss

@@ -102,6 +102,43 @@
   border-radius: var(--fui-radius-lg, #{$fui-radius-lg});
 }
 
+// Dropdown / popup container base styles.
+// Compose with @include surface-elevated for the full treatment.
+// Consumer sets min-width and optionally max-height/overflow.
+@mixin popup-container {
+  display: flex;
+  flex-direction: column;
+  gap: 1px;
+  padding: var(--fui-space-1, #{$fui-space-1});
+  box-shadow: var(--fui-shadow-md, #{$fui-shadow-md});
+}
+
+// Dropdown/popup item base.
+// Includes button-reset and text-base. Consumer adds state styles.
+@mixin popup-item {
+  @include button-reset;
+  @include text-base;
+
+  display: flex;
+  align-items: center;
+  gap: var(--fui-space-1, #{$fui-space-1});
+  width: 100%;
+  padding: var(--fui-space-1, #{$fui-space-1}) var(--fui-space-2, #{$fui-space-2});
+  border-radius: var(--fui-radius-sm, #{$fui-radius-sm});
+  cursor: pointer;
+  outline: none;
+}
+
+// Group label within a dropdown/popup.
+@mixin popup-group-label {
+  padding: var(--fui-space-1, #{$fui-space-1}) var(--fui-space-2, #{$fui-space-2});
+  font-size: var(--fui-font-size-xs, #{$fui-font-size-xs});
+  font-weight: var(--fui-font-weight-medium, #{$fui-font-weight-medium});
+  color: var(--fui-text-tertiary, #{$fui-text-tertiary});
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+}
+
 // Responsive breakpoint mixins (mobile-first, min-width)
 @mixin breakpoint-sm { @media (min-width: $fui-breakpoint-sm) { @content; } }
 @mixin breakpoint-md { @media (min-width: $fui-breakpoint-md) { @content; } }
@@ -115,6 +152,43 @@
 @mixin below-lg { @media (max-width: #{$fui-breakpoint-lg - 1px}) { @content; } }
 @mixin below-xl { @media (max-width: #{$fui-breakpoint-xl - 1px}) { @content; } }
 
+// ============================================
+// Container Queries
+// ============================================
+// Component-level responsive design via container queries.
+// Unlike media queries (viewport-based), these respond to the component's
+// own container width — making components intrinsically responsive.
+// Browser support: ~96% (Chrome 105+, Firefox 110+, Safari 16+)
+
+/// Make an element a container query context.
+/// @param {String} $name - Container name for targeting in @container rules
+@mixin container($name) {
+  container-type: inline-size;
+  container-name: #{$name};
+}
+
+/// Container query: apply styles when named container is at least $width wide.
+/// @param {Length} $width - Minimum width threshold
+/// @param {String} $name - Optional container name (omit for nearest ancestor container)
+@mixin container-min($width, $name: null) {
+  @if $name {
+    @container #{$name} (min-width: #{$width}) { @content; }
+  } @else {
+    @container (min-width: #{$width}) { @content; }
+  }
+}
+
+/// Container query: apply styles when named container is below $width wide.
+/// @param {Length} $width - Maximum width threshold
+/// @param {String} $name - Optional container name (omit for nearest ancestor container)
+@mixin container-max($width, $name: null) {
+  @if $name {
+    @container #{$name} (max-width: #{$width}) { @content; }
+  } @else {
+    @container (max-width: #{$width}) { @content; }
+  }
+}
+
 // Visually hidden (for screen readers)
 @mixin visually-hidden {
   position: absolute;
@@ -218,3 +292,41 @@
     }
   }
 }
+
+// ============================================
+// Form Field Wrapper
+// Generates .wrapper, .label, .helper, .helperError, .errorMessage
+// for consistent form field layout across all form components.
+// ============================================
+
+@mixin form-field-wrapper {
+  .wrapper {
+    display: flex;
+    flex-direction: column;
+  }
+
+  .label {
+    @include label-text;
+    margin-bottom: var(--fui-space-1, #{$fui-space-1});
+  }
+
+  .required {
+    color: var(--fui-color-danger, #{$fui-color-danger});
+    margin-left: 2px;
+  }
+
+  .helper {
+    @include helper-text;
+    margin-top: var(--fui-space-1, #{$fui-space-1});
+  }
+
+  .helperError {
+    color: var(--fui-color-danger, #{$fui-color-danger});
+  }
+
+  .errorMessage {
+    font-size: var(--fui-font-size-xs, #{$fui-font-size-xs});
+    color: var(--fui-color-danger, #{$fui-color-danger});
+    margin-top: var(--fui-space-1, #{$fui-space-1});
+  }
+}

package/src/tokens/_palettes.scss

@@ -42,9 +42,9 @@ $palette-ice: (
   500: #0ea5e9,
   600: #0284c7,
   700: #0369a1,
-  800: #075985,
-  900: #0c4a6e,
-  950: #082f49
+  800: #0f2d3d,  // Darkened and desaturated for dark mode
+  900: #0a1f2c,  // Darkened and desaturated for dark mode
+  950: #06141c   // Very dark blue-gray for dark mode bg
 );
 
 // --------------------------------------------
@@ -60,9 +60,9 @@ $palette-sand: (
   500: #a67c52,
   600: #8b5e34,
   700: #6f4518,
-  800: #553311,
-  900: #3d240c,
-  950: #261607
+  800: #231a12,  // Darkened and desaturated for dark mode
+  900: #181210,  // Darkened and desaturated for dark mode
+  950: #0f0c09   // Very dark warm gray for dark mode bg
 );
 
 // --------------------------------------------
@@ -78,9 +78,9 @@ $palette-earth: (
   500: #6b8c4e,
   600: #517035,
   700: #3d5527,
-  800: #2b3d1c,
-  900: #1c2912,
-  950: #0f170a
+  800: #1a2316,  // Darkened and desaturated for dark mode
+  900: #121810,  // Darkened and desaturated for dark mode
+  950: #0a0f08   // Very dark green-gray for dark mode bg
 );
 
 // --------------------------------------------
@@ -96,9 +96,9 @@ $palette-fire: (
   500: #f97316,
   600: #ea580c,
   700: #c2410c,
-  800: #9a3412,
-  900: #7c2d12,
-  950: #431407
+  800: #2d1810,  // Darkened and desaturated for dark mode
+  900: #1c100a,  // Darkened and desaturated for dark mode
+  950: #120a06   // Very dark warm gray for dark mode bg
 );
 
 // --------------------------------------------

package/src/tokens/_property-registrations.scss

@@ -0,0 +1,210 @@
+// ============================================
+// @fragments-sdk/ui CSS @property Registrations
+// ============================================
+// Registers typed CSS custom properties via @property.
+// Benefits:
+//   1. Animatable color/length tokens (smooth theme transitions)
+//   2. Typed defaults eliminate need for SCSS fallback long-term
+//   3. Inheritance control prevents token leaking
+// Browser support: ~94% (Chrome 85+, Firefox 128+, Safari 15.4+)
+// https://caniuse.com/mdn-css_at-rules_property
+// Usage: @include fui-property-registrations; (before fui-css-variables)
+// ============================================
+
+@use 'variables' as *;
+
+// ============================================
+// Color Tokens
+// ============================================
+
+@mixin register-color($name, $initial) {
+  @property --fui-#{$name} {
+    syntax: '<color>';
+    initial-value: #{$initial};
+    inherits: true;
+  }
+}
+
+// ============================================
+// Length Tokens
+// ============================================
+
+@mixin register-length($name, $initial) {
+  @property --fui-#{$name} {
+    syntax: '<length>';
+    initial-value: #{$initial};
+    inherits: true;
+  }
+}
+
+// ============================================
+// Number Tokens (unitless: weights, line-heights, z-index)
+// ============================================
+
+@mixin register-number($name, $initial) {
+  @property --fui-#{$name} {
+    syntax: '<number>';
+    initial-value: #{$initial};
+    inherits: true;
+  }
+}
+
+// ============================================
+// Main Registration Mixin
+// ============================================
+
+@mixin fui-property-registrations {
+  // ------------------------------------------
+  // Seed Colors — configurable brand/semantic seeds
+  // Runtime derivation via relative color syntax operates in OKLCH space.
+  // ------------------------------------------
+  @include register-color('seed-brand', $fui-color-accent);
+  @include register-color('seed-danger', $fui-color-danger);
+  @include register-color('seed-success', $fui-color-success);
+  @include register-color('seed-warning', $fui-color-warning);
+  @include register-color('seed-info', $fui-color-info);
+
+  // ------------------------------------------
+  // Colors — Accent (animatable for theme transitions)
+  // ------------------------------------------
+  @include register-color('color-accent', $fui-color-accent);
+  @include register-color('color-accent-hover', $fui-color-accent-hover);
+  @include register-color('color-accent-active', $fui-color-accent-active);
+
+  // ------------------------------------------
+  // Colors — Semantic
+  // ------------------------------------------
+  @include register-color('color-danger', $fui-color-danger);
+  @include register-color('color-danger-hover', $fui-color-danger-hover);
+  @include register-color('color-success', $fui-color-success);
+  @include register-color('color-warning', $fui-color-warning);
+  @include register-color('color-info', $fui-color-info);
+
+  // ------------------------------------------
+  // Colors — Semantic Backgrounds
+  // ------------------------------------------
+  @include register-color('color-danger-bg', $fui-color-danger-bg);
+  @include register-color('color-success-bg', $fui-color-success-bg);
+  @include register-color('color-warning-bg', $fui-color-warning-bg);
+  @include register-color('color-info-bg', $fui-color-info-bg);
+
+  // ------------------------------------------
+  // Colors — Semantic Text
+  // ------------------------------------------
+  @include register-color('color-danger-text', $fui-color-danger-text);
+  @include register-color('color-success-text', $fui-color-success-text);
+  @include register-color('color-warning-text', $fui-color-warning-text);
+  @include register-color('color-info-text', $fui-color-info-text);
+
+  // ------------------------------------------
+  // Colors — Surfaces
+  // ------------------------------------------
+  @include register-color('bg-primary', $fui-bg-primary);
+  @include register-color('bg-secondary', $fui-bg-secondary);
+  @include register-color('bg-tertiary', $fui-bg-tertiary);
+  @include register-color('bg-elevated', $fui-bg-elevated);
+  @include register-color('bg-subtle', $fui-bg-subtle);
+  @include register-color('bg-hover', $fui-bg-hover);
+  @include register-color('bg-active', $fui-bg-active);
+
+  // ------------------------------------------
+  // Colors — Text
+  // ------------------------------------------
+  @include register-color('text-primary', $fui-text-primary);
+  @include register-color('text-secondary', $fui-text-secondary);
+  @include register-color('text-tertiary', $fui-text-tertiary);
+  @include register-color('text-inverse', $fui-text-inverse);
+
+  // ------------------------------------------
+  // Colors — Borders
+  // ------------------------------------------
+  @include register-color('border', $fui-border);
+  @include register-color('border-default', $fui-border-default);
+  @include register-color('border-strong', $fui-border-strong);
+
+  // ------------------------------------------
+  // Colors — Focus
+  // ------------------------------------------
+  @include register-color('focus-ring-color', $fui-focus-ring-color);
+
+  // ------------------------------------------
+  // Colors — Scrollbar
+  // ------------------------------------------
+  @include register-color('scrollbar-track', $fui-scrollbar-track);
+  @include register-color('scrollbar-thumb', $fui-scrollbar-thumb);
+  @include register-color('scrollbar-thumb-hover', $fui-scrollbar-thumb-hover);
+
+  // ------------------------------------------
+  // Spacing — Lengths
+  // ------------------------------------------
+  @include register-length('space-px', $fui-space-px);
+  @include register-length('space-0-5', $fui-space-0-5);
+  @include register-length('space-0-75', $fui-space-0-75);
+  @include register-length('space-1', $fui-space-1);
+  @include register-length('space-2', $fui-space-2);
+  @include register-length('space-3', $fui-space-3);
+  @include register-length('space-4', $fui-space-4);
+  @include register-length('space-5', $fui-space-5);
+  @include register-length('space-6', $fui-space-6);
+  @include register-length('space-8', $fui-space-8);
+  @include register-length('space-10', $fui-space-10);
+  @include register-length('space-12', $fui-space-12);
+
+  // ------------------------------------------
+  // Border Radius — Lengths
+  // ------------------------------------------
+  @include register-length('radius-sm', $fui-radius-sm);
+  @include register-length('radius-md', $fui-radius-md);
+  @include register-length('radius-lg', $fui-radius-lg);
+  @include register-length('radius-xl', $fui-radius-xl);
+  @include register-length('radius-full', $fui-radius-full);
+
+  // ------------------------------------------
+  // Component Heights — Lengths
+  // ------------------------------------------
+  @include register-length('button-height-sm', $fui-button-height-sm);
+  @include register-length('button-height-md', $fui-button-height-md);
+  @include register-length('button-height-lg', $fui-button-height-lg);
+  @include register-length('input-height', $fui-input-height);
+  @include register-length('input-height-sm', $fui-input-height-sm);
+  @include register-length('input-height-lg', $fui-input-height-lg);
+  @include register-length('target-size-min', $fui-target-size-min);
+
+  // ------------------------------------------
+  // Focus Ring — Lengths
+  // ------------------------------------------
+  @include register-length('focus-ring-offset', $fui-focus-ring-offset);
+  @include register-length('focus-ring-width', $fui-focus-ring-width);
+  @include register-length('scrollbar-width', $fui-scrollbar-width);
+
+  // ------------------------------------------
+  // Typography — Numbers (unitless, animatable)
+  // ------------------------------------------
+  @include register-number('font-weight-normal', $fui-font-weight-normal);
+  @include register-number('font-weight-medium', $fui-font-weight-medium);
+  @include register-number('font-weight-semibold', $fui-font-weight-semibold);
+  @include register-number('font-weight-bold', $fui-font-weight-bold);
+  @include register-number('line-height-tight', $fui-line-height-tight);
+  @include register-number('line-height-normal', $fui-line-height-normal);
+  @include register-number('line-height-relaxed', $fui-line-height-relaxed);
+
+  // ------------------------------------------
+  // Typography — Font Sizes (lengths)
+  // ------------------------------------------
+  @include register-length('font-size-2xs', $fui-font-size-2xs);
+  @include register-length('font-size-xs', $fui-font-size-xs);
+  @include register-length('font-size-sm', $fui-font-size-sm);
+  @include register-length('font-size-base', $fui-font-size-base);
+  @include register-length('font-size-lg', $fui-font-size-lg);
+  @include register-length('font-size-xl', $fui-font-size-xl);
+  @include register-length('font-size-2xl', $fui-font-size-2xl);
+
+  // ------------------------------------------
+  // Note: The following tokens are NOT registered because @property
+  // syntax doesn't support their complex types:
+  //   --fui-font-sans, --fui-font-mono (font family lists)
+  //   --fui-shadow-sm/md/lg (shadow lists)
+  //   --fui-transition-fast/normal (shorthand timing)
+  //   --fui-backdrop, --fui-dark-backdrop (rgba — registered above as <color>)
+  // ------------------------------------------
+}