@usefragments/ui 1.0.0

package/src/components/Stack/Stack.contract.json

@@ -0,0 +1,220 @@
+{
+  "$schema": "https://usefragments.com/schemas/contract.v1.json",
+  "name": "Stack",
+  "description": "Flexible layout component for arranging children in rows or columns with consistent spacing. Supports responsive direction and gap.",
+  "category": "layout",
+  "tags": [
+    "stack",
+    "layout",
+    "flex",
+    "spacing",
+    "responsive"
+  ],
+  "status": "stable",
+  "sourcePath": "src/components/Stack/index.tsx",
+  "exportName": "Stack",
+  "propsSummary": [
+    "children: node (required)",
+    "direction: union (default: column)",
+    "gap: union (default: md)",
+    "align: start|center|end|stretch|baseline",
+    "justify: start|center|end|between",
+    "wrap: boolean (default: false)",
+    "separator: node",
+    "as: div|section|nav|article|aside|header|footer|main|ul|ol (default: div)",
+    "className: string",
+    "style: object"
+  ],
+  "props": {
+    "children": {
+      "type": "node",
+      "description": "Elements to arrange",
+      "required": true
+    },
+    "direction": {
+      "type": "union",
+      "description": "Stack direction: \"row\", \"column\", or responsive object",
+      "default": "column",
+      "required": false
+    },
+    "gap": {
+      "type": "union",
+      "description": "Spacing between items: \"none\"|\"xs\"|\"sm\"|\"md\"|\"lg\"|\"xl\", a number (1-8) for space scale, or responsive object",
+      "default": "md",
+      "required": false
+    },
+    "align": {
+      "type": "enum",
+      "description": "Cross-axis alignment",
+      "required": false,
+      "values": [
+        "start",
+        "center",
+        "end",
+        "stretch",
+        "baseline"
+      ]
+    },
+    "justify": {
+      "type": "enum",
+      "description": "Main-axis alignment",
+      "required": false,
+      "values": [
+        "start",
+        "center",
+        "end",
+        "between"
+      ]
+    },
+    "wrap": {
+      "type": "boolean",
+      "description": "Allow items to wrap",
+      "default": "false",
+      "required": false
+    },
+    "separator": {
+      "type": "node",
+      "description": "Render a separator between children. true = default 1px line, or pass a ReactNode for custom separators.",
+      "required": false
+    },
+    "as": {
+      "type": "enum",
+      "description": "HTML element to render",
+      "default": "div",
+      "required": false,
+      "values": [
+        "div",
+        "section",
+        "nav",
+        "article",
+        "aside",
+        "header",
+        "footer",
+        "main",
+        "ul",
+        "ol"
+      ]
+    },
+    "className": {
+      "type": "string",
+      "description": "",
+      "required": false
+    },
+    "style": {
+      "type": "object",
+      "description": "",
+      "required": false
+    }
+  },
+  "usage": {
+    "when": [
+      "Arranging elements in a row or column",
+      "Creating consistent spacing between items",
+      "Building responsive layouts",
+      "Simple flexbox-based arrangements"
+    ],
+    "whenNot": [
+      "Complex grid layouts (use Grid)",
+      "Button-specific grouping (use ButtonGroup)",
+      "Page-level layout (use AppShell)"
+    ],
+    "guidelines": [
+      "Use semantic elements via the \"as\" prop when appropriate",
+      "Leverage responsive props for mobile-first layouts",
+      "Keep spacing consistent within related sections",
+      "Consider alignment for visual balance",
+      "Pass DOM attributes (id, role, aria-*, data-*, event handlers) directly to Stack root when needed"
+    ],
+    "accessibility": [
+      "Use semantic elements (nav, section, etc.) via \"as\" prop",
+      "Maintains source order for screen readers",
+      "No accessibility concerns with visual arrangement"
+    ]
+  },
+  "examples": [
+    {
+      "name": "Vertical Stack",
+      "description": "Default column layout",
+      "code": "<Stack gap=\"sm\">\n  <Badge>Item 1</Badge>\n  <Badge>Item 2</Badge>\n  <Badge>Item 3</Badge>\n</Stack>"
+    },
+    {
+      "name": "Horizontal Stack",
+      "description": "Row layout",
+      "code": "<Stack direction=\"row\" gap=\"sm\">\n  <Badge>Item 1</Badge>\n  <Badge>Item 2</Badge>\n  <Badge>Item 3</Badge>\n</Stack>"
+    },
+    {
+      "name": "Gap Sizes",
+      "description": "Different spacing options",
+      "code": "<Stack gap=\"lg\">\n  <Stack direction=\"row\" gap=\"xs\">\n    <Badge variant=\"info\">XS</Badge>\n    <Badge variant=\"info\">Gap</Badge>\n  </Stack>\n  <Stack direction=\"row\" gap=\"sm\">\n    <Badge variant=\"info\">SM</Badge>\n    <Badge variant=\"info\">Gap</Badge>\n  </Stack>\n  <Stack direction=\"row\" gap=\"md\">\n    <Badge variant=\"info\">MD</Badge>\n    <Badge variant=\"info\">Gap</Badge>\n  </Stack>\n  <Stack direction=\"row\" gap=\"lg\">\n    <Badge variant=\"info\">LG</Badge>\n    <Badge variant=\"info\">Gap</Badge>\n  </Stack>\n</Stack>"
+    },
+    {
+      "name": "Numeric Gap",
+      "description": "Using number values (1-8) mapped to the spacing scale",
+      "code": "<Stack gap=\"lg\">\n  <Stack direction=\"row\" gap={2}>\n    <Badge variant=\"info\">Gap 2</Badge>\n    <Badge variant=\"info\">Gap 2</Badge>\n  </Stack>\n  <Stack direction=\"row\" gap={4}>\n    <Badge variant=\"info\">Gap 4</Badge>\n    <Badge variant=\"info\">Gap 4</Badge>\n  </Stack>\n  <Stack direction=\"row\" gap={6}>\n    <Badge variant=\"info\">Gap 6</Badge>\n    <Badge variant=\"info\">Gap 6</Badge>\n  </Stack>\n</Stack>"
+    },
+    {
+      "name": "Alignment",
+      "description": "Cross-axis and main-axis alignment",
+      "code": "<Stack gap=\"md\">\n  <Stack direction=\"row\" gap=\"sm\" justify=\"between\" style={{ width: '200px', padding: '8px', background: 'var(--fui-bg-secondary)', borderRadius: '4px' }}>\n    <Badge>Start</Badge>\n    <Badge>End</Badge>\n  </Stack>\n  <Stack direction=\"row\" gap=\"sm\" justify=\"center\" style={{ width: '200px', padding: '8px', background: 'var(--fui-bg-secondary)', borderRadius: '4px' }}>\n    <Badge>Centered</Badge>\n  </Stack>\n</Stack>"
+    },
+    {
+      "name": "Responsive",
+      "description": "Direction changes at breakpoints",
+      "code": "<Stack\n  direction={{ base: 'column', md: 'row' }}\n  gap={{ base: 'sm', md: 'lg' }}\n>\n  <Button variant=\"secondary\">First</Button>\n  <Button variant=\"secondary\">Second</Button>\n  <Button variant=\"secondary\">Third</Button>\n</Stack>"
+    },
+    {
+      "name": "With Separator",
+      "description": "Default line separator between items",
+      "code": "<Stack gap=\"md\" separator>\n  <div>Section One</div>\n  <div>Section Two</div>\n  <div>Section Three</div>\n</Stack>"
+    },
+    {
+      "name": "Semantic Element",
+      "description": "Using nav element for navigation",
+      "code": "<Stack as=\"nav\" direction=\"row\" gap=\"md\">\n  <Button variant=\"ghost\" size=\"sm\">Home</Button>\n  <Button variant=\"ghost\" size=\"sm\">About</Button>\n  <Button variant=\"ghost\" size=\"sm\">Contact</Button>\n</Stack>"
+    }
+  ],
+  "relations": [
+    {
+      "component": "Grid",
+      "relationship": "alternative",
+      "note": "Use Grid for complex 2D layouts"
+    },
+    {
+      "component": "ButtonGroup",
+      "relationship": "sibling",
+      "note": "ButtonGroup is specialized for buttons"
+    },
+    {
+      "component": "Box",
+      "relationship": "sibling",
+      "note": "Box for single-element styling"
+    }
+  ],
+  "contract": {
+    "propsSummary": [
+      "direction: row|column|{responsive} - stack direction",
+      "gap: none|xs|sm|md|lg|xl|number|{responsive} - spacing (number maps to space scale)",
+      "align: start|center|end|stretch|baseline - cross-axis",
+      "justify: start|center|end|between - main-axis",
+      "wrap: boolean - allow wrapping",
+      "separator: boolean|ReactNode - divider between children",
+      "as: string - HTML element",
+      "Pass-through DOM props supported on the root (id, role, aria-*, data-*, handlers)"
+    ],
+    "a11yRules": [
+      "A11Y_SEMANTIC_ELEMENTS"
+    ]
+  },
+  "ai": {
+    "compositionPattern": "compound",
+    "subComponents": [
+      "Root"
+    ]
+  },
+  "provenance": {
+    "source": "migrated",
+    "verified": false,
+    "frameworkSupport": "native",
+    "extractedAt": "2026-03-13T23:19:04.310Z"
+  }
+}

package/src/components/Stack/Stack.module.scss

@@ -0,0 +1,136 @@
+@use '../../tokens/variables' as *;
+
+.stack {
+  display: flex;
+}
+
+// Direction
+.row {
+  flex-direction: row;
+}
+
+.column {
+  flex-direction: column;
+}
+
+// Responsive direction
+.directionResponsive {
+  flex-direction: var(--fui-stack-direction, column);
+
+  @media (min-width: 640px) {
+    flex-direction: var(--fui-stack-direction-sm, var(--fui-stack-direction, column));
+  }
+
+  @media (min-width: 768px) {
+    flex-direction: var(--fui-stack-direction-md, var(--fui-stack-direction-sm, var(--fui-stack-direction, column)));
+  }
+
+  @media (min-width: 1024px) {
+    flex-direction: var(--fui-stack-direction-lg, var(--fui-stack-direction-md, var(--fui-stack-direction-sm, var(--fui-stack-direction, column))));
+  }
+
+  @media (min-width: 1280px) {
+    flex-direction: var(--fui-stack-direction-xl, var(--fui-stack-direction-lg, var(--fui-stack-direction-md, var(--fui-stack-direction-sm, var(--fui-stack-direction, column)))));
+  }
+}
+
+// Gap sizes
+.gap-xs {
+  gap: var(--fui-space-1, $fui-space-1);
+}
+
+.gap-sm {
+  gap: var(--fui-space-2, $fui-space-2);
+}
+
+.gap-md {
+  gap: var(--fui-space-3, $fui-space-3);
+}
+
+.gap-lg {
+  gap: var(--fui-space-4, $fui-space-4);
+}
+
+.gap-xl {
+  gap: var(--fui-space-6, $fui-space-6);
+}
+
+// Responsive gap
+.gapResponsive {
+  gap: var(--fui-stack-gap, 0);
+
+  @media (min-width: 640px) {
+    gap: var(--fui-stack-gap-sm, var(--fui-stack-gap, 0));
+  }
+
+  @media (min-width: 768px) {
+    gap: var(--fui-stack-gap-md, var(--fui-stack-gap-sm, var(--fui-stack-gap, 0)));
+  }
+
+  @media (min-width: 1024px) {
+    gap: var(--fui-stack-gap-lg, var(--fui-stack-gap-md, var(--fui-stack-gap-sm, var(--fui-stack-gap, 0))));
+  }
+
+  @media (min-width: 1280px) {
+    gap: var(--fui-stack-gap-xl, var(--fui-stack-gap-lg, var(--fui-stack-gap-md, var(--fui-stack-gap-sm, var(--fui-stack-gap, 0)))));
+  }
+}
+
+// Align (cross-axis)
+.align-start {
+  align-items: flex-start;
+}
+
+.align-center {
+  align-items: center;
+}
+
+.align-end {
+  align-items: flex-end;
+}
+
+.align-stretch {
+  align-items: stretch;
+}
+
+.align-baseline {
+  align-items: baseline;
+}
+
+// Justify (main-axis)
+.justify-start {
+  justify-content: flex-start;
+}
+
+.justify-center {
+  justify-content: center;
+}
+
+.justify-end {
+  justify-content: flex-end;
+}
+
+.justify-between {
+  justify-content: space-between;
+}
+
+// Wrap
+.wrap {
+  flex-wrap: wrap;
+}
+
+// Separator
+.separator {
+  flex-shrink: 0;
+  background-color: var(--fui-border, $fui-border);
+
+  &[data-orientation="horizontal"] {
+    height: 1px;
+    width: 100%;
+  }
+
+  &[data-orientation="vertical"] {
+    width: 1px;
+    align-self: stretch;
+  }
+}

package/src/components/Stack/Stack.stories.tsx

@@ -0,0 +1,73 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Stack } from '.';
+
+/**
+ * Stack is a flexbox layout primitive for arranging children in rows or
+ * columns with consistent spacing. Direction and gap accept tokens, numbers,
+ * or responsive objects.
+ */
+const meta = {
+  title: 'Layout/Stack',
+  component: Stack,
+  tags: ['autodocs', 'canonical'],
+  parameters: {
+    docs: {
+      description: {
+        component: 'Flexbox layout component for arranging children in rows or columns.',
+      },
+    },
+  },
+  argTypes: {
+    align: {
+      control: 'select',
+      options: ['start', 'center', 'end', 'stretch', 'baseline'],
+      description: 'Cross-axis alignment',
+    },
+    justify: {
+      control: 'select',
+      options: ['start', 'center', 'end', 'between'],
+      description: 'Main-axis alignment',
+    },
+    as: {
+      control: 'select',
+      options: ['div', 'section', 'nav', 'article', 'aside', 'header', 'footer', 'main', 'ul', 'ol'],
+      description: 'HTML element to render',
+    },
+    wrap: { control: 'boolean', description: 'Allow items to wrap' },
+  },
+  args: {
+    direction: 'column',
+    gap: 'md',
+    children: (
+      <>
+        <div style={{ padding: 8, background: 'var(--fui-bg-secondary)' }}>Item 1</div>
+        <div style={{ padding: 8, background: 'var(--fui-bg-secondary)' }}>Item 2</div>
+        <div style={{ padding: 8, background: 'var(--fui-bg-secondary)' }}>Item 3</div>
+      </>
+    ),
+  },
+} satisfies Meta<typeof Stack>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Vertical: Story = {
+  args: { direction: 'column', gap: 'sm' },
+};
+
+export const Horizontal: Story = {
+  args: { direction: 'row', gap: 'sm' },
+};
+
+export const NumericGap: Story = {
+  args: { direction: 'row', gap: 4 },
+};
+
+export const WithSeparator: Story = {
+  args: { direction: 'column', gap: 'md', separator: true },
+};
+
+export const SemanticElement: Story = {
+  args: { as: 'nav', direction: 'row', gap: 'md' },
+};

package/src/components/Stack/index.tsx

@@ -0,0 +1,207 @@
+import * as React from 'react';
+import styles from './Stack.module.scss';
+
+type Direction = 'row' | 'column';
+type GapToken = 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+/** Gap accepts string tokens or numbers (1-8) mapping to the spacing scale */
+type GapScale = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8;
+type Gap = GapToken | GapScale;
+
+/** Responsive value — either a single value or per-breakpoint overrides */
+export interface ResponsiveDirection {
+  /** Default (mobile-first) */
+  base?: Direction;
+  /** ≥640px */
+  sm?: Direction;
+  /** ≥768px */
+  md?: Direction;
+  /** ≥1024px */
+  lg?: Direction;
+  /** ≥1280px */
+  xl?: Direction;
+}
+
+/** Responsive gap value */
+export interface ResponsiveGap {
+  /** Default (mobile-first) */
+  base?: GapToken;
+  /** ≥640px */
+  sm?: GapToken;
+  /** ≥768px */
+  md?: GapToken;
+  /** ≥1024px */
+  lg?: GapToken;
+  /** ≥1280px */
+  xl?: GapToken;
+}
+
+/**
+ * Flexbox layout component for vertical or horizontal stacking with consistent spacing.
+ * @see https://usefragments.com/components/stack
+ */
+export interface StackProps extends Omit<React.HTMLAttributes<HTMLElement>, 'children' | 'style' | 'className'> {
+  children: React.ReactNode;
+  /**
+   * Stack direction.
+   * - A string for fixed direction: `"row"` or `"column"`
+   * - An object for responsive direction: `{ base: "column", md: "row" }`
+   */
+  direction?: Direction | ResponsiveDirection;
+  /**
+   * Gap between items.
+   * - A string for fixed gap: `"sm"`, `"md"`, etc.
+   * - An object for responsive gap: `{ base: "sm", md: "lg" }`
+   */
+  gap?: Gap | ResponsiveGap;
+  align?: 'start' | 'center' | 'end' | 'stretch' | 'baseline';
+  justify?: 'start' | 'center' | 'end' | 'between';
+  wrap?: boolean;
+  /**
+   * Render a separator between each child.
+   * - `true` renders a default 1px border line
+   * - A ReactNode renders custom content between children
+   */
+  separator?: boolean | React.ReactNode;
+  as?: 'div' | 'section' | 'nav' | 'article' | 'aside' | 'header' | 'footer' | 'main' | 'ul' | 'ol';
+  className?: string;
+  style?: React.CSSProperties;
+}
+
+function isResponsiveDirection(
+  direction: StackProps['direction']
+): direction is ResponsiveDirection {
+  return typeof direction === 'object' && direction !== null;
+}
+
+function isResponsiveGap(gap: StackProps['gap']): gap is ResponsiveGap {
+  return typeof gap === 'object' && gap !== null;
+}
+
+function isNumericGap(gap: StackProps['gap']): gap is GapScale {
+  return typeof gap === 'number';
+}
+
+const StackRoot = React.forwardRef<HTMLElement, StackProps>(
+  function Stack(
+    {
+      children,
+      direction = 'column',
+      gap = 'md',
+      align,
+      justify,
+      wrap = false,
+      separator,
+      as: Component = 'div',
+      className,
+      style,
+      ...htmlProps
+    },
+    ref
+  ) {
+    let directionClass: string;
+    let gapClass: string | false;
+    let inlineStyle: React.CSSProperties | undefined;
+
+    // Handle responsive direction
+    if (isResponsiveDirection(direction)) {
+      directionClass = styles.directionResponsive;
+      const vars: Record<string, string> = {};
+      if (direction.base) vars['--fui-stack-direction'] = direction.base;
+      if (direction.sm) vars['--fui-stack-direction-sm'] = direction.sm;
+      if (direction.md) vars['--fui-stack-direction-md'] = direction.md;
+      if (direction.lg) vars['--fui-stack-direction-lg'] = direction.lg;
+      if (direction.xl) vars['--fui-stack-direction-xl'] = direction.xl;
+      inlineStyle = vars as unknown as React.CSSProperties;
+    } else {
+      directionClass = styles[direction];
+    }
+
+    // Handle responsive gap
+    if (isResponsiveGap(gap)) {
+      gapClass = styles.gapResponsive;
+      const gapVars: Record<string, string> = {};
+      if (gap.base && gap.base !== 'none') gapVars['--fui-stack-gap'] = `var(--fui-space-${gapToSpace(gap.base)})`;
+      if (gap.sm && gap.sm !== 'none') gapVars['--fui-stack-gap-sm'] = `var(--fui-space-${gapToSpace(gap.sm)})`;
+      if (gap.md && gap.md !== 'none') gapVars['--fui-stack-gap-md'] = `var(--fui-space-${gapToSpace(gap.md)})`;
+      if (gap.lg && gap.lg !== 'none') gapVars['--fui-stack-gap-lg'] = `var(--fui-space-${gapToSpace(gap.lg)})`;
+      if (gap.xl && gap.xl !== 'none') gapVars['--fui-stack-gap-xl'] = `var(--fui-space-${gapToSpace(gap.xl)})`;
+      inlineStyle = { ...inlineStyle, ...gapVars } as React.CSSProperties;
+    } else if (isNumericGap(gap)) {
+      // Numeric gap: maps to space scale tokens (e.g. gap={2} → var(--fui-space-2))
+      gapClass = false;
+      inlineStyle = { ...inlineStyle, gap: `var(--fui-space-${gap})` } as React.CSSProperties;
+    } else {
+      gapClass = gap !== 'none' && styles[`gap-${gap}`];
+    }
+
+    const classes = [
+      styles.stack,
+      directionClass,
+      gapClass,
+      align && styles[`align-${align}`],
+      justify && styles[`justify-${justify}`],
+      wrap && styles.wrap,
+      className,
+    ]
+      .filter(Boolean)
+      .join(' ');
+
+    const mergedStyle = inlineStyle ? { ...inlineStyle, ...style } : style;
+
+    // Interleave separator between children when provided
+    let content: React.ReactNode = children;
+    if (separator) {
+      const validChildren = React.Children.toArray(children).filter(Boolean);
+      if (validChildren.length > 1) {
+        const resolvedDir = isResponsiveDirection(direction) ? (direction.base ?? 'column') : direction;
+        const separatorEl = separator === true ? (
+          <div
+            className={styles.separator}
+            data-orientation={resolvedDir === 'row' ? 'vertical' : 'horizontal'}
+            role="separator"
+          />
+        ) : separator;
+
+        const items: React.ReactNode[] = [];
+        validChildren.forEach((child, idx) => {
+          items.push(child);
+          if (idx < validChildren.length - 1) {
+            const childKey = React.isValidElement(child) && child.key != null ? child.key : `idx-${idx}`;
+            items.push(
+              <React.Fragment key={`sep-${childKey}`}>{separatorEl}</React.Fragment>
+            );
+          }
+        });
+        content = items;
+      }
+    }
+
+    return (
+      <Component
+        {...htmlProps}
+        ref={ref as React.Ref<never>}
+        className={classes}
+        style={mergedStyle}
+      >
+        {content}
+      </Component>
+    );
+  }
+);
+
+// Map gap prop values to space variable numbers
+function gapToSpace(gap: GapToken): string {
+  const map: Record<GapToken, string> = {
+    none: '0',
+    xs: '1',
+    sm: '2',
+    md: '3',
+    lg: '4',
+    xl: '6',
+  };
+  return map[gap];
+}
+
+export const Stack = Object.assign(StackRoot, {
+  Root: StackRoot,
+});

package/src/components/Switch/Switch.stories.tsx

@@ -0,0 +1,59 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Switch } from '.';
+
+/**
+ * Switch is a binary on/off control for settings and preferences. It supports
+ * controlled and uncontrolled checked state, an optional label, helper text,
+ * and three sizes.
+ */
+const meta = {
+  title: 'Forms/Switch',
+  component: Switch,
+  tags: ['autodocs', 'canonical'],
+  parameters: {
+    docs: {
+      description: {
+        component: 'Binary on/off switch for settings and preferences.',
+      },
+    },
+  },
+  argTypes: {
+    size: {
+      control: 'select',
+      options: ['sm', 'md', 'lg'],
+      description: 'Size variant',
+    },
+    disabled: { control: 'boolean', description: 'Disable the switch' },
+    readOnly: { control: 'boolean', description: 'Prevent the user from toggling' },
+    required: { control: 'boolean', description: 'Mark the switch as required' },
+    defaultChecked: { control: 'boolean', description: 'Default checked state (uncontrolled)' },
+  },
+  args: { label: 'Enable notifications', size: 'md', defaultChecked: false },
+} satisfies Meta<typeof Switch>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: { label: 'Enable notifications' },
+};
+
+export const Checked: Story = {
+  args: { label: 'Auto-save', defaultChecked: true },
+};
+
+export const WithHelperText: Story = {
+  args: {
+    label: 'Marketing emails',
+    helperText: 'Receive occasional product updates and offers.',
+  },
+};
+
+export const Small: Story = {
+  args: { label: 'Compact mode', size: 'sm', defaultChecked: true },
+};
+
+export const Disabled: Story = {
+  args: { label: 'Locked setting', disabled: true, defaultChecked: true },
+};