@usefragments/ui 1.0.0

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

@@ -0,0 +1,166 @@
+{
+  "$schema": "https://usefragments.com/schemas/contract.v1.json",
+  "name": "Skeleton",
+  "description": "Placeholder loading state for content",
+  "category": "feedback",
+  "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)",
+    "size: sm|md|lg (default: md)",
+    "width: union",
+    "height: union",
+    "fill: boolean (default: false)",
+    "radius: sm|md|lg|none|full",
+    "static: boolean (default: false)"
+  ],
+  "props": {
+    "variant": {
+      "type": "enum",
+      "description": "Semantic variant that auto-sizes",
+      "default": "rect",
+      "required": false,
+      "values": [
+        "text",
+        "heading",
+        "avatar",
+        "button",
+        "input",
+        "rect"
+      ]
+    },
+    "size": {
+      "type": "enum",
+      "description": "Size for avatar/button variants",
+      "default": "md",
+      "required": false,
+      "values": [
+        "sm",
+        "md",
+        "lg"
+      ]
+    },
+    "width": {
+      "type": "union",
+      "description": "Custom width (string or number)",
+      "required": false
+    },
+    "height": {
+      "type": "union",
+      "description": "Custom height (string or number)",
+      "required": false
+    },
+    "fill": {
+      "type": "boolean",
+      "description": "Fill parent container",
+      "default": "false",
+      "required": false
+    },
+    "radius": {
+      "type": "enum",
+      "description": "Border radius override",
+      "required": false,
+      "values": [
+        "sm",
+        "md",
+        "lg",
+        "none",
+        "full"
+      ]
+    },
+    "static": {
+      "type": "boolean",
+      "description": "Disable skeleton animation",
+      "default": "false",
+      "required": false
+    }
+  },
+  "usage": {
+    "when": [
+      "Content is loading asynchronously",
+      "Preventing layout shift during data fetching",
+      "Providing visual feedback that content is coming",
+      "Improving perceived performance"
+    ],
+    "whenNot": [
+      "Short loading times (< 300ms)",
+      "When spinner is more appropriate",
+      "Background operations without visible impact"
+    ],
+    "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)"
+    ],
+    "accessibility": [
+      "Skeletons are decorative - use aria-hidden",
+      "Announce loading state separately if needed",
+      "Ensure sufficient contrast for the animation"
+    ]
+  },
+  "examples": [
+    {
+      "name": "Default",
+      "description": "Basic rectangle skeleton",
+      "code": "<Skeleton width={200} height={20} />"
+    },
+    {
+      "name": "Text Lines",
+      "description": "Multi-line text placeholder",
+      "code": "<Skeleton.Text lines={3} />"
+    },
+    {
+      "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": "Avatar Skeleton",
+      "description": "Circular placeholder for avatars",
+      "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>"
+    }
+  ],
+  "relations": [
+    {
+      "component": "Progress",
+      "relationship": "alternative",
+      "note": "Use Progress for determinate loading"
+    }
+  ],
+  "contract": {
+    "propsSummary": [
+      "variant: text|heading|avatar|button|input|rect",
+      "size: sm|md|lg (for avatar/button)",
+      "width/height: custom dimensions",
+      "fill: boolean - fill parent",
+      "Skeleton / Skeleton.Text forward div DOM props"
+    ]
+  },
+  "ai": {
+    "compositionPattern": "compound",
+    "subComponents": [
+      "Text",
+      "Circle"
+    ]
+  },
+  "provenance": {
+    "source": "migrated",
+    "verified": false,
+    "frameworkSupport": "native",
+    "extractedAt": "2026-03-13T23:19:03.952Z"
+  }
+}

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

@@ -0,0 +1,166 @@
+@use '../../tokens/variables' as *;
+
+// ============================================
+// Skeleton Component Styles
+// ============================================
+
+// Animation
+@keyframes skeleton-pulse {
+  0%, 100% {
+    opacity: 1;
+  }
+  50% {
+    opacity: 0.5;
+  }
+}
+
+// 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;
+  border-radius: var(--fui-radius-md, #{$fui-radius-md});
+}
+
+// Static (no animation)
+.static {
+  animation: none;
+}
+
+// Fill parent
+.fill {
+  width: 100%;
+  height: 100%;
+}
+
+// ============================================
+// Semantic Variants
+// ============================================
+
+// Text - single line of body text
+.text {
+  height: 1em;
+  width: 100%;
+  border-radius: var(--fui-radius-sm, #{$fui-radius-sm});
+}
+
+// Heading - taller for headings
+.heading {
+  height: 1.5em;
+  width: 100%;
+  border-radius: var(--fui-radius-sm, #{$fui-radius-sm});
+}
+
+// Avatar - circular profile placeholder
+.avatar {
+  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});
+}
+
+// Button - matches button heights
+.button {
+  border-radius: var(--fui-radius-md, #{$fui-radius-md});
+}
+
+.button-sm {
+  height: var(--fui-button-height-sm, #{$fui-button-height-sm});
+  width: 5rem;  // 70px default width
+}
+
+.button-md {
+  height: var(--fui-button-height-md, #{$fui-button-height-md});
+  width: 6rem;  // 84px default width
+}
+
+.button-lg {
+  height: var(--fui-button-height-lg, #{$fui-button-height-lg});
+  width: 7rem;  // 98px default width
+}
+
+// Input - matches input field height
+.input {
+  height: var(--fui-input-height, #{$fui-input-height});
+  width: 100%;
+  border-radius: var(--fui-radius-md, #{$fui-radius-md});
+}
+
+// Rect - generic rectangle (no preset dimensions)
+.rect {
+  // Uses explicit width/height from props or fill
+}
+
+// ============================================
+// Border Radius Overrides
+// ============================================
+
+.radius-none {
+  border-radius: 0;
+}
+
+.radius-sm {
+  border-radius: var(--fui-radius-sm, #{$fui-radius-sm});
+}
+
+.radius-md {
+  border-radius: var(--fui-radius-md, #{$fui-radius-md});
+}
+
+.radius-lg {
+  border-radius: var(--fui-radius-lg, #{$fui-radius-lg});
+}
+
+.radius-full {
+  border-radius: var(--fui-radius-full, #{$fui-radius-full});
+}
+
+// ============================================
+// Skeleton.Text - Multi-line text container
+// ============================================
+
+.textContainer {
+  display: flex;
+  flex-direction: column;
+  width: 100%;
+}
+
+.gap-sm {
+  gap: var(--fui-space-2, #{$fui-space-2}); // 14px
+}
+
+.gap-md {
+  gap: var(--fui-space-3, #{$fui-space-3}); // 21px
+}
+
+.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;
+  border-radius: var(--fui-radius-sm, #{$fui-radius-sm});
+}
+
+// ============================================
+// Accessibility: Reduced Motion
+// ============================================
+
+@media (prefers-reduced-motion: reduce) {
+  .skeleton,
+  .textLine {
+    animation: none;
+  }
+}

package/src/components/Skeleton/Skeleton.stories.tsx

@@ -0,0 +1,80 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Skeleton } from '.';
+
+/**
+ * Skeleton is a placeholder loading state for content. Semantic variants
+ * auto-size to common shapes, while width/height allow custom dimensions.
+ * Includes Skeleton.Text and Skeleton.Circle subcomponents.
+ */
+const meta = {
+  title: 'Feedback/Skeleton',
+  component: Skeleton,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component: 'Placeholder loading state for content.',
+      },
+    },
+  },
+  argTypes: {
+    variant: {
+      control: 'select',
+      options: ['text', 'heading', 'avatar', 'button', 'input', 'rect'],
+      description: 'Semantic variant that auto-sizes',
+    },
+    size: {
+      control: 'select',
+      options: ['sm', 'md', 'lg'],
+      description: 'Size for avatar/button variants',
+    },
+    radius: {
+      control: 'select',
+      options: ['sm', 'md', 'lg', 'none', 'full'],
+      description: 'Border radius override',
+    },
+    fill: { control: 'boolean', description: 'Fill parent container' },
+    static: { control: 'boolean', description: 'Disable skeleton animation' },
+  },
+  args: { variant: 'rect', width: 200, height: 20 },
+} satisfies Meta<typeof Skeleton>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: { variant: 'rect', width: 200, height: 20 },
+};
+
+export const Heading: Story = {
+  args: { variant: 'heading', width: 200 },
+};
+
+export const TextLines: Story = {
+  render: () => <Skeleton.Text lines={3} />,
+};
+
+export const Avatars: Story = {
+  render: () => (
+    <div style={{ display: 'flex', gap: 'var(--fui-space-1)', alignItems: 'center' }}>
+      <Skeleton.Circle size="sm" />
+      <Skeleton.Circle size="md" />
+      <Skeleton.Circle size="lg" />
+    </div>
+  ),
+};
+
+export const Card: Story = {
+  render: () => (
+    <div style={{ width: 300 }}>
+      <Skeleton variant="rect" height={120} radius="md" />
+      <div style={{ marginTop: 'var(--fui-space-2)' }}>
+        <Skeleton variant="heading" width="60%" />
+      </div>
+      <div style={{ marginTop: 'var(--fui-space-1)' }}>
+        <Skeleton.Text lines={2} />
+      </div>
+    </div>
+  ),
+};

package/src/components/Skeleton/index.tsx

@@ -0,0 +1,182 @@
+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
+
+export type SkeletonSize = 'sm' | 'md' | 'lg';
+
+export interface SkeletonProps extends React.HTMLAttributes<HTMLDivElement> {
+  /**
+   * Semantic variant that auto-sizes based on design tokens.
+   * @default 'rect'
+   */
+  variant?: SkeletonVariant;
+  /**
+   * Size variant for avatar/button. Ignored for text/heading/input.
+   * @default 'md'
+   */
+  size?: SkeletonSize;
+  /**
+   * Width in pixels or CSS value. Auto-determined for most variants.
+   */
+  width?: number | string;
+  /**
+   * Height in pixels or CSS value. Auto-determined for semantic variants.
+   */
+  height?: number | string;
+  /**
+   * Fill parent container (100% width and height).
+   * Useful when parent has explicit dimensions.
+   */
+  fill?: boolean;
+  /**
+   * Border radius override. Auto-determined for most variants.
+   */
+  radius?: 'none' | 'sm' | 'md' | 'lg' | 'full';
+  /**
+   * Disable animation for reduced motion preference.
+   * @default false
+   */
+  static?: boolean;
+}
+
+export interface SkeletonTextProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'children'> {
+  /** Number of text lines to render */
+  lines?: number;
+  /**
+   * Width of last line as percentage.
+   * Creates natural paragraph appearance.
+   * @default 80
+   */
+  lastLineWidth?: number;
+  /** Gap between lines. Uses spacing tokens. */
+  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;
+    }
+
+    return (
+      <div
+        ref={ref}
+        {...htmlProps}
+        className={classes}
+        style={Object.keys(style).length > 0 ? style : undefined}
+        aria-hidden="true"
+      />
+    );
+  }
+);
+
+// ============================================
+// Skeleton.Text - Multi-line text skeleton
+// ============================================
+
+function SkeletonText({
+  lines = 3,
+  lastLineWidth = 80,
+  gap = 'sm',
+  className,
+  ...htmlProps
+}: SkeletonTextProps) {
+  const containerClasses = [
+    styles.textContainer,
+    styles[`gap-${gap}`],
+    className,
+  ].filter(Boolean).join(' ');
+
+  return (
+    <div {...htmlProps} className={containerClasses} aria-hidden="true">
+      {Array.from({ length: lines }, (_, lineIdx) => {
+        const isLast = lineIdx === lines - 1;
+        return (
+          <div
+            key={`line-${lineIdx}`}
+            className={styles.textLine}
+            style={isLast && lines > 1 ? { width: `${lastLineWidth}%` } : undefined}
+          />
+        );
+      })}
+    </div>
+  );
+}
+
+// ============================================
+// Skeleton.Circle - Shorthand for avatar variant
+// ============================================
+
+function SkeletonCircle({
+  size = 'md',
+  className,
+}: {
+  size?: SkeletonSize | number;
+  className?: string;
+}) {
+  if (typeof size === 'number') {
+    return (
+      <SkeletonBase
+        variant="rect"
+        width={size}
+        height={size}
+        radius="full"
+        className={className}
+      />
+    );
+  }
+  return <SkeletonBase variant="avatar" size={size} className={className} />;
+}
+
+// ============================================
+// Compound Component
+// ============================================
+
+export const Skeleton = Object.assign(SkeletonBase, {
+  Text: SkeletonText,
+  Circle: SkeletonCircle,
+});