@fragments-sdk/ui 0.14.0 → 0.16.0

package/src/components/Toggle/Toggle.module.scss

@@ -11,11 +11,11 @@
 
   &[data-disabled] {
     cursor: not-allowed;
-    opacity: 0.38;
+    opacity: 0.5;
   }
 }
 
-.rootWithDescription {
+.rootWithHelper {
   align-items: flex-start;
 
   .track {
@@ -35,7 +35,7 @@
   // iOS unchecked: semi-transparent gray — visible in both light and dark
   background-color: var(--fui-bg-active, $fui-bg-active);
   overflow: hidden;
-  transition: background-color 250ms cubic-bezier(0.4, 0.0, 0.2, 1);
+  transition: background-color var(--fui-transition-normal, $fui-transition-normal);
 
   // Checked: accent fill
   .root[data-checked] & {
@@ -52,11 +52,9 @@
     background-color: var(--fui-color-accent-hover, $fui-color-accent-hover);
   }
 
-  // Focus ring
+  // Focus ring (consistent box-shadow approach across all form controls)
   .root:focus-visible & {
-    outline: var(--fui-focus-ring-width, $fui-focus-ring-width) solid
-      var(--fui-focus-ring-color, $fui-focus-ring-color);
-    outline-offset: var(--fui-focus-ring-offset, $fui-focus-ring-offset);
+    @include focus-ring;
   }
 }
 
@@ -73,6 +71,19 @@
   );
 }
 
+// Lg: 60×36
+.trackLg {
+  width: var(--fui-toggle-width-lg, $fui-toggle-width-lg);
+  height: var(--fui-toggle-height-lg, $fui-toggle-height-lg);
+  --_toggle-thumb-size: calc(var(--fui-toggle-height-lg, #{$fui-toggle-height-lg}) - 4px);
+  --_toggle-inset: 2px;
+  --_toggle-translate: calc(
+    var(--fui-toggle-width-lg, #{$fui-toggle-width-lg}) -
+    var(--_toggle-thumb-size) -
+    4px
+  );
+}
+
 // Md: 51×31 (iOS standard)
 .trackMd {
   width: var(--fui-toggle-width-md, $fui-toggle-width-md);
@@ -86,7 +97,10 @@
   );
 }
 
-// iOS-style thumb: always white, multi-layer shadow
+// iOS-style thumb: always white, multi-layer shadow.
+// The thumb is intentionally always white (#fff) to match iOS toggle UX — this is
+// a hardcoded design decision (like CodeBlock/Tooltip dark surfaces). Override via
+// --fui-toggle-thumb-bg and --fui-toggle-thumb-shadow CSS custom properties.
 .thumb {
   position: absolute;
   top: var(--_toggle-inset, $fui-toggle-thumb-offset);
@@ -96,15 +110,17 @@
   height: var(--_toggle-thumb-size, $fui-toggle-thumb-md);
   border-radius: 50%;
   pointer-events: none;
-  background-color: #fff;
-  box-shadow:
+  background-color: var(--fui-toggle-thumb-bg, #fff);
+  box-shadow: var(
+    --fui-toggle-thumb-shadow,
     0 3px 8px rgba(0, 0, 0, 0.15),
     0 1px 1px rgba(0, 0, 0, 0.06),
-    0 3px 1px rgba(0, 0, 0, 0.06);
+    0 3px 1px rgba(0, 0, 0, 0.06)
+  );
   transition:
-    transform 250ms cubic-bezier(0.4, 0.0, 0.2, 1),
-    background-color 250ms cubic-bezier(0.4, 0.0, 0.2, 1),
-    width 120ms cubic-bezier(0.4, 0.0, 0.2, 1);
+    transform var(--fui-transition-normal, $fui-transition-normal),
+    background-color var(--fui-transition-normal, $fui-transition-normal),
+    width var(--fui-transition-fast, $fui-transition-fast);
 
   // Slide right when checked — inverse color for contrast against accent
   .root[data-checked] & {
@@ -132,24 +148,43 @@
   font-weight: var(--fui-font-weight-medium, $fui-font-weight-medium);
   color: var(--fui-text-primary, $fui-text-primary);
   line-height: var(--fui-line-height-tight, $fui-line-height-tight);
+  user-select: none;
 }
 
 .labelSm {
   font-size: var(--fui-font-size-xs, $fui-font-size-xs);
 }
 
-.description {
+.labelLg {
+  font-size: var(--fui-font-size-base, $fui-font-size-base);
+}
+
+.helper {
   display: block;
   font-size: var(--fui-font-size-xs, $fui-font-size-xs);
   color: var(--fui-text-secondary, $fui-text-secondary);
-  margin-top: var(--fui-space-0-5, $fui-space-0-5);
-  line-height: var(--fui-line-height-tight, $fui-line-height-tight);
+  margin-top: var(--fui-space-1, $fui-space-1);
+  line-height: var(--fui-line-height-normal, $fui-line-height-normal);
 }
 
-.descriptionSm {
+.helperSm {
   font-size: var(--fui-font-size-2xs, $fui-font-size-2xs);
 }
 
+// ============================================
+// Accessibility: High Contrast Mode
+// ============================================
+
+@media (prefers-contrast: more) {
+  .track {
+    border: 2px solid var(--fui-text-primary, $fui-text-primary);
+  }
+
+  .root[data-checked] .track {
+    border-color: var(--fui-color-accent, $fui-color-accent);
+  }
+}
+
 // ============================================
 // Accessibility: Reduced Motion
 // ============================================

package/src/components/Toggle/index.tsx

@@ -14,13 +14,16 @@ export interface SwitchProps {
   /** Default checked state (uncontrolled) */
   defaultChecked?: boolean;
   /** Called when the switch is toggled */
-  onChange?: (checked: boolean) => void;
-  /** Alias for onChange (Radix convention) */
   onCheckedChange?: (checked: boolean) => void;
+  /** Alias for onCheckedChange */
+  onChange?: (checked: boolean) => void;
   label?: string;
+  /** Helper text shown below the label */
+  helperText?: string;
+  /** @deprecated Use helperText instead. */
   description?: string;
   disabled?: boolean;
-  size?: 'sm' | 'md';
+  size?: 'sm' | 'md' | 'lg';
   className?: string;
   name?: string;
   id?: string;
@@ -39,6 +42,7 @@ const SwitchRoot = React.forwardRef<HTMLButtonElement, SwitchProps>(
       onChange,
       onCheckedChange,
       label,
+      helperText,
       description,
       disabled = false,
       size = 'md',
@@ -51,27 +55,32 @@ const SwitchRoot = React.forwardRef<HTMLButtonElement, SwitchProps>(
     },
     ref
   ) {
+    const resolvedHelperText = helperText ?? description;
     const trackClasses = [
       styles.track,
-      size === 'sm' ? styles.trackSm : styles.trackMd,
+      size === 'sm' ? styles.trackSm : size === 'lg' ? styles.trackLg : styles.trackMd,
     ].join(' ');
 
     const thumbClasses = styles.thumb;
 
-    const labelClasses = [styles.label, size === 'sm' && styles.labelSm]
+    const labelClasses = [
+      styles.label,
+      size === 'sm' && styles.labelSm,
+      size === 'lg' && styles.labelLg,
+    ]
       .filter(Boolean)
       .join(' ');
 
-    const descClasses = [
-      styles.description,
-      size === 'sm' && styles.descriptionSm,
+    const helperClasses = [
+      styles.helper,
+      size === 'sm' && styles.helperSm,
     ]
       .filter(Boolean)
       .join(' ');
 
     const rootClasses = [
       styles.root,
-      description && styles.rootWithDescription,
+      resolvedHelperText && styles.rootWithHelper,
       className,
     ]
       .filter(Boolean)
@@ -83,7 +92,7 @@ const SwitchRoot = React.forwardRef<HTMLButtonElement, SwitchProps>(
         id={id}
         checked={checked}
         defaultChecked={defaultChecked}
-        onCheckedChange={onChange ?? onCheckedChange}
+        onCheckedChange={onCheckedChange ?? onChange}
         disabled={disabled}
         name={name}
         className={rootClasses}
@@ -95,10 +104,10 @@ const SwitchRoot = React.forwardRef<HTMLButtonElement, SwitchProps>(
           <BaseSwitch.Thumb className={thumbClasses} />
         </span>
 
-        {(label || description) && (
+        {(label || resolvedHelperText) && (
           <div className={styles.content}>
             {label && <span className={labelClasses}>{label}</span>}
-            {description && <span className={descClasses}>{description}</span>}
+            {resolvedHelperText && <span className={helperClasses}>{resolvedHelperText}</span>}
           </div>
         )}
       </BaseSwitch.Root>

package/src/index.ts

@@ -341,6 +341,7 @@ export {
   AppShell,
   type AppShellProps,
   type AppShellLayout,
+  type AppShellSlotVariant,
   type AppShellHeaderProps,
   type AppShellSidebarProps,
   type AppShellMainProps,
@@ -664,5 +665,35 @@ export {
   type UseKeyboardShortcutOptions,
 } from './utils/keyboard-shortcuts';
 
+// Seed Derivation
+export {
+  type SeedConfig,
+  PALETTES,
+  RADIUS_STYLES,
+  PALETTE_SEMANTIC_COLORS,
+  DEFAULT_SEEDS,
+  getSemanticColors,
+  deriveText,
+  deriveSurfaces,
+  deriveBorders,
+  deriveShadows,
+  deriveAccentHover,
+  deriveAccentActive,
+  deriveDarkAccent,
+  deriveSemanticText,
+  deriveSemanticBg,
+  deriveSemanticHover,
+} from './utils/seed-derivation';
+
+// Theme Presets
+export {
+  PRESETS,
+  PRESET_DEFINITIONS,
+  generatePreset,
+  seedsToTheme,
+  type ThemeConfig,
+  type PresetDefinition,
+} from './utils/theme-presets';
+
 // Legacy aliases (deprecated)
 export { Switch as Toggle, type SwitchProps as ToggleProps } from './components/Switch';

package/src/styles/globals.scss

@@ -48,100 +48,107 @@ $fui-info: #3b82f6 !default;
 );
 
 @use '../tokens/variables' as *;
-
-// Output all CSS custom properties
-@include fui-css-variables;
+@use '../tokens/property-registrations' as prop-reg;
 
 // ============================================
-// Box-Sizing Reset
+// Cascade Layer Order Declaration
 // ============================================
+// Establishes the priority order for the cascade.
+// Consumer styles outside any @layer always win over layered styles.
+// Within layers: tokens < base < components (declared first = lowest priority).
+// Browser support: ~97% (Chrome 99+, Firefox 97+, Safari 15.4+)
+@layer fui.tokens, fui.base;
 
-*,
-*::before,
-*::after {
-  box-sizing: border-box;
-}
+// Output typed @property registrations (must be top-level, can't be in @layer)
+@include prop-reg.fui-property-registrations;
 
 // ============================================
-// Base Element Resets
+// Tokens Layer — CSS custom properties & theming
 // ============================================
 
-html {
-  scroll-behavior: smooth;
+@layer fui.tokens {
+  @include fui-css-variables;
 }
 
-body {
-  margin: 0;
-  font-family: var(--fui-font-sans, Inter, system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif);
-  background-color: var(--fui-bg-primary, #ffffff);
-  color: var(--fui-text-primary, #171717);
-  -webkit-font-smoothing: antialiased;
-  -moz-osx-font-smoothing: grayscale;
-  font-feature-settings: "rlig" 1, "calt" 1;
-}
+// ============================================
+// Base Layer — Resets & defaults
+// ============================================
+// Uses :where() for zero-specificity resets where possible.
+// Any consumer selector overrides these without specificity fighting.
 
-// Global link reset
-a {
-  text-decoration: none;
-}
+@layer fui.base {
+  // Box-Sizing Reset
+  :where(*, *::before, *::after) {
+    box-sizing: border-box;
+  }
 
-*::selection {
-  background-color: var(--fui-color-success-bg, rgba(16, 163, 127, 0.1));
-  color: var(--fui-text-primary, #171717);
-}
+  // Base Element Resets
+  :where(html) {
+    scroll-behavior: smooth;
+  }
 
-// ============================================
-// Scrollbar Styles
-// ============================================
+  :where(body) {
+    margin: 0;
+    font-family: var(--fui-font-sans, Inter, system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif);
+    background-color: var(--fui-bg-primary, #ffffff);
+    color: var(--fui-text-primary, #171717);
+    -webkit-font-smoothing: antialiased;
+    -moz-osx-font-smoothing: grayscale;
+    font-feature-settings: "rlig" 1, "calt" 1;
+  }
 
-::-webkit-scrollbar {
-  width: 6px;
-  height: 6px;
-}
+  // Global link reset
+  :where(a) {
+    text-decoration: none;
+  }
 
-::-webkit-scrollbar-track {
-  background-color: transparent;
-}
+  ::selection {
+    background-color: var(--fui-color-success-bg, rgba(16, 163, 127, 0.1));
+    color: var(--fui-text-primary, #171717);
+  }
 
-::-webkit-scrollbar-thumb {
-  background-color: var(--fui-text-tertiary, #8a8a8a);
-  border-radius: 9999px;
-}
+  // Scrollbar Styles
+  ::-webkit-scrollbar {
+    width: 6px;
+    height: 6px;
+  }
 
-::-webkit-scrollbar-thumb:hover {
-  background-color: var(--fui-text-secondary, #525252);
-}
+  ::-webkit-scrollbar-track {
+    background-color: transparent;
+  }
 
-// Firefox scrollbar
-* {
-  scrollbar-width: thin;
-  scrollbar-color: var(--fui-text-tertiary, #8a8a8a) transparent;
-}
+  ::-webkit-scrollbar-thumb {
+    background-color: var(--fui-text-tertiary, #8a8a8a);
+    border-radius: 9999px;
+  }
 
-// ============================================
-// Accessibility: Reduced Motion
-// ============================================
+  ::-webkit-scrollbar-thumb:hover {
+    background-color: var(--fui-text-secondary, #525252);
+  }
 
-@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;
+  // Firefox scrollbar
+  :where(*) {
+    scrollbar-width: thin;
+    scrollbar-color: var(--fui-text-tertiary, #8a8a8a) transparent;
   }
-}
 
-// ============================================
-// Accessibility: Focus Visible
-// ============================================
+  // Accessibility: Reduced Motion
+  @media (prefers-reduced-motion: reduce) {
+    :where(*, *::before, *::after) {
+      animation-duration: 0.01ms !important;
+      animation-iteration-count: 1 !important;
+      transition-duration: 0.01ms !important;
+      scroll-behavior: auto !important;
+    }
+  }
 
-:focus:not(:focus-visible) {
-  outline: none;
-}
+  // Accessibility: Focus Visible
+  :where(:focus:not(:focus-visible)) {
+    outline: none;
+  }
 
-:focus-visible {
-  outline: var(--fui-focus-ring-width, 2px) solid var(--fui-focus-ring-color, #18181b);
-  outline-offset: var(--fui-focus-ring-offset, 2px);
+  :where(:focus-visible) {
+    outline: var(--fui-focus-ring-width, 2px) solid var(--fui-focus-ring-color, #18181b);
+    outline-offset: var(--fui-focus-ring-offset, 2px);
+  }
 }

package/src/tokens/_computed.scss

@@ -77,6 +77,9 @@ $computed-touch-sm: density.px-to-rem($_density, map.get($_density, touch-sm));
 $computed-touch-md: density.px-to-rem($_density, map.get($_density, touch-md));
 $computed-touch-lg: density.px-to-rem($_density, map.get($_density, touch-lg));
 
+// Sidebar navigation (from density)
+$computed-sidebar-item-height: density.px-to-rem($_density, map.get($_density, sidebar-item-height));
+
 // --------------------------------------------
 // Computed: Colors - Light Mode
 // --------------------------------------------
@@ -106,7 +109,7 @@ $computed-color-warning-text: derive.derive-semantic-text(seeds.$fui-warning, fa
 $computed-color-info-text: derive.derive-semantic-text(seeds.$fui-info, false);
 
 // Surfaces (from neutral palette)
-$_surfaces-light: derive.derive-surfaces($_palette, false);
+$_surfaces-light: derive.derive-surfaces($_palette, false, seeds.$fui-neutral);
 $computed-bg-primary: map.get($_surfaces-light, primary);
 $computed-bg-secondary: map.get($_surfaces-light, secondary);
 $computed-bg-tertiary: map.get($_surfaces-light, tertiary);
@@ -116,7 +119,7 @@ $computed-bg-hover: map.get($_surfaces-light, hover);
 $computed-bg-active: map.get($_surfaces-light, active);
 
 // Text (from neutral palette)
-$_text-light: derive.derive-text($_palette, false);
+$_text-light: derive.derive-text($_palette, false, seeds.$fui-neutral);
 $computed-text-primary: map.get($_text-light, primary);
 $computed-text-secondary: map.get($_text-light, secondary);
 $computed-text-tertiary: map.get($_text-light, tertiary);
@@ -168,7 +171,7 @@ $computed-dark-color-warning-text: derive.derive-semantic-text(seeds.$fui-warnin
 $computed-dark-color-info-text: derive.derive-semantic-text(seeds.$fui-info, true);
 
 // Surfaces (dark mode)
-$_surfaces-dark: derive.derive-surfaces($_palette, true);
+$_surfaces-dark: derive.derive-surfaces($_palette, true, seeds.$fui-neutral);
 $computed-dark-bg-primary: map.get($_surfaces-dark, primary);
 $computed-dark-bg-secondary: map.get($_surfaces-dark, secondary);
 $computed-dark-bg-tertiary: map.get($_surfaces-dark, tertiary);
@@ -178,7 +181,7 @@ $computed-dark-bg-hover: map.get($_surfaces-dark, hover);
 $computed-dark-bg-active: map.get($_surfaces-dark, active);
 
 // Text (dark mode)
-$_text-dark: derive.derive-text($_palette, true);
+$_text-dark: derive.derive-text($_palette, true, seeds.$fui-neutral);
 $computed-dark-text-primary: map.get($_text-dark, primary);
 $computed-dark-text-secondary: map.get($_text-dark, secondary);
 $computed-dark-text-tertiary: map.get($_text-dark, tertiary);

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
 );
 
 // --------------------------------------------