@fragments-sdk/ui 0.1.0

package/src/components/Separator/Separator.fragment.tsx

@@ -0,0 +1,148 @@
+import React from 'react';
+import { defineSegment } from '@fragments/core';
+import { Separator } from './index.js';
+
+export default defineSegment({
+  component: Separator,
+
+  meta: {
+    name: 'Separator',
+    description: 'Visual divider between content sections. Use to create clear visual boundaries and improve content organization.',
+    category: 'layout',
+    status: 'stable',
+    tags: ['separator', 'divider', 'hr', 'line', 'layout'],
+    since: '0.1.0',
+  },
+
+  usage: {
+    when: [
+      'Dividing content sections',
+      'Separating groups of related items',
+      'Creating visual breathing room',
+      'Labeled section breaks',
+    ],
+    whenNot: [
+      'Creating grid layouts (use CSS Grid)',
+      'Decorative borders (use CSS)',
+      'Spacing alone is sufficient',
+    ],
+    guidelines: [
+      'Use sparingly - too many separators create visual noise',
+      'Consider if spacing alone would work',
+      'Use soft variant for subtle separation',
+      'Labeled separators work well for major section breaks',
+    ],
+    accessibility: [
+      'Uses role="separator" for semantic meaning',
+      'Decorative separators should be aria-hidden',
+    ],
+  },
+
+  props: {
+    orientation: {
+      type: 'enum',
+      description: 'Direction of the separator',
+      values: ['horizontal', 'vertical'],
+      default: 'horizontal',
+    },
+    spacing: {
+      type: 'enum',
+      description: 'Margin around the separator',
+      values: ['none', 'sm', 'md', 'lg'],
+      default: 'none',
+    },
+    soft: {
+      type: 'boolean',
+      description: 'Softer, lighter appearance',
+      default: 'false',
+    },
+    label: {
+      type: 'string',
+      description: 'Optional text label (horizontal only)',
+    },
+  },
+
+  relations: [
+    { component: 'Card', relationship: 'sibling', note: 'Cards provide stronger visual grouping' },
+  ],
+
+  contract: {
+    propsSummary: [
+      'orientation: horizontal|vertical - direction',
+      'spacing: none|sm|md|lg - margin',
+      'soft: boolean - lighter appearance',
+      'label: string - centered label text',
+    ],
+    scenarioTags: [
+      'layout.divider',
+      'layout.section',
+    ],
+    a11yRules: ['A11Y_SEPARATOR_ROLE'],
+  },
+
+  variants: [
+    {
+      name: 'Default',
+      description: 'Basic horizontal separator',
+      render: () => (
+        <div style={{ width: '300px' }}>
+          <p>Content above</p>
+          <Separator spacing="md" />
+          <p>Content below</p>
+        </div>
+      ),
+    },
+    {
+      name: 'With Label',
+      description: 'Labeled section divider',
+      render: () => (
+        <div style={{ width: '300px' }}>
+          <p>First section</p>
+          <Separator label="Or" spacing="md" />
+          <p>Second section</p>
+        </div>
+      ),
+    },
+    {
+      name: 'Soft',
+      description: 'Subtle separator',
+      render: () => (
+        <div style={{ width: '300px' }}>
+          <p>Content above</p>
+          <Separator soft spacing="md" />
+          <p>Content below</p>
+        </div>
+      ),
+    },
+    {
+      name: 'Vertical',
+      description: 'Vertical separator between elements',
+      render: () => (
+        <div style={{ display: 'flex', alignItems: 'center', gap: '16px', height: '40px' }}>
+          <span>Item 1</span>
+          <Separator orientation="vertical" />
+          <span>Item 2</span>
+          <Separator orientation="vertical" />
+          <span>Item 3</span>
+        </div>
+      ),
+    },
+    {
+      name: 'Spacing Options',
+      description: 'Different spacing sizes',
+      render: () => (
+        <div style={{ width: '300px' }}>
+          <p>No spacing</p>
+          <Separator spacing="none" />
+          <p>Small spacing</p>
+          <Separator spacing="sm" />
+          <p>Medium spacing</p>
+          <Separator spacing="md" />
+          <p>Large spacing</p>
+          <Separator spacing="lg" />
+          <p>End</p>
+        </div>
+      ),
+    },
+  ],
+});

package/src/components/Separator/Separator.module.scss

@@ -0,0 +1,92 @@
+@use '../../tokens/variables' as *;
+@use '../../tokens/mixins' as *;
+
+.separator {
+  flex-shrink: 0;
+  background-color: var(--fui-border, $fui-border);
+}
+
+// Horizontal (default)
+.horizontal {
+  width: 100%;
+  height: 1px;
+}
+
+// Vertical
+.vertical {
+  width: 1px;
+  height: auto;
+  align-self: stretch;
+}
+
+// With label
+.withLabel {
+  display: flex;
+  align-items: center;
+  gap: var(--fui-space-3, $fui-space-3);
+  background-color: transparent;
+
+  &::before,
+  &::after {
+    content: '';
+    flex: 1;
+    height: 1px;
+    background-color: var(--fui-border, $fui-border);
+  }
+}
+
+.label {
+  font-family: var(--fui-font-sans, $fui-font-sans);
+  font-size: var(--fui-font-size-xs, $fui-font-size-xs);
+  font-weight: var(--fui-font-weight-medium, $fui-font-weight-medium);
+  color: var(--fui-text-tertiary, $fui-text-tertiary);
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  white-space: nowrap;
+}
+
+// Spacing variants
+.spacingNone {
+  margin: 0;
+}
+
+.spacingSm {
+  &.horizontal {
+    margin: var(--fui-space-2, $fui-space-2) 0;
+  }
+
+  &.vertical {
+    margin: 0 var(--fui-space-2, $fui-space-2);
+  }
+}
+
+.spacingMd {
+  &.horizontal {
+    margin: var(--fui-space-4, $fui-space-4) 0;
+  }
+
+  &.vertical {
+    margin: 0 var(--fui-space-4, $fui-space-4);
+  }
+}
+
+.spacingLg {
+  &.horizontal {
+    margin: var(--fui-space-6, $fui-space-6) 0;
+  }
+
+  &.vertical {
+    margin: 0 var(--fui-space-6, $fui-space-6);
+  }
+}
+
+// Soft variant (lighter color)
+.soft {
+  background-color: var(--fui-border, $fui-border);
+  opacity: 0.5;
+
+  &.withLabel::before,
+  &.withLabel::after {
+    opacity: 0.5;
+  }
+}

package/src/components/Separator/index.tsx

@@ -0,0 +1,89 @@
+import * as React from 'react';
+import { Separator as BaseSeparator } from '@base-ui/react/separator';
+import styles from './Separator.module.scss';
+// Import globals to ensure CSS variables are defined
+import '../../styles/globals.scss';
+
+// ============================================
+// Types
+// ============================================
+
+export interface SeparatorProps {
+  /** Orientation of the separator */
+  orientation?: 'horizontal' | 'vertical';
+  /** Spacing around the separator */
+  spacing?: 'none' | 'sm' | 'md' | 'lg';
+  /** Softer visual appearance */
+  soft?: boolean;
+  /** Optional label text (creates a labeled divider) */
+  label?: string;
+  /** Additional class name */
+  className?: string;
+}
+
+// ============================================
+// Spacing class map
+// ============================================
+
+const spacingClasses = {
+  none: styles.spacingNone,
+  sm: styles.spacingSm,
+  md: styles.spacingMd,
+  lg: styles.spacingLg,
+};
+
+// ============================================
+// Component
+// ============================================
+
+export const Separator = React.forwardRef<HTMLDivElement, SeparatorProps>(
+  function Separator(
+    {
+      orientation = 'horizontal',
+      spacing = 'none',
+      soft = false,
+      label,
+      className,
+    },
+    ref
+  ) {
+    // Labeled separator (horizontal only)
+    if (label && orientation === 'horizontal') {
+      const classes = [
+        styles.separator,
+        styles.withLabel,
+        spacingClasses[spacing],
+        soft && styles.soft,
+        className,
+      ].filter(Boolean).join(' ');
+
+      return (
+        <div
+          ref={ref}
+          role="separator"
+          aria-orientation="horizontal"
+          className={classes}
+        >
+          <span className={styles.label}>{label}</span>
+        </div>
+      );
+    }
+
+    // Standard separator
+    const classes = [
+      styles.separator,
+      orientation === 'horizontal' ? styles.horizontal : styles.vertical,
+      spacingClasses[spacing],
+      soft && styles.soft,
+      className,
+    ].filter(Boolean).join(' ');
+
+    return (
+      <BaseSeparator
+        ref={ref}
+        orientation={orientation}
+        className={classes}
+      />
+    );
+  }
+);

package/src/components/Skeleton/Skeleton.fragment.tsx

@@ -0,0 +1,147 @@
+import React from 'react';
+import { defineSegment } from '@fragments/core';
+import { Skeleton } from './index.js';
+
+export default defineSegment({
+  component: Skeleton,
+
+  meta: {
+    name: 'Skeleton',
+    description: 'Placeholder loading state for content',
+    category: 'feedback',
+    status: 'stable',
+    tags: ['loading', 'placeholder', 'skeleton', 'shimmer'],
+  },
+
+  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',
+    ],
+    accessibility: [
+      'Skeletons are decorative - use aria-hidden',
+      'Announce loading state separately if needed',
+      'Ensure sufficient contrast for the animation',
+    ],
+  },
+
+  props: {
+    variant: {
+      type: 'enum',
+      values: ['text', 'heading', 'avatar', 'button', 'input', 'rect'],
+      default: 'rect',
+      description: 'Semantic variant that auto-sizes',
+    },
+    size: {
+      type: 'enum',
+      values: ['sm', 'md', 'lg'],
+      default: 'md',
+      description: 'Size for avatar/button variants',
+    },
+    width: {
+      type: 'union',
+      description: 'Custom width (string or number)',
+    },
+    height: {
+      type: 'union',
+      description: 'Custom height (string or number)',
+    },
+    fill: {
+      type: 'boolean',
+      default: false,
+      description: 'Fill parent container',
+    },
+    radius: {
+      type: 'enum',
+      values: ['none', 'sm', 'md', 'lg', 'full'],
+      description: 'Border radius override',
+    },
+  },
+
+  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',
+    ],
+    scenarioTags: [
+      'loading.content',
+      'loading.list',
+      'loading.card',
+    ],
+    a11yRules: [],
+    bans: [],
+  },
+
+  variants: [
+    {
+      name: 'Default',
+      description: 'Basic rectangle skeleton',
+      render: () => <Skeleton width={200} height={20} />,
+    },
+    {
+      name: 'Text Lines',
+      description: 'Multi-line text placeholder',
+      render: () => <Skeleton.Text lines={3} />,
+    },
+    {
+      name: 'Semantic Variants',
+      description: 'Pre-configured shapes for common elements',
+      render: () => (
+        <div style={{ display: 'flex', flexDirection: 'column', gap: '12px' }}>
+          <Skeleton variant="heading" width={200} />
+          <Skeleton variant="text" width="100%" />
+          <Skeleton variant="text" width="80%" />
+        </div>
+      ),
+    },
+    {
+      name: 'Avatar Skeleton',
+      description: 'Circular placeholder for avatars',
+      render: () => (
+        <div style={{ display: 'flex', gap: '8px', alignItems: 'center' }}>
+          <Skeleton.Circle size="sm" />
+          <Skeleton.Circle size="md" />
+          <Skeleton.Circle size="lg" />
+        </div>
+      ),
+    },
+    {
+      name: 'Card Skeleton',
+      description: 'Composed skeleton for a card layout',
+      render: () => (
+        <div style={{ width: 300, padding: 16, border: '1px solid #e5e7eb', borderRadius: 8 }}>
+          <Skeleton variant="rect" height={120} radius="md" />
+          <div style={{ marginTop: 12 }}>
+            <Skeleton variant="heading" width="60%" />
+          </div>
+          <div style={{ marginTop: 8 }}>
+            <Skeleton.Text lines={2} />
+          </div>
+        </div>
+      ),
+    },
+  ],
+});

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
+.avatar-sm {
+  width: 2rem;   // 32px
+  height: 2rem;
+}
+
+.avatar-md {
+  width: 2.5rem; // 40px
+  height: 2.5rem;
+}
+
+.avatar-lg {
+  width: 3rem;   // 48px
+  height: 3rem;
+}
+
+// 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;  // 80px default width
+}
+
+.button-md {
+  height: var(--fui-button-height-md, #{$fui-button-height-md});
+  width: 6rem;  // 96px default width
+}
+
+.button-lg {
+  height: var(--fui-button-height-lg, #{$fui-button-height-lg});
+  width: 7rem;  // 112px 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}); // 8px
+}
+
+.gap-md {
+  gap: var(--fui-space-3, #{$fui-space-3}); // 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;
+  border-radius: var(--fui-radius-sm, #{$fui-radius-sm});
+}
+
+// ============================================
+// Dark mode adjustments
+// ============================================
+
+@media (prefers-color-scheme: dark) {
+  .skeleton,
+  .textLine {
+    background-color: var(--fui-bg-tertiary, #{$fui-dark-bg-tertiary});
+  }
+}