@usefragments/ui 1.0.0

package/src/components/ButtonGroup/ButtonGroup.contract.json

@@ -0,0 +1,140 @@
+{
+  "$schema": "https://usefragments.com/schemas/contract.v1.json",
+  "name": "ButtonGroup",
+  "description": "Groups related buttons together with consistent spacing and alignment. Useful for action bars, toolbars, and related button sets.",
+  "category": "forms",
+  "tags": [
+    "button",
+    "group",
+    "toolbar",
+    "actions",
+    "layout"
+  ],
+  "status": "stable",
+  "sourcePath": "src/components/ButtonGroup/index.tsx",
+  "exportName": "ButtonGroup",
+  "propsSummary": [
+    "children: node (required)",
+    "gap: none|xs|sm|md (default: sm)",
+    "wrap: boolean (default: false)",
+    "align: start|center|end"
+  ],
+  "props": {
+    "children": {
+      "type": "node",
+      "description": "Button elements to group together",
+      "required": true
+    },
+    "gap": {
+      "type": "enum",
+      "description": "Spacing between buttons",
+      "default": "sm",
+      "required": false,
+      "values": [
+        "none",
+        "xs",
+        "sm",
+        "md"
+      ]
+    },
+    "wrap": {
+      "type": "boolean",
+      "description": "Allow buttons to wrap to next line",
+      "default": "false",
+      "required": false
+    },
+    "align": {
+      "type": "enum",
+      "description": "Alignment of buttons",
+      "required": false,
+      "values": [
+        "start",
+        "center",
+        "end"
+      ]
+    }
+  },
+  "usage": {
+    "when": [
+      "Grouping related actions together",
+      "Creating toolbars or action bars",
+      "Form submit/cancel button pairs",
+      "Pagination controls"
+    ],
+    "whenNot": [
+      "Unrelated buttons (use Stack instead)",
+      "Navigation links (use nav element)",
+      "Single button (no grouping needed)"
+    ],
+    "guidelines": [
+      "Keep button groups focused on related actions",
+      "Use consistent button variants within a group",
+      "Consider visual hierarchy - primary action should stand out",
+      "Limit to 2-4 buttons per group for clarity",
+      "Pass role/aria-label/id/data-* directly to ButtonGroup when you need semantic grouping hooks"
+    ],
+    "accessibility": [
+      "Group provides semantic relationship between buttons",
+      "Each button remains individually focusable",
+      "Consider using role=\"group\" with aria-label for screen readers"
+    ]
+  },
+  "examples": [
+    {
+      "name": "Default",
+      "description": "Basic button group with default spacing",
+      "code": "<ButtonGroup>\n  <Button variant=\"secondary\">Cancel</Button>\n  <Button variant=\"primary\">Save</Button>\n</ButtonGroup>"
+    },
+    {
+      "name": "Gap Variants",
+      "description": "Different spacing options",
+      "code": "<div style={{ display: 'flex', flexDirection: 'column', gap: '16px' }}>\n  <ButtonGroup gap=\"none\">\n    <Button variant=\"secondary\" size=\"sm\">None</Button>\n    <Button variant=\"secondary\" size=\"sm\">Gap</Button>\n  </ButtonGroup>\n  <ButtonGroup gap=\"xs\">\n    <Button variant=\"secondary\" size=\"sm\">XS</Button>\n    <Button variant=\"secondary\" size=\"sm\">Gap</Button>\n  </ButtonGroup>\n  <ButtonGroup gap=\"sm\">\n    <Button variant=\"secondary\" size=\"sm\">SM</Button>\n    <Button variant=\"secondary\" size=\"sm\">Gap</Button>\n  </ButtonGroup>\n  <ButtonGroup gap=\"md\">\n    <Button variant=\"secondary\" size=\"sm\">MD</Button>\n    <Button variant=\"secondary\" size=\"sm\">Gap</Button>\n  </ButtonGroup>\n</div>"
+    },
+    {
+      "name": "Alignment",
+      "description": "Different alignment options",
+      "code": "<div style={{ display: 'flex', flexDirection: 'column', gap: '16px', width: '300px' }}>\n  <ButtonGroup align=\"start\">\n    <Button variant=\"secondary\" size=\"sm\">Start</Button>\n    <Button variant=\"secondary\" size=\"sm\">Aligned</Button>\n  </ButtonGroup>\n  <ButtonGroup align=\"center\">\n    <Button variant=\"secondary\" size=\"sm\">Center</Button>\n    <Button variant=\"secondary\" size=\"sm\">Aligned</Button>\n  </ButtonGroup>\n  <ButtonGroup align=\"end\">\n    <Button variant=\"secondary\" size=\"sm\">End</Button>\n    <Button variant=\"secondary\" size=\"sm\">Aligned</Button>\n  </ButtonGroup>\n</div>"
+    },
+    {
+      "name": "Form Actions",
+      "description": "Common pattern for form submit/cancel",
+      "code": "<ButtonGroup align=\"end\" role=\"group\" aria-label=\"Form actions\">\n  <Button variant=\"ghost\">Cancel</Button>\n  <Button variant=\"primary\">Submit</Button>\n</ButtonGroup>"
+    }
+  ],
+  "relations": [
+    {
+      "component": "Button",
+      "relationship": "child",
+      "note": "ButtonGroup contains Button components"
+    },
+    {
+      "component": "Stack",
+      "relationship": "alternative",
+      "note": "Use Stack for more general layout needs"
+    }
+  ],
+  "contract": {
+    "propsSummary": [
+      "children: ReactNode - buttons to group",
+      "gap: none|xs|sm|md - spacing between buttons",
+      "wrap: boolean - allow wrapping",
+      "align: start|center|end - alignment",
+      "Pass-through DOM props supported on root (id, role, aria-*, data-*, handlers)"
+    ],
+    "a11yRules": [
+      "A11Y_GROUP_LABEL"
+    ]
+  },
+  "ai": {
+    "compositionPattern": "compound",
+    "subComponents": [
+      "Root"
+    ]
+  },
+  "provenance": {
+    "source": "migrated",
+    "verified": false,
+    "frameworkSupport": "native",
+    "extractedAt": "2026-03-13T23:18:51.693Z"
+  }
+}

package/src/components/ButtonGroup/ButtonGroup.module.scss

@@ -0,0 +1,61 @@
+@use "../../tokens/variables" as *;
+
+.group {
+  display: flex;
+  flex-direction: row;
+}
+
+// Gap sizes
+.gapNone {
+  gap: 0;
+
+  > * {
+    position: relative;
+  }
+
+  > *:not(:first-child) {
+    margin-left: -1px;
+    border-top-left-radius: 0;
+    border-bottom-left-radius: 0;
+  }
+
+  > *:not(:last-child) {
+    border-top-right-radius: 0;
+    border-bottom-right-radius: 0;
+  }
+
+  > *:hover,
+  > *:focus-visible {
+    z-index: 1;
+  }
+}
+
+.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);
+}
+
+// Wrap
+.wrap {
+  flex-wrap: wrap;
+}
+
+// Alignment
+.align-start {
+  justify-content: flex-start;
+}
+
+.align-center {
+  justify-content: center;
+}
+
+.align-end {
+  justify-content: flex-end;
+}

package/src/components/ButtonGroup/ButtonGroup.stories.tsx

@@ -0,0 +1,97 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { ButtonGroup } from '.';
+import { Button } from '../Button';
+
+/**
+ * ButtonGroup groups related buttons together with consistent spacing and
+ * alignment. Use it for action bars, toolbars, and form submit/cancel pairs.
+ * It expects Button children.
+ */
+const meta = {
+  title: 'Forms/ButtonGroup',
+  component: ButtonGroup,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component: 'Groups related buttons together with consistent spacing and alignment.',
+      },
+    },
+  },
+  argTypes: {
+    gap: {
+      control: 'select',
+      options: ['none', 'xs', 'sm', 'md'],
+      description: 'Spacing between buttons',
+    },
+    align: {
+      control: 'select',
+      options: ['start', 'center', 'end'],
+      description: 'Alignment of buttons',
+    },
+    wrap: {
+      control: 'boolean',
+      description: 'Allow buttons to wrap to next line',
+    },
+  },
+  args: {
+    gap: 'sm',
+    children: (
+      <>
+        <Button variant="secondary">Cancel</Button>
+        <Button variant="primary">Save</Button>
+      </>
+    ),
+  },
+} satisfies Meta<typeof ButtonGroup>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  render: () => (
+    <ButtonGroup>
+      <Button variant="secondary">Cancel</Button>
+      <Button variant="primary">Save</Button>
+    </ButtonGroup>
+  ),
+};
+
+export const Tight: Story = {
+  render: () => (
+    <ButtonGroup gap="none">
+      <Button variant="secondary" size="sm">
+        Bold
+      </Button>
+      <Button variant="secondary" size="sm">
+        Italic
+      </Button>
+      <Button variant="secondary" size="sm">
+        Underline
+      </Button>
+    </ButtonGroup>
+  ),
+};
+
+export const AlignedEnd: Story = {
+  render: () => (
+    <ButtonGroup align="end">
+      <Button variant="secondary" size="sm">
+        End
+      </Button>
+      <Button variant="secondary" size="sm">
+        Aligned
+      </Button>
+    </ButtonGroup>
+  ),
+};
+
+export const FormActions: Story = {
+  render: () => (
+    <ButtonGroup align="end" role="group" aria-label="Form actions">
+      <Button variant="ghost">Cancel</Button>
+      <Button variant="primary">Submit</Button>
+    </ButtonGroup>
+  ),
+};

package/src/components/ButtonGroup/index.tsx

@@ -0,0 +1,34 @@
+import * as React from "react";
+import styles from "./ButtonGroup.module.scss";
+
+export interface ButtonGroupProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "children"> {
+  children: React.ReactNode;
+  gap?: "none" | "xs" | "sm" | "md";
+  wrap?: boolean;
+  align?: "start" | "center" | "end";
+}
+
+const ButtonGroupRoot = React.forwardRef<HTMLDivElement, ButtonGroupProps>(function ButtonGroup(
+  { children, gap = "sm", wrap = false, align, className, ...htmlProps },
+  ref
+) {
+  const classes = [
+    styles.group,
+    gap === "none" ? styles.gapNone : styles[`gap-${gap}`],
+    wrap && styles.wrap,
+    align && styles[`align-${align}`],
+    className,
+  ]
+    .filter(Boolean)
+    .join(" ");
+
+  return (
+    <div ref={ref} {...htmlProps} className={classes}>
+      {children}
+    </div>
+  );
+});
+
+export const ButtonGroup = Object.assign(ButtonGroupRoot, {
+  Root: ButtonGroupRoot,
+});

package/src/components/Card/Card.contract.json

@@ -0,0 +1,170 @@
+{
+  "$schema": "https://usefragments.com/schemas/contract.v1.json",
+  "name": "Card",
+  "description": "Container for grouping related content",
+  "category": "layout",
+  "tags": ["container", "layout", "surface"],
+  "status": "stable",
+  "sourcePath": "src/components/Card/index.tsx",
+  "exportName": "Card",
+  "propsSummary": [
+    "children: node (required)",
+    "variant: default|outlined|outline|elevated|stat|panel (default: default)",
+    "padding: none|sm|md|lg (default: md)",
+    "as: article|div|section (default: article)",
+    "style: object"
+  ],
+  "props": {
+    "children": {
+      "type": "node",
+      "description": "Card content - use Card.Header, Card.Body, Card.Footer sub-components",
+      "required": true
+    },
+    "variant": {
+      "type": "enum",
+      "description": "Visual style of the card surface",
+      "default": "default",
+      "required": false,
+      "values": ["default", "outlined", "outline", "elevated", "stat", "panel"],
+      "constraints": [
+        "Use \"elevated\" sparingly to maintain visual hierarchy",
+        "Use \"stat\" for compact dashboard metric tiles",
+        "Use \"panel\" with Card.Header divided and padding=\"none\" for dashboard panels"
+      ]
+    },
+    "padding": {
+      "type": "enum",
+      "description": "Internal padding size",
+      "default": "md",
+      "required": false,
+      "values": ["none", "sm", "md", "lg"]
+    },
+    "as": {
+      "type": "enum",
+      "description": "Semantic HTML element for the card root",
+      "default": "article",
+      "required": false,
+      "values": ["article", "div", "section"]
+    },
+    "style": {
+      "type": "object",
+      "description": "",
+      "required": false
+    }
+  },
+  "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 List or Sidebar patterns)"
+    ],
+    "guidelines": [
+      "Use consistent card variants within the same context",
+      "Cards in a grid should have uniform sizing",
+      "Use elevated variant sparingly for emphasis",
+      "Use stat and panel variants for dashboard surfaces so spacing, border, and radius stay consistent",
+      "If a card is clickable, provide clear hover/focus affordances and prefer explicit buttons/links inside the card"
+    ],
+    "accessibility": [
+      "Card is a semantic container (article/div/section); onClick adds keyboard and role=\"button\" behavior, but explicit Button or Link actions are preferred",
+      "Card titles should be appropriate heading levels"
+    ]
+  },
+  "examples": [
+    {
+      "name": "Default",
+      "description": "Standard quiet card surface",
+      "code": "<Card>\n  <Card.Header>\n    <Card.Title>Card Title</Card.Title>\n    <Card.Description>A brief description</Card.Description>\n  </Card.Header>\n  <Card.Body>Card content goes here.</Card.Body>\n</Card>"
+    },
+    {
+      "name": "Outlined",
+      "description": "Card with border instead of shadow",
+      "code": "<Card variant=\"outlined\">\n  <Card.Header>\n    <Card.Title>Outlined Card</Card.Title>\n  </Card.Header>\n  <Card.Body>Content with border.</Card.Body>\n</Card>"
+    },
+    {
+      "name": "Outline",
+      "description": "Card with border, using the \"outline\" alias for \"outlined\"",
+      "code": "<Card variant=\"outline\">\n  <Card.Header>\n    <Card.Title>Outline Card</Card.Title>\n  </Card.Header>\n  <Card.Body>Uses the Radix/Shadcn-style alias.</Card.Body>\n</Card>"
+    },
+    {
+      "name": "Elevated",
+      "description": "Card with prominent shadow for emphasis",
+      "code": "<Card variant=\"elevated\">\n  <Card.Header>\n    <Card.Title>Featured Item</Card.Title>\n  </Card.Header>\n  <Card.Body>Important content.</Card.Body>\n</Card>"
+    },
+    {
+      "name": "Stat",
+      "description": "Compact metric tile for dashboard grids",
+      "code": "<Card variant=\"stat\">\n  <Stack gap=\"md\">\n    <Stack gap=\"xs\">\n      <Text as=\"strong\" size=\"2xl\" weight=\"bold\" letterSpacing=\"tighter\" tabularNums>94%</Text>\n      <Text as=\"p\" size=\"sm\" color=\"secondary\">Component coverage</Text>\n    </Stack>\n    <Progress value={94} variant=\"success\" size=\"sm\" aria-label=\"Component coverage progress\" />\n  </Stack>\n</Card>"
+    },
+    {
+      "name": "Panel",
+      "description": "Dashboard panel with a divided header and body-owned spacing",
+      "code": "<Card variant=\"panel\" padding=\"none\">\n  <Card.Header divided>\n    <Card.Title>System states</Card.Title>\n  </Card.Header>\n  <Card.Body padding=\"md\">\n    Panel content\n  </Card.Body>\n</Card>"
+    },
+    {
+      "name": "Interactive",
+      "description": "Clickable card surface (root stays a semantic container)",
+      "code": "<Card as=\"section\" onClick={() => alert('Card clicked!')}>\n  <Card.Header>\n    <Card.Title>Click Me</Card.Title>\n    <Card.Description>This card is interactive</Card.Description>\n  </Card.Header>\n  <Card.Body>Click anywhere on this card.</Card.Body>\n</Card>"
+    },
+    {
+      "name": "Section Root",
+      "description": "Use the as prop to match the surrounding document semantics",
+      "code": "<Card as=\"section\" aria-labelledby=\"billing-card-title\">\n  <Card.Header>\n    <Card.Title id=\"billing-card-title\">Billing Summary</Card.Title>\n  </Card.Header>\n  <Card.Body>Section semantics can improve document structure for grouped content.</Card.Body>\n</Card>"
+    },
+    {
+      "name": "With Footer",
+      "description": "Card with header, body, and footer",
+      "code": "<Card>\n  <Card.Header>\n    <Card.Title>Card with Footer</Card.Title>\n    <Card.Description>Complete card layout</Card.Description>\n  </Card.Header>\n  <Card.Body>Main content area.</Card.Body>\n  <Card.Footer>Footer actions go here</Card.Footer>\n</Card>"
+    },
+    {
+      "name": "Content Only",
+      "description": "Card with just body content",
+      "code": "<Card>\n  <Card.Body>Just content, no header or footer.</Card.Body>\n</Card>"
+    }
+  ],
+  "relations": [
+    {
+      "component": "Grid",
+      "relationship": "parent",
+      "note": "Use Grid + Card for responsive card layouts"
+    },
+    {
+      "component": "List",
+      "relationship": "alternative",
+      "note": "Use List for linear, text-first layouts"
+    }
+  ],
+  "contract": {
+    "propsSummary": [
+      "variant: default|outlined|outline|elevated|stat|panel (default: default)",
+      "padding: none|sm|md|lg (default: md)",
+      "as: article|div|section (default: article) - card root element",
+      "onClick: (event) => void - click handler on root (adds role/button keyboard behavior)",
+      "Sub-components: Card.Header, Card.Title, Card.Description, Card.Body, Card.Footer",
+      "Card.Body padding: none|sm|md|lg - use for panel body spacing"
+    ],
+    "a11yRules": ["A11Y_CARD_HEADING", "A11Y_CARD_INTERACTIVE"]
+  },
+  "ai": {
+    "compositionPattern": "compound",
+    "subComponents": ["Header", "Title", "Description", "Body", "Footer"],
+    "requiredChildren": ["Body"],
+    "commonPatterns": [
+      "<Card><Card.Body>{content}</Card.Body></Card>",
+      "<Card><Card.Header><Card.Title>{title}</Card.Title></Card.Header><Card.Body>{content}</Card.Body></Card>",
+      "<Card><Card.Header><Card.Title>{title}</Card.Title><Card.Description>{desc}</Card.Description></Card.Header><Card.Body>{content}</Card.Body><Card.Footer>{actions}</Card.Footer></Card>"
+    ]
+  },
+  "provenance": {
+    "source": "migrated",
+    "verified": false,
+    "frameworkSupport": "native",
+    "extractedAt": "2026-03-13T23:18:51.869Z"
+  }
+}