@fragments-sdk/ui 0.1.0

package/src/components/Button/Button.fragment.tsx

@@ -0,0 +1,159 @@
+import React from 'react';
+import { defineSegment } from '@fragments/core';
+import { Button } from './index.js';
+
+export default defineSegment({
+  component: Button,
+
+  meta: {
+    name: 'Button',
+    description: 'Interactive element for user actions and form submissions',
+    category: 'actions',
+    status: 'stable',
+    tags: ['action', 'button', 'form', 'interactive'],
+  },
+
+  usage: {
+    when: [
+      'Triggering an action (save, submit, delete, etc.)',
+      'Form submission',
+      'Opening dialogs or menus',
+      'Navigation when action context is needed',
+    ],
+    whenNot: [
+      'Simple navigation (use Link)',
+      'Toggling state (use Switch or Checkbox)',
+      'Selecting from options (use Select or RadioGroup)',
+    ],
+    guidelines: [
+      'Use Primary for the main action in a context',
+      'Only one Primary button per section/form',
+      'Use Danger variant for destructive actions',
+      'Loading state should disable the button',
+    ],
+    accessibility: [
+      'Button text should describe the action',
+      'Avoid generic labels like "Click here"',
+      'Icon-only buttons need aria-label',
+    ],
+  },
+
+  props: {
+    children: {
+      type: 'node',
+      required: true,
+      description: 'Button label content',
+    },
+    variant: {
+      type: 'enum',
+      values: ['primary', 'secondary', 'ghost', 'danger'],
+      default: 'primary',
+      description: 'Visual style variant',
+      constraints: ['Only one primary button per context'],
+    },
+    size: {
+      type: 'enum',
+      values: ['sm', 'md', 'lg'],
+      default: 'md',
+      description: 'Button size',
+    },
+    disabled: {
+      type: 'boolean',
+      default: false,
+      description: 'Whether the button is disabled',
+    },
+    onClick: {
+      type: 'function',
+      description: 'Click handler',
+    },
+    type: {
+      type: 'enum',
+      values: ['button', 'submit', 'reset'],
+      default: 'button',
+      description: 'HTML button type attribute',
+    },
+  },
+
+  relations: [
+    {
+      component: 'Link',
+      relationship: 'alternative',
+      note: 'Use Link for navigation without action context',
+    },
+    {
+      component: 'IconButton',
+      relationship: 'alternative',
+      note: 'Use IconButton for icon-only actions',
+    },
+    {
+      component: 'ButtonGroup',
+      relationship: 'parent',
+      note: 'Use ButtonGroup for related action sets',
+    },
+  ],
+
+  contract: {
+    propsSummary: [
+      'variant: primary|secondary|ghost|danger (default: primary)',
+      'size: sm|md|lg (default: md)',
+      'disabled: boolean - disables interaction',
+      'type: button|submit|reset (default: button)',
+      'onClick: () => void - action handler',
+    ],
+    scenarioTags: [
+      'form.submit',
+      'action.primary',
+      'action.secondary',
+      'action.destructive',
+    ],
+    a11yRules: [
+      'A11Y_BTN_LABEL',
+      'A11Y_BTN_FOCUS',
+    ],
+    bans: [
+      {
+        pattern: '<button.*click here',
+        message: 'Use descriptive button text instead of "click here"',
+      },
+    ],
+  },
+
+  variants: [
+    {
+      name: 'Primary',
+      description: 'Default action button for primary actions',
+      render: () => <Button variant="primary">Save Changes</Button>,
+    },
+    {
+      name: 'Secondary',
+      description: 'Less prominent action button',
+      render: () => <Button variant="secondary">Cancel</Button>,
+    },
+    {
+      name: 'Ghost',
+      description: 'Minimal visual weight for subtle actions',
+      render: () => <Button variant="ghost">Learn More</Button>,
+    },
+    {
+      name: 'Danger',
+      description: 'Destructive action requiring attention',
+      render: () => <Button variant="danger">Delete Item</Button>,
+    },
+    {
+      name: 'Sizes',
+      description: 'Available size options',
+      render: () => (
+        <div style={{ display: 'flex', gap: '8px', alignItems: 'center' }}>
+          <Button size="sm">Small</Button>
+          <Button size="md">Medium</Button>
+          <Button size="lg">Large</Button>
+        </div>
+      ),
+    },
+    {
+      name: 'Disabled',
+      description: 'Non-interactive state',
+      render: () => <Button disabled>Cannot Click</Button>,
+    },
+  ],
+});

package/src/components/Button/Button.module.scss

@@ -0,0 +1,97 @@
+@use '../../tokens/variables' as *;
+@use '../../tokens/mixins' as *;
+
+.button {
+  @include button-reset;
+  @include interactive-base;
+  @include text-base;
+
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: var(--fui-space-2, $fui-space-2);
+  border-radius: var(--fui-radius-md, $fui-radius-md);
+  font-weight: var(--fui-font-weight-medium, $fui-font-weight-medium);
+  white-space: nowrap;
+  user-select: none;
+}
+
+// Sizes
+.sm {
+  min-height: var(--fui-button-height-sm, $fui-button-height-sm);
+  padding: 0 var(--fui-space-3, $fui-space-3);
+  font-size: var(--fui-font-size-xs, $fui-font-size-xs);
+}
+
+.md {
+  min-height: var(--fui-button-height-md, $fui-button-height-md);
+  padding: 0 var(--fui-space-4, $fui-space-4);
+  font-size: var(--fui-font-size-sm, $fui-font-size-sm);
+}
+
+.lg {
+  min-height: var(--fui-button-height-lg, $fui-button-height-lg);
+  padding: 0 var(--fui-space-6, $fui-space-6);
+  font-size: var(--fui-font-size-base, $fui-font-size-base);
+}
+
+// Variants
+.primary {
+  background-color: var(--fui-color-accent, $fui-color-accent);
+  color: var(--fui-text-inverse, $fui-text-inverse);
+  border: 1px solid transparent;
+
+  &:hover:not(:disabled) {
+    background-color: var(--fui-color-accent-hover, $fui-color-accent-hover);
+  }
+
+  &:active:not(:disabled),
+  &[data-pressed] {
+    background-color: var(--fui-color-accent-active, $fui-color-accent-active);
+  }
+}
+
+.secondary {
+  background-color: var(--fui-bg-secondary, $fui-bg-secondary);
+  color: var(--fui-text-primary, $fui-text-primary);
+  border: 1px solid var(--fui-border-strong, $fui-border-strong);
+
+  &:hover:not(:disabled) {
+    background-color: var(--fui-bg-tertiary, $fui-bg-tertiary);
+  }
+
+  &:active:not(:disabled),
+  &[data-pressed] {
+    background-color: var(--fui-bg-tertiary, $fui-bg-tertiary);
+  }
+}
+
+.ghost {
+  background-color: transparent;
+  color: var(--fui-text-primary, $fui-text-primary);
+  border: 1px solid transparent;
+
+  &:hover:not(:disabled) {
+    background-color: var(--fui-bg-hover, $fui-bg-hover);
+  }
+
+  &:active:not(:disabled),
+  &[data-pressed] {
+    background-color: var(--fui-bg-active, $fui-bg-active);
+  }
+}
+
+.danger {
+  background-color: var(--fui-color-danger, $fui-color-danger);
+  color: var(--fui-text-inverse, $fui-text-inverse);
+  border: 1px solid transparent;
+
+  &:hover:not(:disabled) {
+    background-color: var(--fui-color-danger-hover, $fui-color-danger-hover);
+  }
+
+  &:active:not(:disabled),
+  &[data-pressed] {
+    background-color: var(--fui-color-danger-hover, $fui-color-danger-hover);
+  }
+}

package/src/components/Button/index.tsx

@@ -0,0 +1,51 @@
+import * as React from 'react';
+import { Button as BaseButton } from '@base-ui/react/button';
+import styles from './Button.module.scss';
+// Import globals to ensure CSS variables are defined
+import '../../styles/globals.scss';
+
+export interface ButtonProps {
+  children: React.ReactNode;
+  variant?: 'primary' | 'secondary' | 'ghost' | 'danger';
+  size?: 'sm' | 'md' | 'lg';
+  disabled?: boolean;
+  onClick?: (e: React.MouseEvent<HTMLButtonElement>) => void;
+  type?: 'button' | 'submit' | 'reset';
+  className?: string;
+}
+
+export const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
+  function Button(
+    {
+      children,
+      variant = 'primary',
+      size = 'md',
+      disabled = false,
+      onClick,
+      type = 'button',
+      className,
+    },
+    ref
+  ) {
+    const classNames = [
+      styles.button,
+      styles[size],
+      styles[variant],
+      className,
+    ]
+      .filter(Boolean)
+      .join(' ');
+
+    return (
+      <BaseButton
+        ref={ref}
+        type={type}
+        disabled={disabled}
+        onClick={onClick}
+        className={classNames}
+      >
+        {children}
+      </BaseButton>
+    );
+  }
+);

package/src/components/Card/Card.fragment.tsx

@@ -0,0 +1,156 @@
+import React from 'react';
+import { defineSegment } from '@fragments/core';
+import { Card } from './index.js';
+
+export default defineSegment({
+  component: Card,
+
+  meta: {
+    name: 'Card',
+    description: 'Container for grouping related content',
+    category: 'layout',
+    status: 'stable',
+    tags: ['container', 'layout', 'surface'],
+  },
+
+  usage: {
+    when: [
+      'Grouping related pieces of content together',
+      'Creating visual separation between content sections',
+      'Displaying a preview or summary of an item',
+      'Building dashboard widgets or tiles',
+    ],
+    whenNot: [
+      'Simple text content that does not need grouping',
+      'Modal or dialog content (use Dialog component)',
+      'Navigation items (use NavItem or similar)',
+    ],
+    guidelines: [
+      'Use consistent card variants within the same context',
+      'Cards in a grid should have uniform sizing',
+      'Use elevated variant sparingly for emphasis',
+      'Interactive cards should have clear hover states',
+    ],
+    accessibility: [
+      'Interactive cards should use button or link semantics',
+      'Card titles should be appropriate heading levels',
+    ],
+  },
+
+  props: {
+    children: {
+      type: 'node',
+      description: 'Card content',
+    },
+    title: {
+      type: 'string',
+      description: 'Card header title',
+    },
+    description: {
+      type: 'string',
+      description: 'Card header description/subtitle',
+    },
+    variant: {
+      type: 'enum',
+      values: ['default', 'outlined', 'elevated'],
+      default: 'default',
+      description: 'Visual style of the card surface',
+      constraints: ['Use "elevated" sparingly to maintain visual hierarchy'],
+    },
+    padding: {
+      type: 'enum',
+      values: ['none', 'sm', 'md', 'lg'],
+      default: 'md',
+      description: 'Internal padding size',
+    },
+    onClick: {
+      type: 'function',
+      description: 'Click handler - makes card interactive',
+    },
+  },
+
+  relations: [
+    {
+      component: 'CardGrid',
+      relationship: 'parent',
+      note: 'Use CardGrid for responsive card layouts',
+    },
+    {
+      component: 'ListItem',
+      relationship: 'alternative',
+      note: 'Use ListItem for linear list layouts',
+    },
+  ],
+
+  contract: {
+    propsSummary: [
+      'variant: default|outlined|elevated (default: default)',
+      'padding: none|sm|md|lg (default: md)',
+      'title: string - header title',
+      'description: string - header subtitle',
+      'onClick: () => void - makes card interactive',
+    ],
+    scenarioTags: [
+      'layout.container',
+      'content.group',
+      'pattern.widget',
+      'pattern.tile',
+    ],
+    a11yRules: [
+      'A11Y_CARD_HEADING',
+      'A11Y_CARD_INTERACTIVE',
+    ],
+  },
+
+  variants: [
+    {
+      name: 'Default',
+      description: 'Standard card with subtle shadow',
+      render: () => (
+        <Card title="Card Title" description="A brief description">
+          Card content goes here.
+        </Card>
+      ),
+    },
+    {
+      name: 'Outlined',
+      description: 'Card with border instead of shadow',
+      render: () => (
+        <Card variant="outlined" title="Outlined Card">
+          Content with border.
+        </Card>
+      ),
+    },
+    {
+      name: 'Elevated',
+      description: 'Card with prominent shadow for emphasis',
+      render: () => (
+        <Card variant="elevated" title="Featured Item">
+          Important content.
+        </Card>
+      ),
+    },
+    {
+      name: 'Interactive',
+      description: 'Clickable card',
+      render: () => (
+        <Card
+          title="Click Me"
+          description="This card is interactive"
+          onClick={() => alert('Card clicked!')}
+        >
+          Click anywhere on this card.
+        </Card>
+      ),
+    },
+    {
+      name: 'Content Only',
+      description: 'Card without header',
+      render: () => (
+        <Card>
+          Just content, no title or description.
+        </Card>
+      ),
+    },
+  ],
+});

package/src/components/Card/Card.module.scss

@@ -0,0 +1,86 @@
+@use '../../tokens/variables' as *;
+@use '../../tokens/mixins' as *;
+
+.card {
+  @include surface-elevated;
+  font-family: var(--fui-font-sans, $fui-font-sans);
+  transition:
+    box-shadow var(--fui-transition-fast, $fui-transition-fast),
+    border-color var(--fui-transition-fast, $fui-transition-fast);
+}
+
+// Variants
+.default {
+  box-shadow: var(--fui-shadow-sm, $fui-shadow-sm);
+}
+
+.outlined {
+  border-color: var(--fui-border-strong, $fui-border-strong);
+  box-shadow: none;
+}
+
+.elevated {
+  box-shadow: var(--fui-shadow-md, $fui-shadow-md);
+}
+
+// Padding
+.paddingNone {
+  padding: 0;
+}
+
+.paddingSm {
+  padding: var(--fui-space-3, $fui-space-3);
+}
+
+.paddingMd {
+  padding: var(--fui-space-4, $fui-space-4);
+}
+
+.paddingLg {
+  padding: var(--fui-space-6, $fui-space-6);
+}
+
+// Interactive card (when onClick is provided)
+.interactive {
+  @include button-reset;
+  @include interactive-base;
+
+  display: block;
+  width: 100%;
+  text-align: left;
+  cursor: pointer;
+
+  &:hover {
+    border-color: var(--fui-border-strong, $fui-border-strong);
+    box-shadow: var(--fui-shadow-md, $fui-shadow-md);
+  }
+
+  &:active {
+    box-shadow: var(--fui-shadow-sm, $fui-shadow-sm);
+  }
+}
+
+.header {
+  margin-bottom: var(--fui-space-3, $fui-space-3);
+}
+
+.title {
+  margin: 0;
+  font-size: var(--fui-font-size-base, $fui-font-size-base);
+  font-weight: var(--fui-font-weight-semibold, $fui-font-weight-semibold);
+  color: var(--fui-text-primary, $fui-text-primary);
+  line-height: var(--fui-line-height-tight, $fui-line-height-tight);
+}
+
+.description {
+  margin: var(--fui-space-1, $fui-space-1) 0 0;
+  font-size: var(--fui-font-size-sm, $fui-font-size-sm);
+  color: var(--fui-text-secondary, $fui-text-secondary);
+  line-height: var(--fui-line-height-normal, $fui-line-height-normal);
+}
+
+.content {
+  color: var(--fui-text-primary, $fui-text-primary);
+  font-size: var(--fui-font-size-sm, $fui-font-size-sm);
+  line-height: var(--fui-line-height-normal, $fui-line-height-normal);
+}

package/src/components/Card/index.tsx

@@ -0,0 +1,79 @@
+import * as React from 'react';
+import styles from './Card.module.scss';
+// Import globals to ensure CSS variables are defined
+import '../../styles/globals.scss';
+
+export interface CardProps {
+  children?: React.ReactNode;
+  title?: string;
+  description?: string;
+  variant?: 'default' | 'outlined' | 'elevated';
+  padding?: 'none' | 'sm' | 'md' | 'lg';
+  onClick?: () => void;
+  className?: string;
+}
+
+const paddingMap = {
+  none: styles.paddingNone,
+  sm: styles.paddingSm,
+  md: styles.paddingMd,
+  lg: styles.paddingLg,
+};
+
+export const Card = React.forwardRef<HTMLDivElement, CardProps>(
+  function Card(
+    {
+      children,
+      title,
+      description,
+      variant = 'default',
+      padding = 'md',
+      onClick,
+      className,
+    },
+    ref
+  ) {
+    const isInteractive = !!onClick;
+
+    const classes = [
+      styles.card,
+      styles[variant],
+      paddingMap[padding],
+      isInteractive && styles.interactive,
+      className,
+    ]
+      .filter(Boolean)
+      .join(' ');
+
+    const content = (
+      <>
+        {(title || description) && (
+          <div className={children ? styles.header : undefined}>
+            {title && <h3 className={styles.title}>{title}</h3>}
+            {description && <p className={styles.description}>{description}</p>}
+          </div>
+        )}
+        {children && <div className={styles.content}>{children}</div>}
+      </>
+    );
+
+    if (isInteractive) {
+      return (
+        <button
+          ref={ref as React.Ref<HTMLButtonElement>}
+          type="button"
+          onClick={onClick}
+          className={classes}
+        >
+          {content}
+        </button>
+      );
+    }
+
+    return (
+      <div ref={ref} className={classes}>
+        {content}
+      </div>
+    );
+  }
+);