@usefragments/ui 1.6.0 → 2.0.0

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

@@ -1,19 +1,14 @@
 {
   "$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",
   "propsSummary": [
-    "variant: text|heading|avatar|button|input|rect (default: rect)",
+    "shape: text|heading|avatar|button|input|rect (default: rect)",
     "size: sm|md|lg (default: md)",
     "width: union",
     "height: union",
@@ -22,30 +17,19 @@
     "static: boolean (default: false)"
   ],
   "props": {
-    "variant": {
+    "shape": {
       "type": "enum",
-      "description": "Semantic variant that auto-sizes",
+      "description": "Semantic shape 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",
+      "description": "Size for avatar/button shapes",
       "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 shapes 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>"
+      "name": "Semantic Shapes",
+      "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 shape=\"heading\" width={200} />\n  <Skeleton shape=\"text\" width=\"100%\" />\n  <Skeleton shape=\"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 shape=\"rect\" height={120} radius=\"md\" />\n  <div style={{ marginTop: 'var(--fui-space-2)' }}>\n    <Skeleton shape=\"heading\" width=\"60%\" />\n  </div>\n  <div style={{ marginTop: 'var(--fui-space-1)' }}>\n    <Skeleton.Text lines={2} />\n  </div>\n</div>"
     }
   ],
   "relations": [
@@ -143,7 +120,7 @@
   ],
   "contract": {
     "propsSummary": [
-      "variant: text|heading|avatar|button|input|rect",
+      "shape: text|heading|avatar|button|input|rect",
       "size: sm|md|lg (for avatar/button)",
       "width/height: custom dimensions",
       "fill: boolean - fill parent",
@@ -152,10 +129,7 @@
   },
   "ai": {
     "compositionPattern": "compound",
-    "subComponents": [
-      "Text",
-      "Circle"
-    ]
+    "subComponents": ["Text", "Circle"]
   },
   "provenance": {
     "source": "migrated",

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

@@ -1,55 +1,72 @@
 @use "../../tokens/variables" as *;
+@use "../../tokens/measurements.generated" as measurements;
 @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
 .fill {
-  width: 100%;
-  height: 100%;
+  inline-size: 100%;
+  block-size: 100%;
 }
 
 // ============================================
-// Semantic Variants
+// Semantic shapes
 // ============================================
 
 // Text - single line of body text
 .text {
-  height: 1em;
-  width: 100%;
+  block-size: 1em;
+  inline-size: 100%;
   border-radius: var(--fui-radius-sm, #{$fui-radius-sm});
 }
 
 // Heading - taller for headings
 .heading {
-  height: 1.5em;
-  width: 100%;
+  block-size: 1.5em;
+  inline-size: 100%;
   border-radius: var(--fui-radius-sm, #{$fui-radius-sm});
 }
 
@@ -76,15 +93,21 @@
 }
 
 .button-sm {
-  inline-size: var(--fui-raw-space-64, 64px);
+  inline-size: var(--fui-raw-space-64, #{measurements.raw-space(64)});
 }
 
 .button-md {
-  inline-size: calc(var(--fui-raw-space-64, 64px) + var(--fui-raw-space-16, 16px));
+  inline-size: calc(
+    var(--fui-raw-space-64, #{measurements.raw-space(64)}) +
+      var(--fui-raw-space-16, #{measurements.raw-space(16)})
+  );
 }
 
 .button-lg {
-  inline-size: calc(var(--fui-raw-space-64, 64px) + var(--fui-raw-space-32, 32px));
+  inline-size: calc(
+    var(--fui-raw-space-64, #{measurements.raw-space(64)}) +
+      var(--fui-raw-space-32, #{measurements.raw-space(32)})
+  );
 }
 
 // Input - matches input field height
@@ -109,7 +132,7 @@
 // ============================================
 
 .radius-none {
-  border-radius: 0;
+  border-radius: var(--fui-radius-none, #{$fui-radius-none});
 }
 
 .radius-sm {
@@ -135,22 +158,23 @@
 .textContainer {
   display: flex;
   flex-direction: column;
-  width: 100%;
+  inline-size: 100%;
 }
 
 .gap-sm {
-  gap: var(--fui-raw-space-8, 8px);
+  gap: var(--fui-raw-space-8, #{measurements.raw-space(8)});
 }
 
 .gap-md {
-  gap: var(--fui-raw-space-12, 12px);
+  gap: var(--fui-raw-space-12, #{measurements.raw-space(12)});
 }
 
 .textLine {
-  height: 1em;
-  width: 100%;
+  block-size: 1em;
+  inline-size: 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

@@ -5,7 +5,7 @@ import styles from "./Skeleton.module.scss";
 // Types
 // ============================================
 
-export type SkeletonVariant =
+export type SkeletonShape =
   | "text" // Single line of text, height: 1em
   | "heading" // Heading text, height: 1.5em
   | "avatar" // Circular, uses size prop
@@ -17,21 +17,22 @@ export type SkeletonSize = "sm" | "md" | "lg";
 
 export interface SkeletonProps extends React.HTMLAttributes<HTMLDivElement> {
   /**
-   * Semantic variant that auto-sizes based on design tokens.
+   * Semantic shape that auto-sizes from the design tokens. Not chrome, so it
+   * is `shape`, not `variant`.
    * @default 'rect'
    */
-  variant?: SkeletonVariant;
+  shape?: SkeletonShape;
   /**
-   * Size variant for avatar, button, and input placeholders.
+   * Size for the avatar, button, and input shapes.
    * @default 'md'
    */
   size?: SkeletonSize;
   /**
-   * Width in pixels or CSS value. Auto-determined for most variants.
+   * Width in pixels or CSS value. Auto-determined for most shapes.
    */
   width?: number | string;
   /**
-   * Height in pixels or CSS value. Auto-determined for semantic variants.
+   * Height in pixels or CSS value. Auto-determined for semantic shapes.
    */
   height?: number | string;
   /**
@@ -40,7 +41,7 @@ export interface SkeletonProps extends React.HTMLAttributes<HTMLDivElement> {
    */
   fill?: boolean;
   /**
-   * Border radius override. Auto-determined for most variants.
+   * Border radius override. Auto-determined for most shapes.
    */
   radius?: "none" | "sm" | "md" | "lg" | "full";
   /**
@@ -69,7 +70,7 @@ export interface SkeletonTextProps extends Omit<React.HTMLAttributes<HTMLDivElem
 
 const SkeletonBase = React.forwardRef<HTMLDivElement, SkeletonProps>(function SkeletonBase(
   {
-    variant = "rect",
+    shape = "rect",
     size = "md",
     width,
     height,
@@ -83,10 +84,10 @@ const SkeletonBase = React.forwardRef<HTMLDivElement, SkeletonProps>(function Sk
 ) {
   const classes = [
     styles.skeleton,
-    styles[variant],
-    variant === "avatar" && styles[`avatar-${size}`],
-    variant === "button" && styles[`button-${size}`],
-    variant === "input" && styles[`input-${size}`],
+    styles[shape],
+    shape === "avatar" && styles[`avatar-${size}`],
+    shape === "button" && styles[`button-${size}`],
+    shape === "input" && styles[`input-${size}`],
     fill && styles.fill,
     radius && styles[`radius-${radius}`],
     isStatic && styles.static,
@@ -147,7 +148,7 @@ function SkeletonText({
 }
 
 // ============================================
-// Skeleton.Circle - Shorthand for avatar variant
+// Skeleton.Circle - Shorthand for the avatar shape
 // ============================================
 
 function SkeletonCircle({
@@ -159,10 +160,10 @@ function SkeletonCircle({
 }) {
   if (typeof size === "number") {
     return (
-      <SkeletonBase variant="rect" width={size} height={size} radius="full" className={className} />
+      <SkeletonBase shape="rect" width={size} height={size} radius="full" className={className} />
     );
   }
-  return <SkeletonBase variant="avatar" size={size} className={className} />;
+  return <SkeletonBase shape="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",

package/src/components/Slider/Slider.module.scss

@@ -45,20 +45,21 @@
   position: relative;
   width: 100%;
   background-color: var(--fui-form-group-bg, $fui-bg-secondary);
-  box-shadow: inset 0 0 0 1px var(--fui-form-group-border, $fui-border);
+  box-shadow: inset 0 0 0 var(--fui-stroke-hairline, 1px) var(--fui-form-group-border, $fui-border);
   border-radius: var(--fui-radius-full, $fui-radius-full);
   cursor: pointer;
 
   &[data-disabled] {
-    opacity: 0.5;
-    cursor: not-allowed;
+    @include disabled-state;
   }
+
+  @include high-contrast-outline;
 }
 
 .indicator {
   position: absolute;
   height: 100%;
-  background-color: var(--fui-field-selection-border, $fui-color-accent);
+  background-color: var(--fui-color-accent, $fui-color-accent);
   border-radius: var(--fui-radius-full, $fui-radius-full);
 }
 
@@ -67,7 +68,7 @@
   @include target.hit-area("compact");
 
   background-color: var(--fui-bg-primary, $fui-bg-primary);
-  border: var(--fui-stroke-hairline, 1px) solid var(--fui-field-selection-border, $fui-color-accent);
+  border: var(--fui-stroke-hairline, 1px) solid var(--fui-color-accent, $fui-color-accent);
   border-radius: var(--fui-radius-full, $fui-radius-full);
   box-shadow: var(--fui-shadow-sm, $fui-shadow-sm);
   cursor: grab;
@@ -89,13 +90,14 @@
   }
 
   &[data-disabled] {
-    cursor: not-allowed;
-    opacity: 0.5;
+    @include disabled-state;
   }
 
   @media (pointer: coarse) {
     --_fui-target-hit-size: #{target.hit-size("touch")};
   }
+
+  @include high-contrast-outline;
 }
 
 .helper {
@@ -127,21 +129,6 @@
     var(--fui-color-danger-text, $fui-color-danger-text);
 }
 
-// ============================================
-// Accessibility: High Contrast Mode
-// ============================================
-
-@media (prefers-contrast: more) {
-  .track {
-    border: var(--fui-stroke-hairline, 1px) solid var(--fui-text-primary, $fui-text-primary);
-  }
-
-  .thumb {
-    outline: var(--fui-stroke-default, 2px) solid var(--fui-text-primary, $fui-text-primary);
-    outline-offset: var(--fui-stroke-hairline, 1px);
-  }
-}
-
 // ============================================
 // Accessibility: Reduced Motion
 // ============================================