@usefragments/ui 1.5.4 → 1.7.0

package/src/components/Skeleton/Skeleton.contract.json

@@ -1,14 +1,9 @@
 {
   "$schema": "https://usefragments.com/schemas/contract.v1.json",
   "name": "Skeleton",
-  "description": "Placeholder loading state for content",
+  "description": "Holds the shape of content that has not arrived yet.",
   "category": "feedback",
-  "tags": [
-    "loading",
-    "placeholder",
-    "skeleton",
-    "shimmer"
-  ],
+  "tags": ["loading", "placeholder", "skeleton", "shimmer"],
   "status": "stable",
   "sourcePath": "src/components/Skeleton/index.tsx",
   "exportName": "Skeleton",
@@ -27,25 +22,14 @@
       "description": "Semantic variant that auto-sizes",
       "default": "rect",
       "required": false,
-      "values": [
-        "text",
-        "heading",
-        "avatar",
-        "button",
-        "input",
-        "rect"
-      ]
+      "values": ["text", "heading", "avatar", "button", "input", "rect"]
     },
     "size": {
       "type": "enum",
       "description": "Size for avatar/button variants",
       "default": "md",
       "required": false,
-      "values": [
-        "sm",
-        "md",
-        "lg"
-      ]
+      "values": ["sm", "md", "lg"]
     },
     "width": {
       "type": "union",
@@ -67,13 +51,7 @@
       "type": "enum",
       "description": "Border radius override",
       "required": false,
-      "values": [
-        "sm",
-        "md",
-        "lg",
-        "none",
-        "full"
-      ]
+      "values": ["sm", "md", "lg", "none", "full"]
     },
     "static": {
       "type": "boolean",
@@ -84,54 +62,53 @@
   },
   "usage": {
     "when": [
-      "Content is loading asynchronously",
-      "Preventing layout shift during data fetching",
-      "Providing visual feedback that content is coming",
-      "Improving perceived performance"
+      "Content is still being fetched",
+      "You want to stop the layout jumping when it lands",
+      "Making a wait feel shorter than it is"
     ],
     "whenNot": [
-      "Short loading times (< 300ms)",
-      "When spinner is more appropriate",
-      "Background operations without visible impact"
+      "Waits under about 300ms",
+      "A spinner says it better",
+      "Work the user cannot see anyway"
     ],
     "guidelines": [
-      "Match skeleton shape to expected content",
-      "Use semantic variants (text, heading, avatar) for consistency",
-      "Maintain similar dimensions to loaded content",
-      "Avoid too many skeleton elements - simplify complex layouts",
-      "Skeleton and Skeleton.Text forward DOM props (id, aria-*, data-*, handlers)"
+      "Match the shape and size of the real content",
+      "Prefer the text, heading, and avatar variants over hand-rolled boxes",
+      "Give Skeleton.Text an ancestor with a real width — percentage lines collapse without one",
+      "A few big shapes beat many small ones",
+      "Skeleton and Skeleton.Text forward id, aria-*, data-* and handlers"
     ],
     "accessibility": [
-      "Skeletons are decorative - use aria-hidden",
-      "Announce loading state separately if needed",
-      "Ensure sufficient contrast for the animation"
+      "Skeletons are decoration — hide them with aria-hidden",
+      "Announce the loading state separately if it matters",
+      "Keep the pulse subtle but visible against the surface"
     ]
   },
   "examples": [
     {
       "name": "Default",
-      "description": "Basic rectangle skeleton",
+      "description": "One rectangle at an explicit size.",
       "code": "<Skeleton width={200} height={20} />"
     },
     {
       "name": "Text Lines",
-      "description": "Multi-line text placeholder",
-      "code": "<Skeleton.Text lines={3} />"
+      "description": "Stacked lines that fill the width they are given.",
+      "code": "<div style={{ width: 260 }}>\n  <Skeleton.Text lines={3} />\n</div>"
     },
     {
       "name": "Semantic Variants",
-      "description": "Pre-configured shapes for common elements",
-      "code": "<div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--fui-space-2)' }}>\n  <Skeleton variant=\"heading\" width={200} />\n  <Skeleton variant=\"text\" width=\"100%\" />\n  <Skeleton variant=\"text\" width=\"80%\" />\n</div>"
+      "description": "Heading sits taller than the body lines under it.",
+      "code": "<div\n  style={{\n    width: 260,\n    display: 'flex',\n    flexDirection: 'column',\n    gap: 'var(--fui-space-2)',\n  }}\n>\n  <Skeleton variant=\"heading\" width={200} />\n  <Skeleton variant=\"text\" width=\"100%\" />\n  <Skeleton variant=\"text\" width=\"80%\" />\n</div>"
     },
     {
       "name": "Avatar Skeleton",
-      "description": "Circular placeholder for avatars",
+      "description": "Circles matching the three avatar sizes.",
       "code": "<div style={{ display: 'flex', gap: 'var(--fui-space-1)', alignItems: 'center' }}>\n  <Skeleton.Circle size=\"sm\" />\n  <Skeleton.Circle size=\"md\" />\n  <Skeleton.Circle size=\"lg\" />\n</div>"
     },
     {
       "name": "Card Skeleton",
-      "description": "Composed skeleton for a card layout",
-      "code": "<div style={{ width: 300, padding: 'var(--fui-space-2)', border: '1px solid var(--fui-border)', borderRadius: 'var(--fui-radius-lg)' }}>\n  <Skeleton variant=\"rect\" height={120} radius=\"md\" />\n  <div style={{ marginTop: 'var(--fui-space-2)' }}>\n    <Skeleton variant=\"heading\" width=\"60%\" />\n  </div>\n  <div style={{ marginTop: 'var(--fui-space-1)' }}>\n    <Skeleton.Text lines={2} />\n  </div>\n</div>"
+      "description": "Media, title, then body — the card before it loads.",
+      "code": "<div\n  style={{\n    width: 300,\n    padding: 'var(--fui-space-2)',\n    border: '1px solid var(--fui-border)',\n    borderRadius: 'var(--fui-radius-lg)',\n  }}\n>\n  <Skeleton variant=\"rect\" height={120} radius=\"md\" />\n  <div style={{ marginTop: 'var(--fui-space-2)' }}>\n    <Skeleton variant=\"heading\" width=\"60%\" />\n  </div>\n  <div style={{ marginTop: 'var(--fui-space-1)' }}>\n    <Skeleton.Text lines={2} />\n  </div>\n</div>"
     }
   ],
   "relations": [
@@ -152,10 +129,7 @@
   },
   "ai": {
     "compositionPattern": "compound",
-    "subComponents": [
-      "Text",
-      "Circle"
-    ]
+    "subComponents": ["Text", "Circle"]
   },
   "provenance": {
     "source": "migrated",

package/src/components/Skeleton/Skeleton.module.scss

@@ -1,30 +1,48 @@
-@use '../../tokens/variables' as *;
+@use "../../tokens/variables" as *;
+@use "../../recipes/representation" as representation;
 
 // ============================================
 // Skeleton Component Styles
 // ============================================
 
-// Animation
-@keyframes skeleton-pulse {
-  0%, 100% {
-    opacity: 1;
+// Animation — a highlight travelling across the placeholder, not the whole
+// block fading out. A pulsing opacity spends half its cycle invisible on a
+// light surface; the shimmer keeps the missing fact legible the entire time.
+@keyframes skeleton-shimmer {
+  from {
+    background-position: 120% 0;
   }
-  50% {
-    opacity: 0.5;
+  to {
+    background-position: -120% 0;
   }
 }
 
 // Base skeleton
 .skeleton {
   display: block;
-  background-color: var(--fui-bg-tertiary, #{$fui-bg-tertiary});
-  animation: skeleton-pulse 2s cubic-bezier(0.4, 0, 0.6, 1) infinite;
+  background-color: var(--fui-skeleton, #{$fui-bg-tertiary});
+  background-image: linear-gradient(
+    90deg,
+    var(--fui-skeleton, #{$fui-bg-tertiary}) 0%,
+    var(--fui-skeleton-hi, #{$fui-bg-secondary}) 45%,
+    var(--fui-skeleton, #{$fui-bg-tertiary}) 90%
+  );
+  background-size: 240% 100%;
+  animation: skeleton-shimmer var(--fui-duration-shimmer, $fui-duration-shimmer) linear infinite;
   border-radius: var(--fui-radius-md, #{$fui-radius-md});
 }
 
 // Static (no animation)
 .static {
   animation: none;
+  background-image: none;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .skeleton {
+    animation: none;
+    background-image: none;
+  }
 }
 
 // Fill parent
@@ -56,20 +74,10 @@
   border-radius: var(--fui-radius-full, #{$fui-radius-full});
 }
 
-// Avatar sizes (rem on a 14px root: 1rem = 14px)
-.avatar-sm {
-  width: var(--fui-space-4, #{$fui-space-4});   // 28px
-  height: var(--fui-space-4, #{$fui-space-4});
-}
-
-.avatar-md {
-  width: 2.5rem; // 35px (no clean ladder step between space-4=28 and space-6=42)
-  height: 2.5rem;
-}
-
-.avatar-lg {
-  width: var(--fui-space-6, #{$fui-space-6});   // 42px
-  height: var(--fui-space-6, #{$fui-space-6});
+@each $size in ("sm", "md", "lg") {
+  .avatar-#{$size} {
+    @include representation.skeleton("avatar", $size);
+  }
 }
 
 // Button - matches button heights
@@ -77,28 +85,36 @@
   border-radius: var(--fui-radius-md, #{$fui-radius-md});
 }
 
+@each $size in ("sm", "md", "lg") {
+  .button-#{$size} {
+    @include representation.skeleton("button", $size);
+  }
+}
+
 .button-sm {
-  height: var(--fui-button-height-sm, #{$fui-button-height-sm});
-  width: 5rem;  // 70px default width
+  inline-size: var(--fui-raw-space-64, 64px);
 }
 
 .button-md {
-  height: var(--fui-button-height-md, #{$fui-button-height-md});
-  width: 6rem;  // 84px default width
+  inline-size: calc(var(--fui-raw-space-64, 64px) + var(--fui-raw-space-16, 16px));
 }
 
 .button-lg {
-  height: var(--fui-button-height-lg, #{$fui-button-height-lg});
-  width: 7rem;  // 98px default width
+  inline-size: calc(var(--fui-raw-space-64, 64px) + var(--fui-raw-space-32, 32px));
 }
 
 // Input - matches input field height
 .input {
-  height: var(--fui-input-height, #{$fui-input-height});
-  width: 100%;
+  inline-size: 100%;
   border-radius: var(--fui-radius-md, #{$fui-radius-md});
 }
 
+@each $size in ("sm", "md", "lg") {
+  .input-#{$size} {
+    @include representation.skeleton("field", $size);
+  }
+}
+
 // Rect - generic rectangle (no preset dimensions)
 .rect {
   // Uses explicit width/height from props or fill
@@ -139,18 +155,19 @@
 }
 
 .gap-sm {
-  gap: var(--fui-space-2, #{$fui-space-2}); // 14px
+  gap: var(--fui-raw-space-8, 8px);
 }
 
 .gap-md {
-  gap: var(--fui-space-3, #{$fui-space-3}); // 21px
+  gap: var(--fui-raw-space-12, 12px);
 }
 
 .textLine {
   height: 1em;
   width: 100%;
   background-color: var(--fui-bg-tertiary, #{$fui-bg-tertiary});
-  animation: skeleton-pulse 2s cubic-bezier(0.4, 0, 0.6, 1) infinite;
+  animation: skeleton-pulse var(--fui-duration-shimmer, $fui-duration-shimmer)
+    cubic-bezier(0.4, 0, 0.6, 1) infinite;
   border-radius: var(--fui-radius-sm, #{$fui-radius-sm});
 }
 

package/src/components/Skeleton/index.tsx

@@ -1,19 +1,19 @@
-import * as React from 'react';
-import styles from './Skeleton.module.scss';
+import * as React from "react";
+import styles from "./Skeleton.module.scss";
 
 // ============================================
 // Types
 // ============================================
 
 export type SkeletonVariant =
-  | 'text'      // Single line of text, height: 1em
-  | 'heading'   // Heading text, height: 1.5em
-  | 'avatar'    // Circular, uses size prop
-  | 'button'    // Button shape, uses size prop
-  | 'input'     // Form input height
-  | 'rect';     // Rectangle, requires explicit dimensions or fill
+  | "text" // Single line of text, height: 1em
+  | "heading" // Heading text, height: 1.5em
+  | "avatar" // Circular, uses size prop
+  | "button" // Button shape, uses size prop
+  | "input" // Form input height
+  | "rect"; // Rectangle, requires explicit dimensions or fill
 
-export type SkeletonSize = 'sm' | 'md' | 'lg';
+export type SkeletonSize = "sm" | "md" | "lg";
 
 export interface SkeletonProps extends React.HTMLAttributes<HTMLDivElement> {
   /**
@@ -22,7 +22,7 @@ export interface SkeletonProps extends React.HTMLAttributes<HTMLDivElement> {
    */
   variant?: SkeletonVariant;
   /**
-   * Size variant for avatar/button. Ignored for text/heading/input.
+   * Size variant for avatar, button, and input placeholders.
    * @default 'md'
    */
   size?: SkeletonSize;
@@ -42,7 +42,7 @@ export interface SkeletonProps extends React.HTMLAttributes<HTMLDivElement> {
   /**
    * Border radius override. Auto-determined for most variants.
    */
-  radius?: 'none' | 'sm' | 'md' | 'lg' | 'full';
+  radius?: "none" | "sm" | "md" | "lg" | "full";
   /**
    * Disable animation for reduced motion preference.
    * @default false
@@ -50,7 +50,7 @@ export interface SkeletonProps extends React.HTMLAttributes<HTMLDivElement> {
   static?: boolean;
 }
 
-export interface SkeletonTextProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'children'> {
+export interface SkeletonTextProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "children"> {
   /** Number of text lines to render */
   lines?: number;
   /**
@@ -60,59 +60,60 @@ export interface SkeletonTextProps extends Omit<React.HTMLAttributes<HTMLDivElem
    */
   lastLineWidth?: number;
   /** Gap between lines. Uses spacing tokens. */
-  gap?: 'sm' | 'md';
+  gap?: "sm" | "md";
 }
 
 // ============================================
 // Component
 // ============================================
 
-const SkeletonBase = React.forwardRef<HTMLDivElement, SkeletonProps>(
-  function SkeletonBase(
-    {
-      variant = 'rect',
-      size = 'md',
-      width,
-      height,
-      fill = false,
-      radius,
-      static: isStatic = false,
-      className,
-      ...htmlProps
-    },
-    ref
-  ) {
-    const classes = [
-      styles.skeleton,
-      styles[variant],
-      variant === 'avatar' && styles[`avatar-${size}`],
-      variant === 'button' && styles[`button-${size}`],
-      fill && styles.fill,
-      radius && styles[`radius-${radius}`],
-      isStatic && styles.static,
-      className,
-    ].filter(Boolean).join(' ');
-
-    const style: React.CSSProperties = {};
-
-    if (width !== undefined) {
-      style.width = typeof width === 'number' ? `${width}px` : width;
-    }
-    if (height !== undefined) {
-      style.height = typeof height === 'number' ? `${height}px` : height;
-    }
+const SkeletonBase = React.forwardRef<HTMLDivElement, SkeletonProps>(function SkeletonBase(
+  {
+    variant = "rect",
+    size = "md",
+    width,
+    height,
+    fill = false,
+    radius,
+    static: isStatic = false,
+    className,
+    ...htmlProps
+  },
+  ref
+) {
+  const classes = [
+    styles.skeleton,
+    styles[variant],
+    variant === "avatar" && styles[`avatar-${size}`],
+    variant === "button" && styles[`button-${size}`],
+    variant === "input" && styles[`input-${size}`],
+    fill && styles.fill,
+    radius && styles[`radius-${radius}`],
+    isStatic && styles.static,
+    className,
+  ]
+    .filter(Boolean)
+    .join(" ");
 
-    return (
-      <div
-        ref={ref}
-        {...htmlProps}
-        className={classes}
-        style={Object.keys(style).length > 0 ? style : undefined}
-        aria-hidden="true"
-      />
-    );
+  const style: React.CSSProperties = {};
+
+  if (width !== undefined) {
+    style.width = typeof width === "number" ? `${width}px` : width;
+  }
+  if (height !== undefined) {
+    style.height = typeof height === "number" ? `${height}px` : height;
   }
-);
+
+  return (
+    <div
+      ref={ref}
+      {...htmlProps}
+      className={classes}
+      style={Object.keys(style).length > 0 ? style : undefined}
+      aria-hidden="true"
+    />
+  );
+});
 
 // ============================================
 // Skeleton.Text - Multi-line text skeleton
@@ -121,15 +122,13 @@ const SkeletonBase = React.forwardRef<HTMLDivElement, SkeletonProps>(
 function SkeletonText({
   lines = 3,
   lastLineWidth = 80,
-  gap = 'sm',
+  gap = "sm",
   className,
   ...htmlProps
 }: SkeletonTextProps) {
-  const containerClasses = [
-    styles.textContainer,
-    styles[`gap-${gap}`],
-    className,
-  ].filter(Boolean).join(' ');
+  const containerClasses = [styles.textContainer, styles[`gap-${gap}`], className]
+    .filter(Boolean)
+    .join(" ");
 
   return (
     <div {...htmlProps} className={containerClasses} aria-hidden="true">
@@ -152,21 +151,15 @@ function SkeletonText({
 // ============================================
 
 function SkeletonCircle({
-  size = 'md',
+  size = "md",
   className,
 }: {
   size?: SkeletonSize | number;
   className?: string;
 }) {
-  if (typeof size === 'number') {
+  if (typeof size === "number") {
     return (
-      <SkeletonBase
-        variant="rect"
-        width={size}
-        height={size}
-        radius="full"
-        className={className}
-      />
+      <SkeletonBase variant="rect" width={size} height={size} radius="full" className={className} />
     );
   }
   return <SkeletonBase variant="avatar" size={size} className={className} />;

package/src/components/Slider/Slider.contract.json

@@ -1,15 +1,9 @@
 {
   "$schema": "https://usefragments.com/schemas/contract.v1.json",
   "name": "Slider",
-  "description": "Range input control for selecting a numeric value within a defined range. Supports labels, value display, and custom step intervals.",
-  "category": "forms",
-  "tags": [
-    "slider",
-    "range",
-    "input",
-    "number",
-    "control"
-  ],
+  "description": "Selects a numeric value within a defined range.",
+  "category": "inputs",
+  "tags": ["slider", "range", "input", "number", "control"],
   "status": "stable",
   "sourcePath": "src/components/Slider/index.tsx",
   "exportName": "Slider",
@@ -141,63 +135,63 @@
   },
   "usage": {
     "when": [
-      "Selecting a value from a continuous range",
-      "Volume or brightness controls",
-      "Price range filters",
-      "Settings that benefit from visual feedback"
+      "Any value along a range, where roughly right is good enough",
+      "Volume, brightness, opacity",
+      "Price and range filters",
+      "The effect is visible as the user drags"
     ],
     "whenNot": [
-      "Precise numeric input (use Input type=\"number\")",
-      "Discrete options (use RadioGroup or Select)",
-      "Yes/no choices (use Switch)"
+      "An exact number matters (use Input type=\"number\")",
+      "A handful of fixed choices (use RadioGroup or Select)",
+      "On or off (use Switch)"
     ],
     "guidelines": [
-      "Always provide a label describing what the slider controls",
-      "Show the current value when precision matters",
-      "Use appropriate min/max values for the context",
-      "Consider step size for usability"
+      "Label what the track controls",
+      "Turn on showValue whenever the number matters",
+      "Set min and max to the real limits, not 0-100 by habit",
+      "Pick a step the user can actually land on"
     ],
     "accessibility": [
-      "Label is associated with the slider",
-      "Keyboard accessible with arrow keys",
-      "Current value is announced to screen readers",
-      "Uses native slider semantics"
+      "Label is tied to the track",
+      "Arrow keys move the thumb",
+      "The current value is announced",
+      "Native slider semantics throughout"
     ]
   },
   "examples": [
     {
       "name": "Default",
-      "description": "Basic slider with label",
+      "description": "0-100 with no number shown.",
       "code": "<div style={{ width: '300px' }}>\n  <Slider label=\"Volume\" defaultValue={50} />\n</div>"
     },
     {
       "name": "With Value Display",
-      "description": "Shows current value alongside the slider",
+      "description": "showValue prints the number opposite the label.",
       "code": "<div style={{ width: '300px' }}>\n  <Slider\n    label=\"Brightness\"\n    defaultValue={75}\n    showValue\n    valueSuffix=\"%\"\n  />\n</div>"
     },
     {
       "name": "Custom Range",
-      "description": "Custom min, max, and step values",
+      "description": "min, max and step bound the track to real-world units.",
       "code": "<div style={{ width: '300px', display: 'flex', flexDirection: 'column', gap: '16px' }}>\n  <Slider\n    label=\"Temperature\"\n    min={60}\n    max={80}\n    step={1}\n    defaultValue={72}\n    showValue\n    valueSuffix=\"°F\"\n  />\n  <Slider\n    label=\"Font Size\"\n    min={12}\n    max={32}\n    step={2}\n    defaultValue={16}\n    showValue\n    valueSuffix=\"px\"\n  />\n</div>"
     },
     {
       "name": "Controlled",
-      "description": "Controlled slider with external state",
+      "description": "The parent owns the value and can react to every move.",
       "code": "<ControlledSliderDemo />"
     },
     {
       "name": "Drag Value Bubble",
-      "description": "Shows a floating value bubble while the thumb is being dragged",
+      "description": "The number floats above the thumb only while dragging.",
       "code": "<div style={{ width: '300px' }}>\n  <Slider\n    label=\"Mix\"\n    defaultValue={40}\n    showValueOnDrag\n    valueSuffix=\"%\"\n  />\n</div>"
     },
     {
       "name": "With Helper Text",
-      "description": "Slider with helper text guidance",
+      "description": "A line below the track explains the trade-off.",
       "code": "<div style={{ width: '300px' }}>\n  <Slider\n    label=\"Quality\"\n    defaultValue={80}\n    showValue\n    valueSuffix=\"%\"\n    helperText=\"Higher quality increases file size\"\n  />\n</div>"
     },
     {
       "name": "Disabled",
-      "description": "Disabled slider",
+      "description": "Dimmed; the thumb will not move.",
       "code": "<div style={{ width: '300px' }}>\n  <Slider\n    label=\"Locked Setting\"\n    defaultValue={30}\n    showValue\n    disabled\n  />\n</div>"
     }
   ],
@@ -227,17 +221,11 @@
       "showValueOnDrag: boolean - show value bubble during drag",
       "valueSuffix: string - unit suffix"
     ],
-    "a11yRules": [
-      "A11Y_LABEL_REQUIRED",
-      "A11Y_KEYBOARD_ACCESSIBLE",
-      "A11Y_TARGET_SIZE_MIN"
-    ]
+    "a11yRules": ["A11Y_LABEL_REQUIRED", "A11Y_KEYBOARD_ACCESSIBLE", "A11Y_TARGET_SIZE_MIN"]
   },
   "ai": {
     "compositionPattern": "compound",
-    "subComponents": [
-      "Root"
-    ]
+    "subComponents": ["Root"]
   },
   "provenance": {
     "source": "migrated",