@fragments-sdk/ui 0.1.0

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@fragments-sdk/ui",
+  "version": "0.1.0",
+  "description": "Customizable UI components built on Base UI headless primitives",
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./styles": "./src/styles/globals.scss",
+    "./tokens": "./src/tokens/_variables.scss",
+    "./brand": "./src/brand.ts"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "dev": "fragments dev",
+    "build": "fragments build",
+    "validate": "fragments validate"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0"
+  },
+  "dependencies": {
+    "@base-ui/react": "^1.0.0",
+    "@tanstack/react-table": "^8.21.3"
+  },
+  "devDependencies": {
+    "@fragments/cli": "workspace:*",
+    "@fragments/core": "workspace:*",
+    "@fragments/viewer": "workspace:*",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "sass": "^1.83.0",
+    "typescript": "^5.7.0"
+  },
+  "files": [
+    "src"
+  ]
+}

package/src/brand.ts

@@ -0,0 +1,15 @@
+/**
+ * Shared brand constants for the Fragments ecosystem
+ */
+export const BRAND = {
+  name: 'Fragments',
+  tagline: 'AI-native design system tooling',
+  url: 'https://fragments.cloud',
+  support: 'support@fragments.cloud',
+  social: {
+    github: 'https://github.com/anthropics/fragments',
+    twitter: '@fragmentscloud',
+  },
+} as const;
+
+export type Brand = typeof BRAND;

package/src/components/Alert/Alert.fragment.tsx

@@ -0,0 +1,163 @@
+import React from 'react';
+import { defineSegment } from '@fragments/core';
+import { Alert } from './index.js';
+
+export default defineSegment({
+  component: Alert,
+
+  meta: {
+    name: 'Alert',
+    description: 'Contextual feedback messages for user actions or system status. Supports multiple severity levels with optional actions and dismissibility.',
+    category: 'feedback',
+    status: 'stable',
+    tags: ['notification', 'message', 'feedback', 'banner', 'toast'],
+    since: '0.1.0',
+  },
+
+  usage: {
+    when: [
+      'Communicating the result of a user action (success, error)',
+      'Warning about potential issues before they occur',
+      'Providing important contextual information inline',
+      'System status notifications that require attention',
+    ],
+    whenNot: [
+      'Brief status labels (use Badge instead)',
+      'Transient notifications (use Toast/Snackbar)',
+      'Form-field-level errors (use Input error prop)',
+      'Confirmation before destructive actions (use Dialog)',
+    ],
+    guidelines: [
+      'Match severity to the actual importance: info for context, warning for potential issues, error for failures',
+      'Always provide actionable guidance in error alerts',
+      'Use titles for complex messages; skip titles for brief one-liners',
+      'Limit to one action per alert to avoid decision paralysis',
+      'Dismissible alerts should only be used for non-critical information',
+    ],
+    accessibility: [
+      'Uses role="alert" for screen reader announcement',
+      'Error and warning alerts are announced immediately by assistive technology',
+      'Dismiss button must have an accessible label',
+      'Color alone must not convey meaning - icons and text reinforce severity',
+    ],
+  },
+
+  props: {
+    children: {
+      type: 'node',
+      description: 'Alert message content',
+      required: true,
+    },
+    title: {
+      type: 'string',
+      description: 'Optional bold title displayed above the message',
+    },
+    severity: {
+      type: 'enum',
+      description: 'Visual severity level',
+      values: ['info', 'success', 'warning', 'error'],
+      default: 'info',
+    },
+    dismissible: {
+      type: 'boolean',
+      description: 'Whether the alert shows a dismiss button',
+      default: 'false',
+    },
+    onDismiss: {
+      type: 'function',
+      description: 'Callback when the alert is dismissed',
+    },
+    action: {
+      type: 'custom',
+      description: 'Optional action button: { label: string, onClick: () => void }',
+    },
+  },
+
+  relations: [
+    { component: 'Badge', relationship: 'alternative', note: 'Use Badge for compact, inline status labels' },
+    { component: 'Toast', relationship: 'alternative', note: 'Use Toast for transient notifications that auto-dismiss' },
+    { component: 'Dialog', relationship: 'sibling', note: 'Use Dialog for blocking confirmations' },
+  ],
+
+  contract: {
+    propsSummary: [
+      'children: ReactNode - message content (required)',
+      'title: string - optional bold heading',
+      'severity: info|success|warning|error - visual severity',
+      'dismissible: boolean - shows dismiss button',
+      'action: { label, onClick } - optional action button',
+    ],
+    scenarioTags: [
+      'feedback.message',
+      'feedback.error',
+      'feedback.success',
+      'feedback.warning',
+      'content.notification',
+    ],
+    a11yRules: ['A11Y_ALERT_ROLE', 'A11Y_ALERT_DISMISS', 'A11Y_ALERT_CONTRAST'],
+    validationBans: [
+      { pattern: 'severity="error"(?!.*children)', reason: 'Error alerts must include helpful message text' },
+    ],
+  },
+
+  variants: [
+    {
+      name: 'Info',
+      description: 'Informational context for the user',
+      render: () => (
+        <Alert severity="info">
+          Your session will expire in 15 minutes. Save your work to avoid losing changes.
+        </Alert>
+      ),
+    },
+    {
+      name: 'Success',
+      description: 'Positive confirmation of completed action',
+      render: () => (
+        <Alert severity="success" title="Payment processed">
+          Your order #12345 has been confirmed. You will receive a confirmation email shortly.
+        </Alert>
+      ),
+    },
+    {
+      name: 'Warning',
+      description: 'Caution about potential issues',
+      render: () => (
+        <Alert severity="warning" title="Storage almost full">
+          You have used 90% of your storage quota. Consider deleting unused files.
+        </Alert>
+      ),
+    },
+    {
+      name: 'Error',
+      description: 'Error state requiring user attention',
+      render: () => (
+        <Alert severity="error" title="Upload failed">
+          The file could not be uploaded. Check your connection and try again.
+        </Alert>
+      ),
+    },
+    {
+      name: 'With Action',
+      description: 'Alert with an actionable button',
+      render: () => (
+        <Alert
+          severity="warning"
+          title="Update available"
+          action={{ label: 'Update now', onClick: () => {} }}
+        >
+          A new version is available with important security fixes.
+        </Alert>
+      ),
+    },
+    {
+      name: 'Dismissible',
+      description: 'Alert that can be closed by the user',
+      render: () => (
+        <Alert severity="info" dismissible>
+          You can customize your notification preferences in Settings.
+        </Alert>
+      ),
+    },
+  ],
+});

package/src/components/Alert/Alert.module.scss

@@ -0,0 +1,116 @@
+@use '../../tokens/variables' as *;
+@use '../../tokens/mixins' as *;
+
+.alert {
+  display: flex;
+  align-items: flex-start;
+  gap: var(--fui-space-3, $fui-space-3);
+  padding: var(--fui-space-3, $fui-space-3) var(--fui-space-4, $fui-space-4);
+  border-radius: var(--fui-radius-lg, $fui-radius-lg);
+  font-family: var(--fui-font-sans, $fui-font-sans);
+  font-size: var(--fui-font-size-sm, $fui-font-size-sm);
+  line-height: var(--fui-line-height-normal, $fui-line-height-normal);
+}
+
+// Severity variants
+.info {
+  background-color: var(--fui-color-info-bg, $fui-color-info-bg);
+  border: 1px solid var(--fui-color-info, $fui-color-info);
+  color: var(--fui-color-info, $fui-color-info);
+}
+
+.success {
+  background-color: var(--fui-color-success-bg, $fui-color-success-bg);
+  border: 1px solid var(--fui-color-success, $fui-color-success);
+  color: var(--fui-color-success, $fui-color-success);
+}
+
+.warning {
+  background-color: var(--fui-color-warning-bg, $fui-color-warning-bg);
+  border: 1px solid var(--fui-color-warning, $fui-color-warning);
+  color: var(--fui-color-warning, $fui-color-warning);
+}
+
+.error {
+  background-color: var(--fui-color-danger-bg, $fui-color-danger-bg);
+  border: 1px solid var(--fui-color-danger, $fui-color-danger);
+  color: var(--fui-color-danger, $fui-color-danger);
+}
+
+.icon {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 20px;
+  height: 20px;
+  border-radius: 50%;
+  font-size: var(--fui-font-size-xs, $fui-font-size-xs);
+  font-weight: var(--fui-font-weight-semibold, $fui-font-weight-semibold);
+  flex-shrink: 0;
+  margin-top: 1px;
+  color: var(--fui-text-inverse, $fui-text-inverse);
+}
+
+.info .icon {
+  background-color: var(--fui-color-info, $fui-color-info);
+}
+
+.success .icon {
+  background-color: var(--fui-color-success, $fui-color-success);
+}
+
+.warning .icon {
+  background-color: var(--fui-color-warning, $fui-color-warning);
+}
+
+.error .icon {
+  background-color: var(--fui-color-danger, $fui-color-danger);
+}
+
+.body {
+  flex: 1;
+  min-width: 0;
+}
+
+.title {
+  font-weight: var(--fui-font-weight-semibold, $fui-font-weight-semibold);
+  margin-bottom: 2px;
+}
+
+.message {
+  opacity: 0.9;
+}
+
+.action {
+  @include button-reset;
+
+  margin-top: var(--fui-space-2, $fui-space-2);
+  font-weight: var(--fui-font-weight-semibold, $fui-font-weight-semibold);
+  font-size: var(--fui-font-size-xs, $fui-font-size-xs);
+  color: inherit;
+  text-decoration: underline;
+
+  &:hover {
+    opacity: 0.8;
+  }
+
+  &:focus-visible {
+    @include focus-ring;
+  }
+}
+
+.dismiss {
+  @include button-reset;
+  @include interactive-base;
+
+  padding: 0 var(--fui-space-1, $fui-space-1);
+  font-size: 18px;
+  color: inherit;
+  opacity: 0.6;
+  line-height: 1;
+  border-radius: var(--fui-radius-sm, $fui-radius-sm);
+
+  &:hover {
+    opacity: 1;
+  }
+}

package/src/components/Alert/index.tsx

@@ -0,0 +1,95 @@
+import * as React from 'react';
+import { Button as BaseButton } from '@base-ui/react/button';
+import styles from './Alert.module.scss';
+// Import globals to ensure CSS variables are defined
+import '../../styles/globals.scss';
+
+export interface AlertProps {
+  children: React.ReactNode;
+  title?: string;
+  severity?: 'info' | 'success' | 'warning' | 'error';
+  dismissible?: boolean;
+  onDismiss?: () => void;
+  action?: {
+    label: string;
+    onClick: () => void;
+  };
+  className?: string;
+}
+
+const severityIcons: Record<string, string> = {
+  info: 'i',
+  success: '\u2713',
+  warning: '!',
+  error: '\u2717',
+};
+
+export const Alert = React.forwardRef<HTMLDivElement, AlertProps>(
+  function Alert(
+    {
+      children,
+      title,
+      severity = 'info',
+      dismissible = false,
+      onDismiss,
+      action,
+      className,
+    },
+    ref
+  ) {
+    const [dismissed, setDismissed] = React.useState(false);
+    const titleId = React.useId();
+    const descId = React.useId();
+
+    if (dismissed) return null;
+
+    const handleDismiss = () => {
+      setDismissed(true);
+      onDismiss?.();
+    };
+
+    const classes = [styles.alert, styles[severity], className]
+      .filter(Boolean)
+      .join(' ');
+
+    return (
+      <div
+        ref={ref}
+        role="alert"
+        aria-labelledby={title ? titleId : undefined}
+        aria-describedby={descId}
+        className={classes}
+      >
+        <span className={styles.icon} aria-hidden="true">
+          {severityIcons[severity]}
+        </span>
+
+        <div className={styles.body}>
+          {title && (
+            <div id={titleId} className={styles.title}>
+              {title}
+            </div>
+          )}
+          <div id={descId} className={styles.message}>
+            {children}
+          </div>
+          {action && (
+            <BaseButton onClick={action.onClick} className={styles.action}>
+              {action.label}
+            </BaseButton>
+          )}
+        </div>
+
+        {dismissible && (
+          <BaseButton
+            onClick={handleDismiss}
+            aria-label="Dismiss alert"
+            className={styles.dismiss}
+          >
+            &times;
+          </BaseButton>
+        )}
+      </div>
+    );
+  }
+);

package/src/components/Avatar/Avatar.fragment.tsx

@@ -0,0 +1,147 @@
+import React from 'react';
+import { defineSegment } from '@fragments/core';
+import { Avatar } from './index.js';
+
+export default defineSegment({
+  component: Avatar,
+
+  meta: {
+    name: 'Avatar',
+    description: 'Visual representation of a user or entity',
+    category: 'data-display',
+    status: 'stable',
+    tags: ['user', 'profile', 'image', 'identity'],
+  },
+
+  usage: {
+    when: [
+      'Displaying user profile pictures',
+      'Showing team member lists',
+      'Representing entities in lists or cards',
+      'User identification in comments or messages',
+    ],
+    whenNot: [
+      'Decorative images (use Image)',
+      'Logo display (use Logo component)',
+      'Large profile headers (use custom layout)',
+    ],
+    guidelines: [
+      'Always provide alt text or name for accessibility',
+      'Use consistent sizes within the same context',
+      'Provide fallback initials when image may not load',
+      'Use Avatar.Group for multiple avatars in a row',
+    ],
+    accessibility: [
+      'Include meaningful alt text describing the user',
+      'Initials should be derived from name for screen readers',
+      'Decorative avatars should have empty alt',
+    ],
+  },
+
+  props: {
+    src: {
+      type: 'string',
+      description: 'Image source URL',
+    },
+    alt: {
+      type: 'string',
+      description: 'Alt text for the image',
+    },
+    name: {
+      type: 'string',
+      description: 'Full name - used to generate initials',
+    },
+    initials: {
+      type: 'string',
+      description: 'Fallback initials (1-2 characters)',
+    },
+    size: {
+      type: 'enum',
+      values: ['xs', 'sm', 'md', 'lg', 'xl'],
+      default: 'md',
+      description: 'Size variant',
+    },
+    shape: {
+      type: 'enum',
+      values: ['circle', 'square'],
+      default: 'circle',
+      description: 'Shape variant',
+    },
+  },
+
+  relations: [
+    {
+      component: 'AvatarGroup',
+      relationship: 'parent',
+      note: 'Use Avatar.Group for stacked avatar displays',
+    },
+  ],
+
+  contract: {
+    propsSummary: [
+      'src: string - image URL',
+      'name: string - used for initials fallback',
+      'size: xs|sm|md|lg|xl (default: md)',
+      'shape: circle|square (default: circle)',
+    ],
+    scenarioTags: [
+      'profile.display',
+      'list.user',
+      'comment.author',
+    ],
+    a11yRules: [
+      'A11Y_IMG_ALT',
+    ],
+    bans: [],
+  },
+
+  variants: [
+    {
+      name: 'Default',
+      description: 'Avatar with image',
+      render: () => (
+        <Avatar
+          src="https://i.pravatar.cc/150?u=jane"
+          alt="Jane Doe"
+          name="Jane Doe"
+        />
+      ),
+    },
+    {
+      name: 'With Initials',
+      description: 'Fallback when no image is provided',
+      render: () => <Avatar name="John Smith" />,
+    },
+    {
+      name: 'Sizes',
+      description: 'Available size options',
+      render: () => (
+        <div style={{ display: 'flex', gap: '8px', alignItems: 'center' }}>
+          <Avatar name="XS" size="xs" />
+          <Avatar name="SM" size="sm" />
+          <Avatar name="MD" size="md" />
+          <Avatar name="LG" size="lg" />
+          <Avatar name="XL" size="xl" />
+        </div>
+      ),
+    },
+    {
+      name: 'Square Shape',
+      description: 'Square variant for app icons or brands',
+      render: () => <Avatar name="App" shape="square" />,
+    },
+    {
+      name: 'Group',
+      description: 'Multiple avatars stacked together',
+      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>
+      ),
+    },
+  ],
+});