@fragments-sdk/ui 0.13.0 → 0.15.1

package/src/tokens/_variables.scss

@@ -93,27 +93,6 @@ $fui-space-8: computed.$computed-space-8 !default;
 $fui-space-10: computed.$computed-space-10 !default;
 $fui-space-12: computed.$computed-space-12 !default;
 
-// --------------------------------------------
-// Density Padding (derived from density seed)
-// --------------------------------------------
-// Container padding: Cards, Dialogs, Popovers
-$fui-padding-container-sm: computed.$computed-padding-container-sm !default;
-$fui-padding-container-md: computed.$computed-padding-container-md !default;
-$fui-padding-container-lg: computed.$computed-padding-container-lg !default;
-$fui-padding-container-xl: computed.$computed-padding-container-xl !default;
-
-// Inline padding: Alerts, Toasts
-$fui-padding-inline-xs: computed.$computed-padding-inline-xs !default;
-$fui-padding-inline-sm: computed.$computed-padding-inline-sm !default;
-$fui-padding-inline-md: computed.$computed-padding-inline-md !default;
-$fui-padding-inline-lg: computed.$computed-padding-inline-lg !default;
-
-// Item padding: Accordion, Tabs, Menu items
-$fui-padding-item-xs: computed.$computed-padding-item-xs !default;
-$fui-padding-item-sm: computed.$computed-padding-item-sm !default;
-$fui-padding-item-md: computed.$computed-padding-item-md !default;
-$fui-padding-item-lg: computed.$computed-padding-item-lg !default;
-
 // --------------------------------------------
 // Border Radius (derived from radius-style seed)
 // --------------------------------------------
@@ -277,17 +256,24 @@ $fui-touch-sm: computed.$computed-touch-sm !default;
 $fui-touch-md: computed.$computed-touch-md !default;
 $fui-touch-lg: computed.$computed-touch-lg !default;
 
-// Minimum interactive target sizes (WCAG 2.2 SC 2.5.8)
+// Minimum interactive target sizes.
+// Keep this token globally available to preserve an accessibility floor for touch/pointer targets.
+// WCAG 2.2 SC 2.5.8 (Target Size (Minimum)):
+// https://www.w3.org/TR/WCAG22/#target-size-minimum
+// Understanding WCAG 2.2 SC 2.5.8:
+// https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum.html
 $fui-target-size-min: 1.714rem !default; // 24px
 $fui-target-size-comfortable: $fui-touch-md !default;
 
-// Toggle/Switch
-$fui-toggle-width-sm: 2.286rem !default; // 32px
-$fui-toggle-width-md: 2.857rem !default; // 40px
+// Toggle/Switch (iOS-proportioned: ~1.65:1 width:height ratio)
+$fui-toggle-width-sm: 2.857rem !default; // 40px
+$fui-toggle-width-md: 3.643rem !default; // 51px (iOS standard)
+$fui-toggle-width-lg: 4.286rem !default; // 60px
 $fui-toggle-height-sm: $fui-target-size-min !default; // 24px
-$fui-toggle-height-md: 2rem !default; // 28px
-$fui-toggle-thumb-sm: 1rem !default; // 14px
-$fui-toggle-thumb-md: 1.286rem !default; // 18px
+$fui-toggle-height-md: 2.214rem !default; // 31px (iOS standard)
+$fui-toggle-height-lg: 2.571rem !default; // 36px
+$fui-toggle-thumb-sm: 1.286rem !default; // 18px
+$fui-toggle-thumb-md: 1.929rem !default; // 27px (iOS standard)
 $fui-toggle-thumb-offset: 2px !default; // Thumb inset from track edge
 
 // Badge
@@ -308,7 +294,7 @@ $fui-anim-offset-md: 8px !default; // Medium slide animation
 $fui-arrow-size: 10px !default;
 
 // Sidebar-specific
-$fui-sidebar-item-height: 2.5rem !default; // 35px (5 units)
+$fui-sidebar-item-height: computed.$computed-sidebar-item-height !default; // density-responsive (compact: 30px, default: 35px, relaxed: 38px)
 $fui-sidebar-subitem-height: 2.571rem !default; // 36px
 $fui-sidebar-indicator-width: 2px !default;
 $fui-sidebar-indicator-height: 1.143rem !default; // 16px
@@ -340,9 +326,6 @@ $fui-colorpicker-pointer-border: 2px !default;
 
 // AppShell Layout
 $fui-appshell-header-height: 56px !default;
-$fui-appshell-sidebar-width: 240px !default;
-$fui-appshell-sidebar-collapsed-width: 64px !default;
-$fui-appshell-aside-width: 280px !default;
 $fui-header-z-index: 40 !default;
 
 // ThemeToggle sizes (derived from density)
@@ -362,8 +345,6 @@ $fui-code-header-bg: #1c1c1f !default;
 $fui-code-text: #d4d4d4 !default;
 $fui-code-text-muted: #6b7280 !default;
 $fui-code-border: rgba(255, 255, 255, 0.1) !default;
-$fui-code-tab-bg: rgba(255, 255, 255, 0.03) !default;
-$fui-code-tab-border: rgba(255, 255, 255, 0.08) !default;
 $fui-code-tab-text: #9ca3af !default;
 $fui-code-tab-text-active: #e5e7eb !default;
 $fui-code-copy-bg: rgba(255, 255, 255, 0.1) !default;
@@ -381,17 +362,12 @@ $fui-tooltip-shadow:
   0 4px 6px -1px rgba(0, 0, 0, 0.2),
   0 2px 4px -2px rgba(0, 0, 0, 0.15) !default;
 
-// Hero/Marketing gradient accent
-$fui-hero-gradient-color: rgba(120, 119, 198, 0.15) !default;
-
 // CodeBlock (dark mode) - same as light, code blocks stay dark
 $fui-dark-code-bg: #000000 !default;
 $fui-dark-code-header-bg: var(--fui-bg-elevated) !default;
 $fui-dark-code-text: #d4d4d4 !default;
 $fui-dark-code-text-muted: #6b7280 !default;
 $fui-dark-code-border: rgba(255, 255, 255, 0.1) !default;
-$fui-dark-code-tab-bg: rgba(255, 255, 255, 0.03) !default;
-$fui-dark-code-tab-border: rgba(255, 255, 255, 0.08) !default;
 $fui-dark-code-tab-text: #9ca3af !default;
 $fui-dark-code-tab-text-active: #e5e7eb !default;
 $fui-dark-code-copy-bg: rgba(255, 255, 255, 0.1) !default;
@@ -409,9 +385,6 @@ $fui-dark-tooltip-shadow:
   0 4px 6px -1px rgba(0, 0, 0, 0.3),
   0 2px 4px -2px rgba(0, 0, 0, 0.25) !default;
 
-// Hero/Marketing gradient accent (dark mode)
-$fui-dark-hero-gradient-color: rgba(120, 119, 198, 0.25) !default;
-
 // --------------------------------------------
 // CSS Custom Properties Export
 // --------------------------------------------
@@ -420,10 +393,26 @@ $fui-dark-hero-gradient-color: rgba(120, 119, 198, 0.25) !default;
 
 @mixin fui-css-variables {
   :root {
+    // Enable light-dark() automatic dark mode via color-scheme.
+    // Browsers supporting light-dark() (~92%) get automatic prefers-color-scheme support.
+    // Manual toggle via [data-theme="dark"] / .dark still works (sets color-scheme: dark).
+    color-scheme: light dark;
+
     // Base configuration
     font-size: #{$fui-base-font-size};
     --fui-base-unit: #{$fui-base-unit};
 
+    // Seed colors — the 5 configurable seeds exposed as custom properties.
+    // Tracks SCSS seed variables, so compile-time customization is reflected.
+    // Consumers can override at runtime: `document.documentElement.style.setProperty('--fui-seed-brand', '#0066ff')`
+    // The @supports block below derives accent/semantic tokens from these seeds
+    // using relative color syntax in OKLCH space (perceptually uniform).
+    --fui-seed-brand: #{$fui-color-accent};
+    --fui-seed-danger: #{$fui-color-danger};
+    --fui-seed-success: #{$fui-color-success};
+    --fui-seed-warning: #{$fui-color-warning};
+    --fui-seed-info: #{$fui-color-info};
+
     // Typography
     --fui-font-sans: #{$fui-font-sans};
     --fui-font-mono: #{$fui-font-mono};
@@ -458,19 +447,6 @@ $fui-dark-hero-gradient-color: rgba(120, 119, 198, 0.25) !default;
     --fui-space-10: #{$fui-space-10};
     --fui-space-12: #{$fui-space-12};
 
-    // Density padding
-    --fui-padding-container-sm: #{$fui-padding-container-sm};
-    --fui-padding-container-md: #{$fui-padding-container-md};
-    --fui-padding-container-lg: #{$fui-padding-container-lg};
-    --fui-padding-container-xl: #{$fui-padding-container-xl};
-    --fui-padding-inline-sm: #{$fui-padding-inline-sm};
-    --fui-padding-inline-md: #{$fui-padding-inline-md};
-    --fui-padding-inline-lg: #{$fui-padding-inline-lg};
-    --fui-padding-item-xs: #{$fui-padding-item-xs};
-    --fui-padding-item-sm: #{$fui-padding-item-sm};
-    --fui-padding-item-md: #{$fui-padding-item-md};
-    --fui-padding-item-lg: #{$fui-padding-item-lg};
-
     // Border radius
     --fui-radius-sm: #{$fui-radius-sm};
     --fui-radius-md: #{$fui-radius-md};
@@ -482,115 +458,180 @@ $fui-dark-hero-gradient-color: rgba(120, 119, 198, 0.25) !default;
     --fui-transition-fast: #{$fui-transition-fast};
     --fui-transition-normal: #{$fui-transition-normal};
 
-    // Colors
-    --fui-color-accent: #{$fui-color-accent};
-    --fui-color-accent-hover: #{$fui-color-accent-hover};
-    --fui-color-accent-active: #{$fui-color-accent-active};
+    // Colors — Accent (light-dark for automatic dark mode)
+    --fui-color-accent: light-dark(#{$fui-color-accent}, #{$fui-dark-color-accent});
+    --fui-color-accent-hover: light-dark(#{$fui-color-accent-hover}, #{$fui-dark-color-accent-hover});
+    --fui-color-accent-active: light-dark(#{$fui-color-accent-active}, #{$fui-dark-color-accent-active});
+
+    // Colors — Semantic (same in light/dark, no light-dark() needed)
     --fui-color-danger: #{$fui-color-danger};
     --fui-color-danger-hover: #{$fui-color-danger-hover};
     --fui-color-success: #{$fui-color-success};
     --fui-color-warning: #{$fui-color-warning};
     --fui-color-info: #{$fui-color-info};
-    --fui-color-danger-bg: #{$fui-color-danger-bg};
-    --fui-color-success-bg: #{$fui-color-success-bg};
-    --fui-color-warning-bg: #{$fui-color-warning-bg};
-    --fui-color-info-bg: #{$fui-color-info-bg};
-    --fui-color-danger-text: #{$fui-color-danger-text};
-    --fui-color-success-text: #{$fui-color-success-text};
-    --fui-color-warning-text: #{$fui-color-warning-text};
-    --fui-color-info-text: #{$fui-color-info-text};
-    --fui-backdrop: #{$fui-backdrop};
+
+    // Colors — Semantic Backgrounds
+    --fui-color-danger-bg: light-dark(#{$fui-color-danger-bg}, #{$fui-dark-color-danger-bg});
+    --fui-color-success-bg: light-dark(#{$fui-color-success-bg}, #{$fui-dark-color-success-bg});
+    --fui-color-warning-bg: light-dark(#{$fui-color-warning-bg}, #{$fui-dark-color-warning-bg});
+    --fui-color-info-bg: light-dark(#{$fui-color-info-bg}, #{$fui-dark-color-info-bg});
+
+    // Colors — Semantic Text
+    --fui-color-danger-text: light-dark(#{$fui-color-danger-text}, #{$fui-dark-color-danger-text});
+    --fui-color-success-text: light-dark(#{$fui-color-success-text}, #{$fui-dark-color-success-text});
+    --fui-color-warning-text: light-dark(#{$fui-color-warning-text}, #{$fui-dark-color-warning-text});
+    --fui-color-info-text: light-dark(#{$fui-color-info-text}, #{$fui-dark-color-info-text});
+
+    // Backdrop
+    --fui-backdrop: light-dark(#{$fui-backdrop}, #{$fui-dark-backdrop});
 
     // Surfaces
-    --fui-bg-primary: #{$fui-bg-primary};
-    --fui-bg-secondary: #{$fui-bg-secondary};
-    --fui-bg-tertiary: #{$fui-bg-tertiary};
-    --fui-bg-elevated: #{$fui-bg-elevated};
-    --fui-bg-subtle: #{$fui-bg-subtle};
-    --fui-bg-hover: #{$fui-bg-hover};
-    --fui-bg-active: #{$fui-bg-active};
+    --fui-bg-primary: light-dark(#{$fui-bg-primary}, #{$fui-dark-bg-primary});
+    --fui-bg-secondary: light-dark(#{$fui-bg-secondary}, #{$fui-dark-bg-secondary});
+    --fui-bg-tertiary: light-dark(#{$fui-bg-tertiary}, #{$fui-dark-bg-tertiary});
+    --fui-bg-elevated: light-dark(#{$fui-bg-elevated}, #{$fui-dark-bg-elevated});
+    --fui-bg-subtle: light-dark(#{$fui-bg-subtle}, #{$fui-dark-bg-subtle});
+    --fui-bg-hover: light-dark(#{$fui-bg-hover}, #{$fui-dark-bg-hover});
+    --fui-bg-active: light-dark(#{$fui-bg-active}, #{$fui-dark-bg-active});
 
     // Text
-    --fui-text-primary: #{$fui-text-primary};
-    --fui-text-secondary: #{$fui-text-secondary};
-    --fui-text-tertiary: #{$fui-text-tertiary};
-    --fui-text-inverse: #{$fui-text-inverse};
+    --fui-text-primary: light-dark(#{$fui-text-primary}, #{$fui-dark-text-primary});
+    --fui-text-secondary: light-dark(#{$fui-text-secondary}, #{$fui-dark-text-secondary});
+    --fui-text-tertiary: light-dark(#{$fui-text-tertiary}, #{$fui-dark-text-tertiary});
+    --fui-text-inverse: light-dark(#{$fui-text-inverse}, #{$fui-dark-text-inverse});
 
     // Borders
-    --fui-border: #{$fui-border};
-    --fui-border-default: #{$fui-border-default};
-    --fui-border-strong: #{$fui-border-strong};
+    --fui-border: light-dark(#{$fui-border}, #{$fui-dark-border});
+    --fui-border-default: light-dark(#{$fui-border-default}, #{$fui-dark-border-default});
+    --fui-border-strong: light-dark(#{$fui-border-strong}, #{$fui-dark-border-strong});
 
-    // Shadows
+    // Shadows (not <color> type — light-dark() can't be used, handled in dark overrides)
     --fui-shadow-sm: #{$fui-shadow-sm};
     --fui-shadow-md: #{$fui-shadow-md};
     --fui-shadow-lg: #{$fui-shadow-lg};
 
     // Focus
-    --fui-focus-ring-color: #{$fui-focus-ring-color};
+    --fui-focus-ring-color: light-dark(#{$fui-focus-ring-color}, #{$fui-dark-focus-ring-color});
     --fui-focus-ring-offset: #{$fui-focus-ring-offset};
     --fui-focus-ring-width: #{$fui-focus-ring-width};
 
     // Scrollbar
     --fui-scrollbar-width: #{$fui-scrollbar-width};
-    --fui-scrollbar-track: #{$fui-scrollbar-track};
-    --fui-scrollbar-thumb: #{$fui-scrollbar-thumb};
-    --fui-scrollbar-thumb-hover: #{$fui-scrollbar-thumb-hover};
+    --fui-scrollbar-track: light-dark(#{$fui-scrollbar-track}, #{$fui-dark-scrollbar-track});
+    --fui-scrollbar-thumb: light-dark(#{$fui-scrollbar-thumb}, #{$fui-dark-scrollbar-thumb});
+    --fui-scrollbar-thumb-hover: light-dark(#{$fui-scrollbar-thumb-hover}, #{$fui-dark-scrollbar-thumb-hover});
 
-    // Component heights
+    // Component heights (density-responsive)
     --fui-button-height-sm: #{$fui-button-height-sm};
     --fui-button-height-md: #{$fui-button-height-md};
     --fui-button-height-lg: #{$fui-button-height-lg};
-    --fui-input-height: #{$fui-input-height};
     --fui-input-height-sm: #{$fui-input-height-sm};
+    --fui-input-height: #{$fui-input-height};
     --fui-input-height-lg: #{$fui-input-height-lg};
+
+    // Touch targets (density-responsive, WCAG 2.5.8: ≥24px)
+    --fui-touch-sm: #{$fui-touch-sm};
+    --fui-touch-md: #{$fui-touch-md};
+    --fui-touch-lg: #{$fui-touch-lg};
     --fui-target-size-min: #{$fui-target-size-min};
-    --fui-target-size-comfortable: #{$fui-target-size-comfortable};
+
+    // Sidebar (density-responsive)
+    --fui-sidebar-item-height: #{$fui-sidebar-item-height};
 
     // AppShell Layout
     --fui-appshell-header-height: #{$fui-appshell-header-height};
-    --fui-appshell-sidebar-width: #{$fui-appshell-sidebar-width};
-    --fui-appshell-sidebar-collapsed-width: #{$fui-appshell-sidebar-collapsed-width};
-    --fui-appshell-aside-width: #{$fui-appshell-aside-width};
     --fui-header-z-index: #{$fui-header-z-index};
 
-    // CodeBlock
-    --fui-code-bg: #{$fui-code-bg};
-    --fui-code-header-bg: #{$fui-code-header-bg};
-    --fui-code-text: #{$fui-code-text};
-    --fui-code-text-muted: #{$fui-code-text-muted};
-    --fui-code-border: #{$fui-code-border};
-    --fui-code-tab-bg: #{$fui-code-tab-bg};
-    --fui-code-tab-border: #{$fui-code-tab-border};
-    --fui-code-tab-text: #{$fui-code-tab-text};
-    --fui-code-tab-text-active: #{$fui-code-tab-text-active};
-    --fui-code-copy-bg: #{$fui-code-copy-bg};
-    --fui-code-copy-bg-hover: #{$fui-code-copy-bg-hover};
-    --fui-code-highlight-bg: #{$fui-code-highlight-bg};
-    --fui-code-selection-bg: #{$fui-code-selection-bg};
-    --fui-code-scrollbar-track: #{$fui-code-scrollbar-track};
-    --fui-code-scrollbar-thumb: #{$fui-code-scrollbar-thumb};
-    --fui-code-scrollbar-thumb-hover: #{$fui-code-scrollbar-thumb-hover};
-
-    // Tooltip
-    --fui-tooltip-bg: #{$fui-tooltip-bg};
-    --fui-tooltip-text: #{$fui-tooltip-text};
-    --fui-tooltip-shadow: #{$fui-tooltip-shadow};
-
-    // Hero/Marketing gradient
-    --fui-hero-gradient-color: #{$fui-hero-gradient-color};
   }
 
-  // Dark mode via data-theme attribute (manual toggle)
+  // Dark mode via data-theme attribute (manual toggle).
+  // Sets color-scheme: dark so light-dark() resolves to dark values.
+  // Explicit overrides kept as fallback for browsers without light-dark() (~8%).
   :root[data-theme="dark"] {
+    color-scheme: dark;
     @include _fui-dark-tokens;
   }
 
   // Dark mode via .dark class on html
   :root.dark {
+    color-scheme: dark;
     @include _fui-dark-tokens;
   }
 
+  // Light mode explicit override (for manual toggle back to light)
+  :root[data-theme="light"] {
+    color-scheme: light;
+  }
+
+  // ============================================
+  // Runtime Color Derivation (Progressive Enhancement)
+  // ============================================
+  // Browsers supporting relative color syntax (~93%) get reactive tokens
+  // that auto-update when --fui-seed-* properties change at runtime.
+  // Derivation uses OKLCH space for perceptually uniform results.
+  // Browsers without support gracefully fall through to SCSS-computed values above.
+  // Usage: document.documentElement.style.setProperty('--fui-seed-brand', '#0066ff')
+  //   → accent, accent-hover, accent-active, focus-ring all update automatically.
+
+  @supports (color: oklch(from red l c h)) {
+    :root {
+      // Accent derived from seed-brand
+      // Light mode: brand as-is; dark mode: inverted lightness, reduced chroma
+      --fui-color-accent: light-dark(
+        var(--fui-seed-brand),
+        oklch(from var(--fui-seed-brand) clamp(0.88, calc(1 - l + 0.1), 0.96) min(c, 0.05) h)
+      );
+      --fui-color-accent-hover: light-dark(
+        oklch(from var(--fui-seed-brand) max(0.05, calc(l - 0.06)) c h),
+        oklch(from var(--fui-seed-brand) clamp(0.80, calc(1 - l + 0.02), 0.90) min(c, 0.05) h)
+      );
+      --fui-color-accent-active: light-dark(
+        oklch(from var(--fui-seed-brand) max(0.05, calc(l - 0.12)) c h),
+        oklch(from var(--fui-seed-brand) clamp(0.73, calc(1 - l - 0.05), 0.85) min(c, 0.05) h)
+      );
+
+      // Semantic hover derived from seed
+      --fui-color-danger-hover: oklch(from var(--fui-seed-danger) max(0.05, calc(l - 0.06)) c h);
+
+      // Semantic backgrounds derived via color-mix (opacity-based)
+      --fui-color-danger-bg: light-dark(
+        color-mix(in oklch, var(--fui-seed-danger) 10%, transparent),
+        color-mix(in oklch, var(--fui-seed-danger) 15%, transparent)
+      );
+      --fui-color-success-bg: light-dark(
+        color-mix(in oklch, var(--fui-seed-success) 10%, transparent),
+        color-mix(in oklch, var(--fui-seed-success) 15%, transparent)
+      );
+      --fui-color-warning-bg: light-dark(
+        color-mix(in oklch, var(--fui-seed-warning) 10%, transparent),
+        color-mix(in oklch, var(--fui-seed-warning) 15%, transparent)
+      );
+      --fui-color-info-bg: light-dark(
+        color-mix(in oklch, var(--fui-seed-info) 10%, transparent),
+        color-mix(in oklch, var(--fui-seed-info) 15%, transparent)
+      );
+
+      // Focus ring derived from seed-brand
+      --fui-focus-ring-color: light-dark(
+        var(--fui-seed-brand),
+        oklch(from var(--fui-seed-brand) clamp(0.88, calc(1 - l + 0.1), 0.96) min(c, 0.05) h)
+      );
+    }
+
+    // Runtime-derived dark mode overrides (replaces SCSS-computed when supported)
+    :root[data-theme="dark"],
+    :root.dark {
+      --fui-color-accent: oklch(from var(--fui-seed-brand) clamp(0.88, calc(1 - l + 0.1), 0.96) min(c, 0.05) h);
+      --fui-color-accent-hover: oklch(from var(--fui-seed-brand) clamp(0.80, calc(1 - l + 0.02), 0.90) min(c, 0.05) h);
+      --fui-color-accent-active: oklch(from var(--fui-seed-brand) clamp(0.73, calc(1 - l - 0.05), 0.85) min(c, 0.05) h);
+      --fui-color-danger-bg: color-mix(in oklch, var(--fui-seed-danger) 15%, transparent);
+      --fui-color-success-bg: color-mix(in oklch, var(--fui-seed-success) 15%, transparent);
+      --fui-color-warning-bg: color-mix(in oklch, var(--fui-seed-warning) 15%, transparent);
+      --fui-color-info-bg: color-mix(in oklch, var(--fui-seed-info) 15%, transparent);
+      --fui-focus-ring-color: oklch(from var(--fui-seed-brand) clamp(0.88, calc(1 - l + 0.1), 0.96) min(c, 0.05) h);
+    }
+  }
+
   // High contrast mode via system preference
   @media (prefers-contrast: more) {
     :root {
@@ -708,29 +749,4 @@ $fui-dark-hero-gradient-color: rgba(120, 119, 198, 0.25) !default;
   --fui-scrollbar-thumb: #{$fui-dark-scrollbar-thumb};
   --fui-scrollbar-thumb-hover: #{$fui-dark-scrollbar-thumb-hover};
 
-  // CodeBlock
-  --fui-code-bg: #{$fui-dark-code-bg};
-  --fui-code-header-bg: #{$fui-dark-code-header-bg};
-  --fui-code-text: #{$fui-dark-code-text};
-  --fui-code-text-muted: #{$fui-dark-code-text-muted};
-  --fui-code-border: #{$fui-dark-code-border};
-  --fui-code-tab-bg: #{$fui-dark-code-tab-bg};
-  --fui-code-tab-border: #{$fui-dark-code-tab-border};
-  --fui-code-tab-text: #{$fui-dark-code-tab-text};
-  --fui-code-tab-text-active: #{$fui-dark-code-tab-text-active};
-  --fui-code-copy-bg: #{$fui-dark-code-copy-bg};
-  --fui-code-copy-bg-hover: #{$fui-dark-code-copy-bg-hover};
-  --fui-code-highlight-bg: #{$fui-dark-code-highlight-bg};
-  --fui-code-selection-bg: #{$fui-dark-code-selection-bg};
-  --fui-code-scrollbar-track: #{$fui-dark-code-scrollbar-track};
-  --fui-code-scrollbar-thumb: #{$fui-dark-code-scrollbar-thumb};
-  --fui-code-scrollbar-thumb-hover: #{$fui-dark-code-scrollbar-thumb-hover};
-
-  // Tooltip
-  --fui-tooltip-bg: #{$fui-dark-tooltip-bg};
-  --fui-tooltip-text: #{$fui-dark-tooltip-text};
-  --fui-tooltip-shadow: #{$fui-dark-tooltip-shadow};
-
-  // Hero/Marketing gradient
-  --fui-hero-gradient-color: #{$fui-dark-hero-gradient-color};
 }

package/src/utils/aria.ts

@@ -0,0 +1,63 @@
+import * as React from 'react';
+
+/**
+ * Merge multiple aria ID values into a single space-separated string.
+ * Filters out undefined/empty values. Returns undefined if no valid IDs.
+ */
+export function mergeAriaIds(...ids: Array<string | undefined>): string | undefined {
+  const merged = ids.filter(Boolean).join(' ').trim();
+  return merged.length > 0 ? merged : undefined;
+}
+
+/**
+ * Normalize a flexible error prop (boolean | string) into its constituent parts.
+ * Used by form components that accept `error?: boolean | string`.
+ */
+export function normalizeError(error?: boolean | string): {
+  hasError: boolean;
+  errorMessage: string | undefined;
+} {
+  return {
+    hasError: !!error,
+    errorMessage: typeof error === 'string' ? error : undefined,
+  };
+}
+
+// ============================================
+// Form Field ID Generation
+// ============================================
+
+/**
+ * Hook that generates consistent ARIA IDs for form field components.
+ * Eliminates duplicated ID generation across Select, Combobox, DatePicker, RadioGroup, etc.
+ */
+export function useFormFieldIds(
+  prefix: string,
+  opts: { label?: string; helperText?: string; error?: boolean | string }
+) {
+  const id = React.useId();
+  const labelId = opts.label ? `${prefix}-label-${id}` : undefined;
+  const { hasError, errorMessage } = normalizeError(opts.error);
+  const errorId = errorMessage ? `${prefix}-error-${id}` : undefined;
+  const helperId = opts.helperText ? `${prefix}-helper-${id}` : undefined;
+  return { id, labelId, helperId, errorId, hasError, errorMessage };
+}
+
+// ============================================
+// Shared Form Field Types
+// ============================================
+
+/**
+ * Base props shared by all form field components.
+ * Extend this interface to get consistent label, helper, error, and disabled props.
+ */
+export interface FormFieldProps {
+  /** Visible label text */
+  label?: string;
+  /** Helper text shown below the field */
+  helperText?: string;
+  /** Show error styling. When a string is provided, it is displayed as an error message. */
+  error?: boolean | string;
+  /** Whether the field is disabled */
+  disabled?: boolean;
+}