@fragments-sdk/ui 0.17.1 → 0.19.0

package/src/components/Tooltip/index.tsx

@@ -36,6 +36,9 @@ export interface TooltipProps extends Omit<React.HTMLAttributes<HTMLDivElement>,
   defaultOpen?: boolean;
   /** Callback when open state changes */
   onOpenChange?: (open: boolean) => void;
+  /** Whether clicking the trigger closes the tooltip.
+   * @default false */
+  closeOnClick?: boolean;
   /** Explicit props for the tooltip popup element (preferred over top-level HTMLAttributes for clarity) */
   contentProps?: React.HTMLAttributes<HTMLDivElement>;
 }
@@ -83,6 +86,7 @@ function TooltipRoot({
   open,
   defaultOpen,
   onOpenChange,
+  closeOnClick = false,
   contentProps,
   className,
   style,
@@ -113,8 +117,8 @@ function TooltipRoot({
     [children],
   );
 
-  if (disabled) {
-    return children;
+  if (disabled || !children) {
+    return children ?? null;
   }
 
   const {
@@ -129,7 +133,7 @@ function TooltipRoot({
       defaultOpen={defaultOpen}
       onOpenChange={onOpenChange}
     >
-      <BaseTooltip.Trigger render={renderTrigger} />
+      <BaseTooltip.Trigger closeOnClick={closeOnClick} render={renderTrigger} />
       <BaseTooltip.Portal>
         <BaseTooltip.Positioner
           side={side}

package/src/components/VisuallyHidden/VisuallyHidden.contract.json

@@ -0,0 +1,116 @@
+{
+  "$schema": "https://usefragments.com/schemas/contract.v1.json",
+  "name": "VisuallyHidden",
+  "description": "Hides content visually while keeping it accessible to screen readers. Essential for accessible icon-only buttons and supplementary text.",
+  "category": "navigation",
+  "tags": [
+    "accessibility",
+    "a11y",
+    "screen-reader",
+    "hidden",
+    "sr-only"
+  ],
+  "status": "stable",
+  "sourcePath": "src/components/VisuallyHidden/index.tsx",
+  "exportName": "VisuallyHidden",
+  "propsSummary": [
+    "children: node (required)",
+    "as: span|div (default: span)"
+  ],
+  "props": {
+    "children": {
+      "type": "node",
+      "description": "Content to hide visually",
+      "required": true
+    },
+    "as": {
+      "type": "enum",
+      "description": "HTML element to render",
+      "default": "span",
+      "required": false,
+      "values": [
+        "span",
+        "div"
+      ]
+    }
+  },
+  "usage": {
+    "when": [
+      "Providing accessible labels for icon-only buttons",
+      "Adding context that screen readers need but sighted users don't",
+      "Hiding decorative content while providing text alternatives",
+      "Skip links for keyboard navigation"
+    ],
+    "whenNot": [
+      "Hiding content from everyone (use display: none or conditional render)",
+      "Content that should be visible on focus (use focus-visible styles)",
+      "Temporarily hidden content (use proper ARIA attributes)",
+      "Lazy-loaded content (use suspense or loading states)"
+    ],
+    "guidelines": [
+      "Always use with icon-only interactive elements",
+      "Keep hidden text concise but descriptive",
+      "Test with screen readers to verify announcements",
+      "Don't overuse; visible text is often better",
+      "VisuallyHidden forwards DOM props and className to the rendered element"
+    ],
+    "accessibility": [
+      "Content is announced by screen readers",
+      "Content is focusable if interactive elements are inside",
+      "Essential for WCAG 2.1 compliance with icon-only controls",
+      "Must convey equivalent information to visual content"
+    ]
+  },
+  "examples": [
+    {
+      "name": "Icon Button Label",
+      "description": "Accessible label for icon-only button",
+      "code": "<button style={{\n  display: 'inline-flex',\n  alignItems: 'center',\n  justifyContent: 'center',\n  width: '40px',\n  height: '40px',\n  border: '1px solid var(--fui-border-default)',\n  borderRadius: '8px',\n  background: 'var(--fui-color-surface-primary)',\n  cursor: 'pointer'\n}}>\n  <svg width=\"20\" height=\"20\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" strokeWidth=\"2\">\n    <path d=\"M21 21l-6-6m2-5a7 7 0 11-14 0 7 7 0 0114 0z\" />\n  </svg>\n  <VisuallyHidden>Search</VisuallyHidden>\n</button>"
+    },
+    {
+      "name": "Supplementary Text",
+      "description": "Additional context for screen readers",
+      "code": "<a href=\"#\" style={{ color: 'var(--fui-color-accent)' }}>\n  Read more\n  <VisuallyHidden> about our accessibility features</VisuallyHidden>\n</a>"
+    },
+    {
+      "name": "Skip Link",
+      "description": "Navigation aid that becomes visible on focus",
+      "code": "<div>\n  <VisuallyHidden as=\"div\">\n    <a\n      href=\"#main-content\"\n      style={{\n        position: 'absolute',\n        padding: '8px 16px',\n        background: 'var(--fui-color-accent)',\n        color: 'white'\n      }}\n    >\n      Skip to main content\n    </a>\n  </VisuallyHidden>\n  <p style={{ color: 'var(--fui-color-text-tertiary)', fontSize: '14px' }}>\n    (Screen reader only: \"Skip to main content\" link)\n  </p>\n</div>"
+    }
+  ],
+  "relations": [
+    {
+      "component": "Button",
+      "relationship": "child",
+      "note": "Use inside icon-only buttons for accessible labels"
+    },
+    {
+      "component": "Icon",
+      "relationship": "sibling",
+      "note": "Pair with icons to provide text alternatives"
+    }
+  ],
+  "contract": {
+    "propsSummary": [
+      "children: ReactNode - hidden text (required)",
+      "as: span|div - HTML element",
+      "Forwards standard DOM props (id, aria-*, data-*, className, handlers)"
+    ],
+    "a11yRules": [
+      "A11Y_SR_ONLY",
+      "A11Y_ICON_LABEL"
+    ]
+  },
+  "ai": {
+    "compositionPattern": "compound",
+    "subComponents": [
+      "Root"
+    ]
+  },
+  "provenance": {
+    "source": "migrated",
+    "verified": false,
+    "frameworkSupport": "native",
+    "extractedAt": "2026-03-13T23:19:06.625Z"
+  }
+}

package/src/index.ts

@@ -1,6 +1,8 @@
-// Import CSS variables and base styles
-// This ensures --fui-* variables are available when using any component
-import './styles/globals.scss';
+// CSS variables and base styles are NOT auto-imported here.
+// Consumers must import styles separately with seed configuration:
+//   @use '@fragments-sdk/ui/styles' with ($fui-brand: ..., $fui-neutral: ...);
+// Bundling globals.scss here would compile with default seeds and
+// override any consumer-configured palette.
 
 // Runtime CSS detection — warns if component styles aren't loaded
 import { checkCssLoaded } from './utils/css-warning';
@@ -404,6 +406,8 @@ export {
   type PromptVariant,
   type PromptTextareaProps,
   type PromptToolbarProps,
+  type PromptTabsProps,
+  type PromptTabProps,
   type PromptActionsProps,
   type PromptInfoProps,
   type PromptActionButtonProps,
@@ -591,6 +595,7 @@ export {
   type DrawerBodyProps,
   type DrawerFooterProps,
   type DrawerCloseProps,
+  type DrawerSwipeAreaProps,
 } from './components/Drawer';
 
 // Pagination

package/src/styles/globals.scss

@@ -83,13 +83,18 @@ $fui-info: #3b82f6 !default;
   }
 
   // Base Element Resets
-  :where(html) {
+  // Use real specificity (not :where()) for font-size so it overrides
+  // the browser default 16px. This makes 1rem = 14px throughout.
+  html {
+    font-size: #{$fui-base-font-size};
     scroll-behavior: smooth;
   }
 
   :where(body) {
     margin: 0;
+    font-size: inherit;
     font-family: var(--fui-font-sans, Inter, system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif);
+    line-height: var(--fui-line-height-normal, $fui-line-height-normal);
     background-color: var(--fui-bg-primary, #ffffff);
     color: var(--fui-text-primary, #171717);
     -webkit-font-smoothing: antialiased;

package/src/tokens/_computed.scss

@@ -86,6 +86,7 @@ $computed-sidebar-item-height: density.px-to-rem($_density, map.get($_density, s
 
 // Accent colors (from brand seed)
 $computed-color-accent: seeds.$fui-brand;
+$computed-color-on-accent: derive.contrast-color(seeds.$fui-brand);
 $computed-color-accent-hover: derive.derive-accent-hover(seeds.$fui-brand, false);
 $computed-color-accent-active: derive.derive-accent-active(seeds.$fui-brand, false);
 
@@ -153,8 +154,9 @@ $computed-backdrop: derive.derive-backdrop(false);
 // Computed: Colors - Dark Mode
 // --------------------------------------------
 
-// Accent colors (derive light version for dark mode)
+// Accent colors — dark brands lightened for visibility; on-accent handles text contrast
 $computed-dark-color-accent: derive.derive-dark-accent(seeds.$fui-brand);
+$computed-dark-color-on-accent: derive.contrast-color($computed-dark-color-accent);
 $computed-dark-color-accent-hover: derive.derive-accent-hover($computed-dark-color-accent, true);
 $computed-dark-color-accent-active: derive.derive-accent-active($computed-dark-color-accent, true);
 

package/src/tokens/_density.scss

@@ -59,8 +59,8 @@ $density-default: (
   // Input height
   input-height: 40px,
   // ~6 units
-  input-height-sm: 28px,
-  // 4 units
+  input-height-sm: 32px,
+  // ~4.5 units
   input-height-lg: 44px,
   // ~6 units
   // Touch targets (baseline)
@@ -70,8 +70,8 @@ $density-default: (
   touch-lg: 44px,
   // WCAG AAA recommended
   // Sidebar navigation
-  sidebar-item-height: 35px,
-  // 5 units
+  sidebar-item-height: 36px,
+  // ~5 units
 );
 
 $density-relaxed: (

package/src/tokens/_derive.scss

@@ -20,14 +20,8 @@
 /// @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;
+  // oklch lightness is perceptually uniform (0-1 range)
+  @return color.channel($color, 'lightness', $space: oklch) < 0.5;
 }
 
 /// Get appropriate contrast color (black or white)
@@ -52,22 +46,22 @@
 /// @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: hsl);
+  $l: color.channel($base, 'lightness', $space: oklch);
 
   @if $is-dark {
-    @if $l > 85% {
+    @if $l > 0.85 {
       // Very light accent on dark bg: darken for visible hover
-      @return color.scale($base, $lightness: -10%);
+      @return color.adjust($base, $lightness: -0.05, $space: oklch);
     }
     // Standard dark mode: lighten for hover
-    @return color.scale($base, $lightness: 8%);
+    @return color.adjust($base, $lightness: 0.04, $space: oklch);
   } @else {
-    @if $l < 15% {
+    @if $l < 0.15 {
       // Very dark accent on light bg: lighten for visible hover
-      @return color.scale($base, $lightness: 18%);
+      @return color.adjust($base, $lightness: 0.09, $space: oklch);
     }
     // Standard light mode: darken for hover
-    @return color.scale($base, $lightness: -10%);
+    @return color.adjust($base, $lightness: -0.05, $space: oklch);
   }
 }
 
@@ -78,38 +72,36 @@
 /// @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: hsl);
+  $l: color.channel($base, 'lightness', $space: oklch);
 
   @if $is-dark {
-    @if $l > 85% {
+    @if $l > 0.85 {
       // Very light accent on dark bg: darken more for active
-      @return color.scale($base, $lightness: -16%);
+      @return color.adjust($base, $lightness: -0.08, $space: oklch);
     }
     // Standard dark mode: lighten more for active
-    @return color.scale($base, $lightness: 14%);
+    @return color.adjust($base, $lightness: 0.07, $space: oklch);
   } @else {
-    @if $l < 15% {
+    @if $l < 0.15 {
       // Very dark accent on light bg: lighten more for active
-      @return color.scale($base, $lightness: 28%);
+      @return color.adjust($base, $lightness: 0.14, $space: oklch);
     }
     // Standard light mode: darken more for active
-    @return color.scale($base, $lightness: -18%);
+    @return color.adjust($base, $lightness: -0.09, $space: oklch);
   }
 }
 
 /// Derive a light variant of accent for dark mode
-/// Auto-lightens dark brand colors so they're visible on dark backgrounds
+/// Lightens dark brand colors so the accent stands out on dark backgrounds.
+/// Clamps lightness to 0.45–0.85 and chroma to 0.12 to keep it muted.
 /// @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%);
-  }
+  $l: color.channel($brand, 'lightness', $space: oklch);
+  $c: color.channel($brand, 'chroma', $space: oklch);
+  $clamped-l: math.max(0.45, math.min($l, 0.85));
+  $clamped-c: math.min($c, 0.12);
+  @return oklch($clamped-l $clamped-c color.channel($brand, 'hue', $space: oklch));
 }
 
 // --------------------------------------------
@@ -129,9 +121,9 @@
   @for $i from 1 through 40 {
     @if wcag-contrast($adjusted, $bg) < $target {
       @if $is-dark {
-        $adjusted: color.adjust($adjusted, $lightness: 2%);
+        $adjusted: color.adjust($adjusted, $lightness: 2%, $space: oklch);
       } @else {
-        $adjusted: color.adjust($adjusted, $lightness: -2%);
+        $adjusted: color.adjust($adjusted, $lightness: -2%, $space: oklch);
       }
     }
   }
@@ -202,19 +194,23 @@
 /// @return {Map} Text token values
 @function derive-text($palette, $is-dark: false, $palette-name: 'stone') {
   @if $is-dark {
-    // Dark mode: light text on dark backgrounds
+    // Dark mode: neutral white text on all palettes.
+    // Palette-tinted text (e.g. green-on-green-dark) looks muddy and reduces
+    // readability. Every major dark theme (Linear, Vercel, Stripe, GitHub)
+    // uses neutral white text regardless of background tint.
     @return (
-      primary: get-shade($palette, 100),           // Main text (light on dark)
-      secondary: get-shade($palette, 400),         // Secondary 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%),
+      primary: #ffffff,
+      secondary: rgba(255, 255, 255, 0.6),
+      tertiary: rgba(255, 255, 255, 0.4),
       inverse: get-shade($palette, 900)            // Text on light accents
     );
   }
 
   // Light mode background — stone uses white, colorful palettes use palette[50]
-  $bg: if($palette-name != 'stone', get-shade($palette, 50), #ffffff);
+  $bg: #ffffff;
+  @if $palette-name != 'stone' {
+    $bg: get-shade($palette, 50);
+  }
 
   @return (
     primary: get-shade($palette, 900),           // Main text (high contrast)
@@ -236,16 +232,16 @@
 /// @return {Map} Border token values
 @function derive-borders($palette, $is-dark: false) {
   @if $is-dark {
-    // Dark mode: semi-transparent borders that adapt to any surface
+    // Dark mode: subtle white-alpha borders
     @return (
       default: rgba(255, 255, 255, 0.08),
-      strong: rgba(255, 255, 255, 0.14)
+      strong: rgba(255, 255, 255, 0.15)
     );
   } @else {
-    // Light mode: semi-transparent borders that adapt to any surface
+    // Light mode: reduced opacity (ChatGPT --border-light ~5%)
     @return (
-      default: rgba(0, 0, 0, 0.08),
-      strong: rgba(0, 0, 0, 0.14)
+      default: rgba(0, 0, 0, 0.05),
+      strong: rgba(0, 0, 0, 0.10)
     );
   }
 }
@@ -259,18 +255,18 @@
 /// @return {Map} Shadow token values
 @function derive-shadows($is-dark: false) {
   @if $is-dark {
-    // Dark mode: reduced shadows for AI-era aesthetic
+    // Dark mode: near-zero shadows (Linear uses borders, not shadows)
     @return (
-      sm: (0 1px 2px 0 rgba(0, 0, 0, 0.2)),
-      md: (0 2px 4px -1px rgba(0, 0, 0, 0.25), 0 1px 3px -2px rgba(0, 0, 0, 0.2)),
-      lg: (0 8px 12px -3px rgba(0, 0, 0, 0.35), 0 3px 5px -4px rgba(0, 0, 0, 0.25))
+      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: minimal shadows ("felt but not noticed")
+    // Light mode: flatter aesthetic (Linear/ChatGPT near-zero shadows)
     @return (
-      sm: (0 1px 2px 0 rgba(0, 0, 0, 0.03)),
-      md: (0 2px 4px -1px rgba(0, 0, 0, 0.06), 0 1px 3px -2px rgba(0, 0, 0, 0.04)),
-      lg: (0 8px 12px -3px rgba(0, 0, 0, 0.08), 0 3px 5px -4px rgba(0, 0, 0, 0.05))
+      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))
     );
   }
 }
@@ -321,7 +317,7 @@
 /// @param {Color} $color - The semantic color
 /// @return {Color} Hover state color
 @function derive-semantic-hover($color) {
-  @return color.scale($color, $lightness: -10%);
+  @return color.adjust($color, $lightness: -0.05, $space: oklch);
 }
 
 // --------------------------------------------
@@ -421,9 +417,9 @@
   @for $i from 1 through 40 {
     @if wcag-contrast($adjusted, $bg) < $target {
       @if $is-dark {
-        $adjusted: color.adjust($adjusted, $lightness: 2%);
+        $adjusted: color.adjust($adjusted, $lightness: 2%, $space: oklch);
       } @else {
-        $adjusted: color.adjust($adjusted, $lightness: -2%);
+        $adjusted: color.adjust($adjusted, $lightness: -2%, $space: oklch);
       }
     }
   }

package/src/tokens/_palettes.scss

@@ -83,6 +83,24 @@ $palette-earth: (
   950: #0a0f08   // Very dark green-gray for dark mode bg
 );
 
+// --------------------------------------------
+// Fragments - Rich saturated green tones
+// The Fragments brand palette — deep forest greens
+// --------------------------------------------
+$palette-fragments: (
+  50:  #f0f7f3,
+  100: #dceee3,
+  200: #b8ddc6,
+  300: #88c5a0,
+  400: #5aaa7a,
+  500: #3d8f60,
+  600: #2d7049,
+  700: #235536,
+  800: #1a3025,  // Dark card surface
+  900: #142318,  // Dark surface
+  950: #0d1f17   // Darkest bg
+);
+
 // --------------------------------------------
 // Fire - Warm red/orange tones
 // Energy, passion feel
@@ -110,6 +128,7 @@ $palettes: (
   "sand": $palette-sand,
   "earth": $palette-earth,
   "fire": $palette-fire,
+  "fragments": $palette-fragments,
   "wind": $palette-stone  // Legacy alias — "wind" was renamed to "stone"
 );
 
@@ -118,7 +137,7 @@ $palettes: (
 // --------------------------------------------
 
 /// Get a palette map by name
-/// @param {String} $name - Palette name (stone, ice, sand, earth, fire)
+/// @param {String} $name - Palette name (stone, ice, sand, earth, fire, fragments)
 /// @return {Map} The palette map with shades 50-950
 @function get-palette($name) {
   @if not map.has-key($palettes, $name) {

package/src/tokens/_seeds.scss

@@ -26,7 +26,7 @@
 $fui-brand: #18181b !default;
 
 /// Neutral palette name for surfaces, text, and borders
-/// Options: "stone" | "ice" | "earth" | "sand" | "fire"
+/// Options: "stone" | "ice" | "earth" | "sand" | "fire" | "fragments"
 /// @type String
 $fui-neutral: "stone" !default;
 
@@ -45,7 +45,7 @@ $fui-radius-style: "default" !default;
 // --------------------------------------------
 // Fail fast at compile time if invalid seed values are provided.
 
-$_valid-neutrals: "stone", "ice", "earth", "sand", "fire";
+$_valid-neutrals: "stone", "ice", "earth", "sand", "fire", "fragments";
 @if not list.index($_valid-neutrals, $fui-neutral) {
   @error "Invalid $fui-neutral: '#{$fui-neutral}'. Must be one of: #{$_valid-neutrals}";
 }