@usefragments/ui 1.0.0

package/src/components/Avatar/Avatar.module.scss

@@ -0,0 +1,136 @@
+@use '../../tokens/variables' as *;
+
+// ============================================
+// Avatar Component Styles
+// ============================================
+
+.avatar {
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  overflow: hidden;
+  border-radius: var(--fui-radius-full, $fui-radius-full);
+  background-color: var(--fui-bg-tertiary, $fui-bg-tertiary);
+  color: var(--fui-text-secondary, $fui-text-secondary);
+  font-family: var(--fui-font-sans, $fui-font-sans);
+  user-select: none;
+}
+
+// Shape variant
+.square {
+  border-radius: var(--fui-radius-md, $fui-radius-md);
+}
+
+// ============================================
+// Size Variants
+// ============================================
+
+.xs {
+  width: 1.5rem;   // 24px
+  height: 1.5rem;
+  font-size: var(--fui-font-size-2xs, $fui-font-size-2xs);
+}
+
+.sm {
+  width: 2rem;     // 32px
+  height: 2rem;
+  font-size: var(--fui-font-size-xs, $fui-font-size-xs);
+}
+
+.md {
+  width: 2.5rem;   // 40px
+  height: 2.5rem;
+  font-size: var(--fui-font-size-sm, $fui-font-size-sm);
+}
+
+.lg {
+  width: 3rem;     // 48px
+  height: 3rem;
+  font-size: var(--fui-font-size-base, $fui-font-size-base);
+}
+
+.xl {
+  width: 4rem;     // 64px
+  height: 4rem;
+  font-size: var(--fui-font-size-lg, $fui-font-size-lg);
+}
+
+// ============================================
+// Image
+// ============================================
+
+.image {
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+}
+
+// ============================================
+// Initials / Fallback
+// ============================================
+
+.initials {
+  font-weight: var(--fui-font-weight-medium, $fui-font-weight-medium);
+  color: var(--avatar-initials-color, var(--fui-text-inverse, $fui-text-inverse));
+  text-transform: uppercase;
+  line-height: 1;
+}
+
+.fallbackIcon {
+  width: 60%;
+  height: 60%;
+  color: var(--fui-text-tertiary, $fui-text-tertiary);
+}
+
+// ============================================
+// Avatar Group
+// ============================================
+
+.group {
+  display: inline-flex;
+  flex-direction: row-reverse;
+  justify-content: flex-end;
+}
+
+.groupItem {
+  margin-left: -0.5rem;
+  border: 2px solid var(--fui-bg-primary, $fui-bg-primary);
+
+  &:last-child {
+    margin-left: 0;
+  }
+}
+
+// Adjust overlap for different sizes
+.group .xs.groupItem {
+  margin-left: -0.375rem;
+}
+
+.group .sm.groupItem {
+  margin-left: -0.5rem;
+}
+
+.group .md.groupItem {
+  margin-left: -0.625rem;
+}
+
+.group .lg.groupItem {
+  margin-left: -0.75rem;
+}
+
+.group .xl.groupItem {
+  margin-left: -1rem;
+}
+
+// Overflow count indicator
+.overflow {
+  margin-left: -0.625rem;
+  background-color: var(--fui-bg-tertiary, $fui-bg-tertiary);
+  border: 2px solid var(--fui-bg-primary, $fui-bg-primary);
+
+  .initials {
+    color: var(--fui-text-secondary, $fui-text-secondary);
+  }
+}

package/src/components/Avatar/Avatar.stories.tsx

@@ -0,0 +1,74 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Avatar } from '.';
+
+/**
+ * Avatar is the visual representation of a user or entity. It renders an image
+ * when available and falls back to initials or a placeholder icon. Use
+ * Avatar.Group to stack multiple avatars in a row.
+ */
+const meta = {
+  title: 'Display/Avatar',
+  component: Avatar,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: { component: 'Visual representation of a user or entity.' },
+    },
+  },
+  argTypes: {
+    size: {
+      control: 'select',
+      options: ['xs', 'sm', 'md', 'lg', 'xl'],
+      description: 'Size variant',
+    },
+    shape: {
+      control: 'select',
+      options: ['circle', 'square'],
+      description: 'Shape variant',
+    },
+    src: { control: 'text', description: 'Image source URL' },
+    name: { control: 'text', description: 'Full name - used to generate initials' },
+    initials: { control: 'text', description: 'Fallback initials (1-2 characters)' },
+  },
+  args: {
+    name: 'Jane Doe',
+    size: 'md',
+    shape: 'circle',
+  },
+} satisfies Meta<typeof Avatar>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const WithImage: Story = {
+  args: {
+    src: 'https://i.pravatar.cc/150?u=jane',
+    alt: 'Jane Doe',
+    name: 'Jane Doe',
+  },
+};
+
+export const WithInitials: Story = {
+  args: { name: 'John Smith' },
+};
+
+export const Large: Story = {
+  args: { name: 'Conan McNicholl', size: 'xl' },
+};
+
+export const Square: Story = {
+  args: { name: 'App', shape: 'square' },
+};
+
+export const Group: Story = {
+  render: () => (
+    <Avatar.Group max={3} size="md">
+      <Avatar name="Alice Johnson" />
+      <Avatar name="Bob Smith" />
+      <Avatar name="Carol Williams" />
+      <Avatar name="David Brown" />
+      <Avatar name="Eve Davis" />
+    </Avatar.Group>
+  ),
+};

package/src/components/Avatar/index.tsx

@@ -0,0 +1,311 @@
+'use client';
+
+import * as React from 'react';
+import styles from './Avatar.module.scss';
+
+// ============================================
+// Types
+// ============================================
+
+export type AvatarSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+
+/**
+ * Avatar for user photos, initials, or placeholder icons.
+ * @see https://usefragments.com/components/avatar
+ */
+export interface AvatarProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'color'> {
+  /** Image source URL */
+  src?: string;
+  /** Alt text for the image */
+  alt?: string;
+  /** Fallback initials (1-2 characters recommended) */
+  initials?: string;
+  /** Full name - used to generate initials if not provided */
+  name?: string;
+  /** Size variant */
+  size?: AvatarSize;
+  /** Custom avatar size (overrides size width/height) */
+  customSize?: number | string;
+  /** Shape variant */
+  shape?: 'circle' | 'square';
+  /** Custom background color for fallback */
+  color?: string;
+  /** Inline style for the underlying image element */
+  imageStyle?: React.CSSProperties;
+  /** Additional props for the underlying img element */
+  imageProps?: Omit<
+    React.ImgHTMLAttributes<HTMLImageElement>,
+    'src' | 'alt' | 'className' | 'style'
+  >;
+}
+
+export interface AvatarGroupProps extends React.HTMLAttributes<HTMLDivElement> {
+  /** Maximum number of avatars to display */
+  max?: number;
+  /** Size for all avatars in the group */
+  size?: AvatarSize;
+  /** Children (Avatar components) */
+  children: React.ReactNode;
+}
+
+// ============================================
+// Helper Functions
+// ============================================
+
+function getInitials(name: string): string {
+  const parts = name.trim().split(/\s+/);
+  if (parts.length === 1) {
+    return parts[0].charAt(0).toUpperCase();
+  }
+  return (parts[0].charAt(0) + parts[parts.length - 1].charAt(0)).toUpperCase();
+}
+
+// Generated identicon backgrounds keep a fixed hue per name but vary lightness
+// by theme: deeper in light mode, lighter in dark mode so the fallback never
+// reads as a fixed mid-tone against the surrounding surface.
+const FALLBACK_SATURATION_LIGHT = 55;
+const FALLBACK_LIGHTNESS_LIGHT = 42;
+const FALLBACK_SATURATION_DARK = 50;
+const FALLBACK_LIGHTNESS_DARK = 62;
+
+function hashString(str: string): number {
+  let hash = 0;
+  for (let i = 0; i < str.length; i++) {
+    hash = str.charCodeAt(i) + ((hash << 5) - hash);
+  }
+  return Math.abs(hash % 360);
+}
+
+function stringToColor(str: string): string {
+  // Generate a consistent hue from a string, theme-aware lightness via
+  // light-dark() so it isn't a fixed mid-tone in dark mode.
+  const hue = hashString(str);
+  return (
+    `light-dark(` +
+    `hsl(${hue} ${FALLBACK_SATURATION_LIGHT}% ${FALLBACK_LIGHTNESS_LIGHT}%), ` +
+    `hsl(${hue} ${FALLBACK_SATURATION_DARK}% ${FALLBACK_LIGHTNESS_DARK}%))`
+  );
+}
+
+/**
+ * Compute a contrast-safe text color (white or black) for an HSL background.
+ * Uses WCAG relative luminance to pick whichever gives higher contrast.
+ */
+function contrastForHsl(h: number, s: number, l: number): string {
+  // HSL → RGB
+  const c = (1 - Math.abs(2 * l - 1)) * s;
+  const x = c * (1 - Math.abs((h / 60) % 2 - 1));
+  const m = l - c / 2;
+  let r = 0, g = 0, b = 0;
+  if (h < 60) { r = c; g = x; }
+  else if (h < 120) { r = x; g = c; }
+  else if (h < 180) { g = c; b = x; }
+  else if (h < 240) { g = x; b = c; }
+  else if (h < 300) { r = x; b = c; }
+  else { r = c; b = x; }
+  r += m; g += m; b += m;
+
+  // Relative luminance (sRGB → linear)
+  const lin = (v: number) => v <= 0.03928 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4);
+  const lum = 0.2126 * lin(r) + 0.7152 * lin(g) + 0.0722 * lin(b);
+
+  return lum > 0.179 ? '#000000' : '#ffffff';
+}
+
+/**
+ * Compute a contrast-safe initials color for a generated fallback background.
+ * The background uses theme-aware lightness via light-dark(), so the text color
+ * is computed for each mode and returned as a matching light-dark() value.
+ * Custom (non-generated) colors fall back to the single-color path.
+ */
+function getContrastTextColor(bgColor: string): string | undefined {
+  // Generated identicon background: light-dark(hsl(...), hsl(...))
+  const ld = bgColor.match(
+    /light-dark\(\s*hsl\((\d+)\s+(\d+)%\s+(\d+)%\)\s*,\s*hsl\((\d+)\s+(\d+)%\s+(\d+)%\)\s*\)/
+  );
+  if (ld) {
+    const lightText = contrastForHsl(
+      parseInt(ld[1]),
+      parseInt(ld[2]) / 100,
+      parseInt(ld[3]) / 100
+    );
+    const darkText = contrastForHsl(
+      parseInt(ld[4]),
+      parseInt(ld[5]) / 100,
+      parseInt(ld[6]) / 100
+    );
+    return lightText === darkText
+      ? lightText
+      : `light-dark(${lightText}, ${darkText})`;
+  }
+
+  // Legacy / custom single HSL color
+  const match = bgColor.match(/hsl\((\d+),\s*(\d+)%,\s*(\d+)%\)/);
+  if (!match) return undefined;
+  return contrastForHsl(
+    parseInt(match[1]),
+    parseInt(match[2]) / 100,
+    parseInt(match[3]) / 100
+  );
+}
+
+// ============================================
+// Avatar Component
+// ============================================
+
+const AvatarBase = React.forwardRef<HTMLDivElement, AvatarProps>(
+  function AvatarBase(
+    {
+      src,
+      alt = '',
+      initials,
+      name,
+      size = 'md',
+      customSize,
+      shape = 'circle',
+      color,
+      imageStyle,
+      imageProps,
+      className,
+      style: styleProp,
+      ...htmlProps
+    },
+    ref
+  ) {
+    const imgRef = React.useRef<HTMLImageElement>(null);
+    const [imageError, setImageError] = React.useState(false);
+
+    // Reset error state when src changes; check if already-loaded image failed
+    React.useEffect(() => {
+      setImageError(false);
+      const img = imgRef.current;
+      if (img && img.complete && img.naturalWidth === 0) {
+        setImageError(true);
+      }
+    }, [src]);
+
+    const showFallback = !src || imageError;
+    const displayInitials = initials || (name ? getInitials(name) : '');
+    const fallbackColor = color || (name ? stringToColor(name) : undefined);
+    const fallbackLabel = alt || name;
+    const hasFallbackLabel = showFallback && Boolean(fallbackLabel && fallbackLabel.trim().length > 0);
+
+    const avatarClasses = [
+      styles.avatar,
+      styles[size],
+      shape === 'square' && styles.square,
+      className,
+    ].filter(Boolean).join(' ');
+
+    const style: React.CSSProperties = { ...styleProp };
+    if (customSize !== undefined) {
+      const resolvedSize = typeof customSize === 'number' ? `${customSize}px` : customSize;
+      style.width = resolvedSize;
+      style.height = resolvedSize;
+      if (style.fontSize === undefined) {
+        style.fontSize = `calc(${resolvedSize} * 0.4)`;
+      }
+    }
+
+    if (showFallback && fallbackColor) {
+      style.backgroundColor = fallbackColor;
+      const textColor = getContrastTextColor(fallbackColor);
+      if (textColor) {
+        (style as Record<string, string>)['--avatar-initials-color'] = textColor;
+      }
+    }
+
+    return (
+      <div
+        ref={ref}
+        {...htmlProps}
+        className={avatarClasses}
+        style={style}
+        role={hasFallbackLabel ? 'img' : undefined}
+        aria-label={hasFallbackLabel ? fallbackLabel : undefined}
+        aria-hidden={showFallback && !hasFallbackLabel ? true : undefined}
+      >
+        {!showFallback && (
+          <img
+            ref={imgRef}
+            {...imageProps}
+            src={src}
+            alt={alt}
+            className={styles.image}
+            onError={(event) => {
+              imageProps?.onError?.(event);
+              if (!event.defaultPrevented) {
+                setImageError(true);
+              }
+            }}
+            style={{ ...imageStyle }}
+          />
+        )}
+        {showFallback && displayInitials && (
+          <span className={styles.initials}>{displayInitials}</span>
+        )}
+        {showFallback && !displayInitials && (
+          <svg
+            className={styles.fallbackIcon}
+            xmlns="http://www.w3.org/2000/svg"
+            viewBox="0 0 24 24"
+            fill="currentColor"
+            aria-hidden="true"
+          >
+            <path d="M12 12c2.21 0 4-1.79 4-4s-1.79-4-4-4-4 1.79-4 4 1.79 4 4 4zm0 2c-2.67 0-8 1.34-8 4v2h16v-2c0-2.66-5.33-4-8-4z" />
+          </svg>
+        )}
+      </div>
+    );
+  }
+);
+
+// ============================================
+// Avatar Group Component
+// ============================================
+
+function AvatarGroup({
+  max,
+  size = 'md',
+  children,
+  className,
+  ...htmlProps
+}: AvatarGroupProps) {
+  const childArray = React.Children.toArray(children);
+  const displayCount = max && max < childArray.length ? max : childArray.length;
+  const overflowCount = max && childArray.length > max ? childArray.length - max : 0;
+
+  const groupClasses = [styles.group, className].filter(Boolean).join(' ');
+
+  return (
+    <div {...htmlProps} className={groupClasses}>
+      {childArray.slice(0, displayCount).map((child, index) => {
+        if (React.isValidElement<AvatarProps>(child)) {
+          return React.cloneElement(child, {
+            key: index,
+            size: child.props.size || size,
+            className: [styles.groupItem, child.props.className].filter(Boolean).join(' '),
+          });
+        }
+        return child;
+      })}
+      {overflowCount > 0 && (
+        <div
+          className={[styles.avatar, styles[size], styles.overflow].join(' ')}
+          role="img"
+          aria-label={`${overflowCount} more ${overflowCount === 1 ? 'person' : 'people'}`}
+        >
+          <span className={styles.initials} aria-hidden="true">+{overflowCount}</span>
+        </div>
+      )}
+    </div>
+  );
+}
+
+// ============================================
+// Compound Component Export
+// ============================================
+
+export const Avatar = Object.assign(AvatarBase, {
+  Group: AvatarGroup,
+});

package/src/components/Badge/Badge.contract.json

@@ -0,0 +1,170 @@
+{
+  "$schema": "https://usefragments.com/schemas/contract.v1.json",
+  "name": "Badge",
+  "description": "Compact label for status, counts, or categorization. Draws attention to metadata without dominating the layout.",
+  "category": "display",
+  "tags": ["status", "label", "tag", "count", "chip"],
+  "status": "stable",
+  "sourcePath": "src/components/Badge/index.tsx",
+  "exportName": "Badge",
+  "propsSummary": [
+    "children: node (required)",
+    "variant: default|success|warning|error|info|outline (default: default)",
+    "size: sm|md|lg (default: md)",
+    "dot: boolean (default: false)",
+    "icon: node",
+    "onRemove: function",
+    "announce: boolean (default: false)",
+    "role: union"
+  ],
+  "props": {
+    "children": {
+      "type": "node",
+      "description": "Badge label text",
+      "required": true
+    },
+    "variant": {
+      "type": "enum",
+      "description": "Visual style indicating severity or category",
+      "default": "default",
+      "required": false,
+      "values": ["default", "success", "warning", "error", "info", "outline"]
+    },
+    "size": {
+      "type": "enum",
+      "description": "Badge size",
+      "default": "md",
+      "required": false,
+      "values": ["sm", "md", "lg"]
+    },
+    "dot": {
+      "type": "boolean",
+      "description": "Show a colored dot indicator before the label",
+      "default": "false",
+      "required": false
+    },
+    "icon": {
+      "type": "node",
+      "description": "Optional icon element before the text",
+      "required": false
+    },
+    "onRemove": {
+      "type": "function",
+      "description": "Makes the badge removable. Called when X is clicked.",
+      "required": false
+    },
+    "announce": {
+      "type": "boolean",
+      "description": "Opt into role=\"status\" live announcement semantics",
+      "default": "false",
+      "required": false
+    },
+    "role": {
+      "type": "union",
+      "description": "",
+      "required": false
+    }
+  },
+  "usage": {
+    "when": [
+      "Showing item status (active, pending, archived)",
+      "Displaying counts or quantities inline",
+      "Categorizing or tagging content",
+      "Highlighting new or updated items"
+    ],
+    "whenNot": [
+      "Conveying critical errors (use Alert instead)",
+      "Long-form status messages (use Alert)",
+      "Interactive filtering (use Chip/ToggleGroup)",
+      "Navigation labels (use Tabs or links)"
+    ],
+    "guidelines": [
+      "Keep badge text under 20 characters",
+      "Use dot variant for live status indicators",
+      "Pair success/error variants with meaningful labels, not just colors",
+      "Semantic status badges are borderless pills using shared semantic bg/text tokens",
+      "Use onRemove for user-created tags only, not system-generated badges",
+      "Badges are not announced as live status updates by default; use announce for screen-reader status announcements when appropriate"
+    ],
+    "accessibility": [
+      "Badge text must be meaningful without relying on color alone",
+      "Removable badges must have accessible dismiss button labels",
+      "Avoid using badges as the sole indicator of important state changes"
+    ]
+  },
+  "examples": [
+    {
+      "name": "Default",
+      "description": "Neutral badge for general labels",
+      "code": "import { Badge } from '@/components/Badge';\n\n<Badge>Default</Badge>"
+    },
+    {
+      "name": "Status Variants",
+      "description": "All severity variants for different contexts",
+      "code": "import { Badge } from '@/components/Badge';\nimport { Stack } from '@/components/Stack';\n\n<Stack direction=\"row\" gap=\"sm\" wrap>\n  <Badge variant=\"default\">Default</Badge>\n  <Badge variant=\"success\">Active</Badge>\n  <Badge variant=\"warning\">Pending</Badge>\n  <Badge variant=\"error\">Failed</Badge>\n  <Badge variant=\"info\">New</Badge>\n</Stack>"
+    },
+    {
+      "name": "Delivery Status",
+      "description": "Reference status pills with deep semantic fill and bright text",
+      "code": "import { Badge } from '@/components/Badge';\nimport { Stack } from '@/components/Stack';\n\n<Stack direction=\"row\" gap=\"sm\" wrap>\n  <Badge variant=\"success\" size=\"lg\">Delivered</Badge>\n  <Badge variant=\"error\" size=\"lg\">Bounced</Badge>\n</Stack>"
+    },
+    {
+      "name": "With Dot",
+      "description": "Live status indicators using dot prefix",
+      "code": "import { Badge } from '@/components/Badge';\nimport { Stack } from '@/components/Stack';\n\n<Stack direction=\"row\" gap=\"sm\" wrap>\n  <Badge variant=\"success\" dot>Online</Badge>\n  <Badge variant=\"warning\" dot>Away</Badge>\n  <Badge variant=\"error\" dot>Offline</Badge>\n</Stack>"
+    },
+    {
+      "name": "Announced Status",
+      "description": "Opt into screen-reader status announcement behavior",
+      "code": "import { Badge } from '@/components/Badge';\n\n<Badge variant=\"success\" announce>Saved</Badge>"
+    },
+    {
+      "name": "Outline",
+      "description": "Minimal bordered badge for neutral emphasis",
+      "code": "import { Badge } from '@/components/Badge';\n\n<Badge variant=\"outline\">Outline</Badge>"
+    },
+    {
+      "name": "Small Size",
+      "description": "Compact badges for dense UIs",
+      "code": "import { Badge } from '@/components/Badge';\nimport { Stack } from '@/components/Stack';\n\n<Stack direction=\"row\" gap=\"sm\" align=\"center\" wrap>\n  <Badge size=\"sm\" variant=\"info\">v2.1</Badge>\n  <Badge size=\"sm\" variant=\"success\">Stable</Badge>\n  <Badge size=\"md\" variant=\"info\">Standard</Badge>\n</Stack>"
+    },
+    {
+      "name": "Removable",
+      "description": "User-created tags that can be dismissed",
+      "code": "import { Badge } from '@/components/Badge';\nimport { Stack } from '@/components/Stack';\n\n<Stack direction=\"row\" gap=\"sm\" wrap>\n  <Badge variant=\"info\" onRemove={() => {}}>React</Badge>\n  <Badge variant=\"info\" onRemove={() => {}}>TypeScript</Badge>\n  <Badge variant=\"info\" onRemove={() => {}}>CSS</Badge>\n</Stack>"
+    }
+  ],
+  "relations": [
+    {
+      "component": "Alert",
+      "relationship": "alternative",
+      "note": "Use Alert for prominent, longer messages with actions"
+    },
+    {
+      "component": "Chip",
+      "relationship": "sibling",
+      "note": "Chip is interactive (clickable/filterable); Badge is display-only"
+    }
+  ],
+  "contract": {
+    "propsSummary": [
+      "children: ReactNode - badge label (required)",
+      "variant: default|success|warning|error|info|outline - visual style",
+      "size: sm|md - badge size",
+      "dot: boolean - show status dot indicator",
+      "onRemove: () => void - makes badge removable",
+      "announce: boolean - opt into role=\"status\" + auto status aria-label"
+    ],
+    "a11yRules": ["A11Y_BADGE_CONTRAST", "A11Y_BADGE_DISMISS", "A11Y_TARGET_SIZE_MIN"]
+  },
+  "ai": {
+    "compositionPattern": "compound",
+    "subComponents": ["Root"]
+  },
+  "provenance": {
+    "source": "migrated",
+    "verified": false,
+    "frameworkSupport": "native",
+    "extractedAt": "2026-03-13T23:18:50.941Z"
+  }
+}