@usefragments/ui 1.0.0

package/src/components/Badge/Badge.module.scss

@@ -0,0 +1,146 @@
+@use "../../tokens/variables" as *;
+@use "../../tokens/mixins" as *;
+
+// Local component tokens
+$fui-badge-dot-sm: 5px !default;
+$fui-badge-dot-md: 6px !default;
+
+.badge {
+  display: inline-flex;
+  align-items: center;
+  width: max-content;
+  gap: var(--fui-space-1, $fui-space-1);
+  border: 0;
+  border-radius: var(--fui-badge-radius, var(--fui-radius-lg, #{$fui-radius-lg}));
+  font-family: var(--fui-font-sans, $fui-font-sans);
+  font-weight: var(--fui-font-weight-semibold, $fui-font-weight-semibold);
+  line-height: 1;
+  white-space: nowrap;
+}
+
+// Sizes
+.sm {
+  padding: var(--fui-space-0-5, $fui-space-0-5) var(--fui-space-1, $fui-space-1);
+  font-size: var(--fui-font-size-2xs, $fui-font-size-2xs);
+}
+
+.md {
+  padding: var(--fui-space-1, $fui-space-1) var(--fui-space-1, $fui-space-1);
+  font-size: var(--fui-font-size-xs, $fui-font-size-xs);
+}
+
+.lg {
+  padding: var(--fui-space-1, $fui-space-1) var(--fui-space-2, $fui-space-2);
+  font-size: var(--fui-font-size-sm, $fui-font-size-sm);
+}
+
+// Variants
+.default {
+  background-color: var(--fui-bg-tertiary, $fui-bg-tertiary);
+  color: var(--fui-text-secondary, $fui-text-secondary);
+}
+
+.success {
+  background: var(--fui-color-success-bg, $fui-color-success-bg);
+  color: var(--fui-color-success-text, $fui-color-success-text);
+}
+
+.warning {
+  background: var(--fui-color-warning-bg, $fui-color-warning-bg);
+  color: var(--fui-color-warning-text, $fui-color-warning-text);
+}
+
+.error {
+  background: var(--fui-color-danger-bg, $fui-color-danger-bg);
+  color: var(--fui-color-danger-text, $fui-color-danger-text);
+}
+
+.info {
+  background: var(--fui-color-info-bg, $fui-color-info-bg);
+  color: var(--fui-color-info-text, $fui-color-info-text);
+}
+
+.outline {
+  background-color: transparent;
+  color: var(--fui-text-primary, $fui-text-primary);
+  border: 1px solid var(--fui-border-strong, $fui-border-strong);
+}
+
+// Compact hairline-bordered label for dense dashboard metadata rows.
+// Overrides the base pill radius and padding — squared corners read as
+// data metadata rather than status chrome.
+.label {
+  height: var(--fui-target-size-min, $fui-target-size-min); // 32px control floor
+  padding: 0 calc(var(--fui-space-1, $fui-space-1) - var(--fui-space-px, $fui-space-px)); // ~6px
+  border: 1px solid var(--fui-border, $fui-border);
+  border-radius: var(--fui-radius-sm, $fui-radius-sm);
+  background-color: transparent;
+  color: var(--fui-text-secondary, $fui-text-secondary);
+  font-size: var(--fui-font-size-2xs, $fui-font-size-2xs);
+  font-weight: var(--fui-font-weight-medium, $fui-font-weight-medium);
+}
+
+// Dim filter-chip chrome for toolbar segmented controls. Transparent at
+// rest, panel-surface + hairline when marked active.
+.dim {
+  height: var(--fui-button-height-sm, $fui-button-height-sm); // 32px small control height
+  padding: 0 calc(var(--fui-space-1, $fui-space-1) + var(--fui-space-0-5, $fui-space-0-5)); // ~9px
+  border: 1px solid transparent;
+  border-radius: var(--fui-radius-sm, $fui-radius-sm);
+  background-color: transparent;
+  color: var(--fui-text-secondary, $fui-text-secondary);
+  font-size: var(--fui-font-size-xs, $fui-font-size-xs);
+  font-weight: var(--fui-font-weight-medium, $fui-font-weight-medium);
+  transition:
+    color var(--fui-transition-fast, $fui-transition-fast),
+    border-color var(--fui-transition-fast, $fui-transition-fast),
+    background-color var(--fui-transition-fast, $fui-transition-fast);
+
+  &.active {
+    border-color: var(--fui-border, $fui-border);
+    background-color: var(--fui-bg-hover, $fui-bg-hover);
+    color: var(--fui-text-primary, $fui-text-primary);
+  }
+}
+
+.dot {
+  width: $fui-badge-dot-md;
+  height: $fui-badge-dot-md;
+  border-radius: 50%;
+  background-color: var(--fui-badge-dot-color, currentColor);
+  flex-shrink: 0;
+
+  .sm & {
+    width: $fui-badge-dot-sm;
+    height: $fui-badge-dot-sm;
+  }
+}
+
+.icon {
+  display: flex;
+  align-items: center;
+}
+
+// Asymmetric padding when removable — tighter on right side near the × button
+.badge:has(.remove) {
+  padding: var(--fui-space-0-5, $fui-space-0-5) var(--fui-space-1, $fui-space-1)
+    var(--fui-space-0-5, $fui-space-0-5) var(--fui-space-2, $fui-space-2);
+}
+
+.remove {
+  @include button-reset;
+  @include interactive-base;
+  @include touch-target;
+
+  margin-left: calc(-1 * var(--fui-space-0-5, $fui-space-0-5));
+  padding: 0;
+  font-size: inherit;
+  color: inherit;
+  opacity: 0.6;
+  line-height: 1;
+  border-radius: var(--fui-radius-full, $fui-radius-full);
+
+  &:hover {
+    opacity: 1;
+  }
+}

package/src/components/Badge/Badge.stories.tsx

@@ -0,0 +1,92 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { Badge } from ".";
+
+/**
+ * Badge is a compact label for status, counts, or categorization. It draws
+ * attention to metadata without dominating the layout and supports semantic
+ * variants, an optional status dot, and a removable affordance.
+ */
+const meta = {
+  title: "Display/Badge",
+  component: Badge,
+  tags: ["autodocs"],
+  parameters: {
+    docs: {
+      description: {
+        component: "Compact label for status, counts, or categorization.",
+      },
+    },
+  },
+  argTypes: {
+    variant: {
+      control: "select",
+      options: ["default", "success", "warning", "error", "info", "outline"],
+      description: "Visual style indicating severity or category",
+    },
+    size: {
+      control: "select",
+      options: ["sm", "md", "lg"],
+      description: "Badge size",
+    },
+    dot: {
+      control: "boolean",
+      description: "Show a colored dot indicator before the label",
+    },
+    announce: {
+      control: "boolean",
+      description: 'Opt into role="status" live announcement semantics',
+    },
+  },
+  args: {
+    variant: "default",
+    size: "md",
+    children: "Default",
+  },
+} satisfies Meta<typeof Badge>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: { variant: "default", children: "Default" },
+};
+
+export const Success: Story = {
+  args: { variant: "success", children: "Active" },
+};
+
+export const Error: Story = {
+  args: { variant: "error", children: "Failed" },
+};
+
+export const SemanticStatus: Story = {
+  render: () => (
+    <div style={{ display: "flex", gap: "var(--fui-space-2)", alignItems: "center" }}>
+      <Badge variant="success" size="lg">
+        Delivered
+      </Badge>
+      <Badge variant="error" size="lg">
+        Bounced
+      </Badge>
+      <Badge variant="warning" size="lg">
+        Delayed
+      </Badge>
+      <Badge variant="info" size="lg">
+        Queued
+      </Badge>
+    </div>
+  ),
+};
+
+export const WithDot: Story = {
+  args: { variant: "success", dot: true, children: "Online" },
+};
+
+export const Outline: Story = {
+  args: { variant: "outline", children: "Outline" },
+};
+
+export const Removable: Story = {
+  args: { variant: "info", children: "React", onRemove: () => {} },
+};

package/src/components/Badge/index.tsx

@@ -0,0 +1,115 @@
+"use client";
+
+import * as React from "react";
+import { Button as BaseButton } from "@base-ui/react/button";
+import styles from "./Badge.module.scss";
+
+/**
+ * Badge for status indicators, labels, and counts.
+ * @see https://usefragments.com/components/badge
+ */
+export interface BadgeProps extends React.HTMLAttributes<HTMLSpanElement> {
+  children: React.ReactNode;
+  /** Visual style variant.
+   *
+   * - `default` / semantic / `outline`: pill-shaped status badges for
+   *   tags, counts, or state.
+   * - `label`: hairline-bordered label on the shared control floor for
+   *   metadata pills inside dense dashboard rows. Pair with `dotColor`.
+   * - `dim`: transparent 32px filter-pill chrome used
+   *   for toolbar filter chips. Pair with `active` to mark the selected one.
+   * @default "default"
+   * @see https://usefragments.com/components/badge#variants */
+  variant?: "default" | "success" | "warning" | "error" | "info" | "outline" | "label" | "dim";
+  /** Badge size.
+   * @default "md" */
+  size?: "sm" | "md" | "lg";
+  /** Show a status dot before the label */
+  dot?: boolean;
+  /** Color for the leading status dot. Applies to `variant="label"` (and the
+   * generic `dot` prop). Accepts any CSS color including CSS custom properties. */
+  dotColor?: string;
+  /** Icon element rendered before the label */
+  icon?: React.ReactNode;
+  /** Marks `variant="dim"` as the currently selected filter. Has no effect on
+   * other variants. */
+  active?: boolean;
+  /** Makes the badge removable. Called when dismiss button is clicked. */
+  onRemove?: () => void;
+  /** Announce badge content as status to assistive tech (opt-in).
+   * @default false */
+  announce?: boolean;
+}
+
+const BadgeRoot = React.forwardRef<HTMLSpanElement, BadgeProps>(function Badge(
+  {
+    children,
+    variant = "default",
+    size = "md",
+    dot = false,
+    dotColor,
+    icon,
+    active = false,
+    onRemove,
+    announce = false,
+    className,
+    style,
+    "aria-label": ariaLabel,
+    role,
+    ...htmlProps
+  },
+  ref
+) {
+  const classes = [
+    styles.badge,
+    styles[size],
+    styles[variant],
+    active && variant === "dim" && styles.active,
+    className,
+  ]
+    .filter(Boolean)
+    .join(" ");
+
+  const resolvedStyle = dotColor
+    ? ({ ...style, "--fui-badge-dot-color": dotColor } as React.CSSProperties)
+    : style;
+
+  // For status badges, include the status in the aria-label if not provided
+  const effectiveAriaLabel =
+    ariaLabel ||
+    (announce && variant !== "default" && variant !== "outline"
+      ? `${variant}: ${typeof children === "string" ? children : ""}`
+      : undefined);
+
+  return (
+    <span
+      ref={ref}
+      {...htmlProps}
+      className={classes}
+      style={resolvedStyle}
+      role={role ?? (announce ? "status" : undefined)}
+      aria-label={effectiveAriaLabel}
+    >
+      {dot && <span className={styles.dot} aria-hidden="true" />}
+      {icon && (
+        <span className={styles.icon} aria-hidden="true">
+          {icon}
+        </span>
+      )}
+      <span>{children}</span>
+      {onRemove && (
+        <BaseButton
+          onClick={onRemove}
+          aria-label={`Remove ${typeof children === "string" ? children : "badge"}`}
+          className={styles.remove}
+        >
+          &times;
+        </BaseButton>
+      )}
+    </span>
+  );
+});
+
+export const Badge = Object.assign(BadgeRoot, {
+  Root: BadgeRoot,
+});

package/src/components/BentoGrid/BentoGrid.contract.json

@@ -0,0 +1,135 @@
+{
+  "$schema": "https://usefragments.com/schemas/contract.v1.json",
+  "name": "BentoGrid",
+  "description": "Asymmetric grid layout with responsive spans and built-in surface styling for bento-style feature sections",
+  "category": "layout",
+  "tags": [
+    "bento",
+    "grid",
+    "layout",
+    "responsive",
+    "feature-grid",
+    "asymmetric"
+  ],
+  "status": "stable",
+  "sourcePath": "src/components/BentoGrid/index.tsx",
+  "exportName": "BentoGrid",
+  "propsSummary": [
+    "children: node",
+    "columns: union (default: 3)",
+    "gap: none|xs|sm|md|lg|xl (default: md)",
+    "style: object"
+  ],
+  "props": {
+    "children": {
+      "type": "node",
+      "description": "BentoGrid.Item children",
+      "required": false
+    },
+    "columns": {
+      "type": "union",
+      "description": "Number of columns — auto-collapses responsively (3→2→1)",
+      "default": "3",
+      "required": false,
+      "values": [
+        "2",
+        "3",
+        "4"
+      ]
+    },
+    "gap": {
+      "type": "enum",
+      "description": "Gap between grid items, mapped to spacing tokens",
+      "default": "md",
+      "required": false,
+      "values": [
+        "none",
+        "xs",
+        "sm",
+        "md",
+        "lg",
+        "xl"
+      ]
+    },
+    "style": {
+      "type": "object",
+      "description": "",
+      "required": false
+    }
+  },
+  "usage": {
+    "when": [
+      "Asymmetric feature grids with hero + supporting items",
+      "Dashboard overviews where cards have different visual weight",
+      "Marketing pages with mixed-size content blocks",
+      "Any layout where items need per-breakpoint column/row spans"
+    ],
+    "whenNot": [
+      "Uniform grids where all items are the same size (use Grid)",
+      "Form layouts with labeled fields (use Grid)",
+      "Simple stacked content (use Stack)"
+    ],
+    "guidelines": [
+      "Use colSpan/rowSpan with responsive objects for layouts that adapt across breakpoints",
+      "The hero item typically uses colSpan={2} rowSpan={2} at lg and above",
+      "Items include built-in surface styling — no need to wrap children in Card",
+      "Grid auto-collapses: 3→2 columns below lg, all→1 column below sm",
+      "Root and Item forward DOM props (aria-*, data-*, handlers), and Item style merges with span CSS vars"
+    ],
+    "accessibility": [
+      "Grid is purely visual — it does not affect reading order or semantics",
+      "Ensure logical source order matches visual order for screen readers",
+      "Hover effects are disabled when prefers-reduced-motion is set",
+      "Border thickness increases in prefers-contrast: more mode"
+    ]
+  },
+  "examples": [
+    {
+      "name": "Default",
+      "description": "Basic 3-column uniform bento grid",
+      "code": "<BentoGrid columns={3} gap=\"md\">\n  <BentoGrid.Item>Item 1</BentoGrid.Item>\n  <BentoGrid.Item>Item 2</BentoGrid.Item>\n  <BentoGrid.Item>Item 3</BentoGrid.Item>\n  <BentoGrid.Item>Item 4</BentoGrid.Item>\n  <BentoGrid.Item>Item 5</BentoGrid.Item>\n  <BentoGrid.Item>Item 6</BentoGrid.Item>\n</BentoGrid>"
+    },
+    {
+      "name": "Hero Layout",
+      "description": "2×2 hero item with 4 supporting items in a 3-column grid",
+      "code": "<BentoGrid columns={3} gap=\"md\">\n  <BentoGrid.Item colSpan={{ base: 1, lg: 2 }} rowSpan={{ base: 1, lg: 2 }}>\n    Hero content\n  </BentoGrid.Item>\n  <BentoGrid.Item>Item 2</BentoGrid.Item>\n  <BentoGrid.Item>Item 3</BentoGrid.Item>\n  <BentoGrid.Item>Item 4</BentoGrid.Item>\n  <BentoGrid.Item>Item 5</BentoGrid.Item>\n</BentoGrid>"
+    },
+    {
+      "name": "Two Column",
+      "description": "2-column bento with a wide item",
+      "code": "<BentoGrid columns={2} gap=\"md\">\n  <BentoGrid.Item>Item 1</BentoGrid.Item>\n  <BentoGrid.Item>Item 2</BentoGrid.Item>\n  <BentoGrid.Item colSpan={2}>Wide item</BentoGrid.Item>\n  <BentoGrid.Item>Item 4</BentoGrid.Item>\n  <BentoGrid.Item>Item 5</BentoGrid.Item>\n</BentoGrid>"
+    },
+    {
+      "name": "Full-Width Banner",
+      "description": "3-column grid with a full-width item spanning all columns",
+      "code": "<BentoGrid columns={3} gap=\"md\">\n  <BentoGrid.Item>Item 1</BentoGrid.Item>\n  <BentoGrid.Item>Item 2</BentoGrid.Item>\n  <BentoGrid.Item>Item 3</BentoGrid.Item>\n  <BentoGrid.Item colSpan={3}>Full-width banner</BentoGrid.Item>\n</BentoGrid>"
+    }
+  ],
+  "relations": [
+    {
+      "component": "Grid",
+      "relationship": "alternative",
+      "note": "Use Grid for uniform layouts; BentoGrid for asymmetric spans with built-in surfaces"
+    },
+    {
+      "component": "Card",
+      "relationship": "sibling",
+      "note": "BentoGrid.Item has built-in surface styling similar to Card"
+    }
+  ],
+  "contract": {
+    "propsSummary": [
+      "columns: 2|3|4 (default: 3) — auto-collapses responsively",
+      "gap: none|xs|sm|md|lg|xl (default: md)",
+      "BentoGrid.Item colSpan: 1|2|3 | { base, sm, md, lg, xl }",
+      "BentoGrid.Item rowSpan: 1|2|3 | { base, sm, md, lg, xl }",
+      "BentoGrid and BentoGrid.Item forward div DOM props; Item style is merged with generated span vars"
+    ]
+  },
+  "provenance": {
+    "source": "migrated",
+    "verified": false,
+    "frameworkSupport": "native",
+    "extractedAt": "2026-03-13T23:18:52.407Z"
+  }
+}

package/src/components/BentoGrid/BentoGrid.module.scss

@@ -0,0 +1,179 @@
+@use "../../tokens/variables" as *;
+@use "../../tokens/mixins" as *;
+
+// ============================================
+// BentoGrid Container
+// ============================================
+
+.grid {
+  display: grid;
+  width: 100%;
+  grid-auto-flow: dense;
+}
+
+// ============================================
+// Column counts
+// ============================================
+
+.columns2 {
+  grid-template-columns: repeat(2, 1fr);
+}
+.columns3 {
+  grid-template-columns: repeat(3, 1fr);
+}
+.columns4 {
+  grid-template-columns: repeat(4, 1fr);
+}
+
+// ============================================
+// Responsive collapse
+// ============================================
+
+@include below-lg {
+  .columns3,
+  .columns4 {
+    grid-template-columns: repeat(2, 1fr);
+  }
+}
+
+@include below-sm {
+  .columns2,
+  .columns3,
+  .columns4 {
+    grid-template-columns: 1fr;
+  }
+}
+
+// ============================================
+// Gap
+// ============================================
+
+.gapNone {
+  gap: 0;
+}
+.gapXs {
+  gap: var(--fui-space-1, $fui-space-1);
+}
+.gapSm {
+  gap: var(--fui-space-2, $fui-space-2);
+}
+.gapMd {
+  gap: var(--fui-space-3, $fui-space-3);
+}
+.gapLg {
+  gap: var(--fui-space-4, $fui-space-4);
+}
+.gapXl {
+  gap: var(--fui-space-6, $fui-space-6);
+}
+
+// ============================================
+// BentoGrid Item
+// ============================================
+
+.item {
+  @include surface-elevated;
+
+  min-width: 0;
+  padding: var(--fui-space-2, $fui-space-2);
+  transition:
+    box-shadow var(--fui-transition-fast, $fui-transition-fast),
+    border-color var(--fui-transition-fast, $fui-transition-fast),
+    transform var(--fui-transition-fast, $fui-transition-fast);
+
+  &:hover {
+    border-color: var(--fui-border-strong, $fui-border-strong);
+    box-shadow: var(--fui-shadow-md, $fui-shadow-md);
+    transform: translateY(-2px);
+  }
+
+  // ---- Responsive span cascade ----
+  --_col-span: var(--bento-col-span, 1);
+  --_row-span: var(--bento-row-span, 1);
+
+  grid-column: span var(--_col-span);
+  grid-row: span var(--_row-span);
+
+  @include breakpoint-sm {
+    --_col-span: var(--bento-col-span-sm, var(--bento-col-span, 1));
+    --_row-span: var(--bento-row-span-sm, var(--bento-row-span, 1));
+  }
+
+  @include breakpoint-md {
+    --_col-span: var(--bento-col-span-md, var(--bento-col-span-sm, var(--bento-col-span, 1)));
+    --_row-span: var(--bento-row-span-md, var(--bento-row-span-sm, var(--bento-row-span, 1)));
+  }
+
+  @include breakpoint-lg {
+    --_col-span: var(
+      --bento-col-span-lg,
+      var(--bento-col-span-md, var(--bento-col-span-sm, var(--bento-col-span, 1)))
+    );
+    --_row-span: var(
+      --bento-row-span-lg,
+      var(--bento-row-span-md, var(--bento-row-span-sm, var(--bento-row-span, 1)))
+    );
+  }
+
+  @include breakpoint-xl {
+    --_col-span: var(
+      --bento-col-span-xl,
+      var(
+        --bento-col-span-lg,
+        var(--bento-col-span-md, var(--bento-col-span-sm, var(--bento-col-span, 1)))
+      )
+    );
+    --_row-span: var(
+      --bento-row-span-xl,
+      var(
+        --bento-row-span-lg,
+        var(--bento-row-span-md, var(--bento-row-span-sm, var(--bento-row-span, 1)))
+      )
+    );
+  }
+}
+
+// ============================================
+// Accessibility: Reduced Motion
+// ============================================
+
+@media (prefers-reduced-motion: reduce) {
+  .item {
+    transition: none;
+
+    &:hover {
+      transform: none;
+    }
+  }
+}
+
+// ============================================
+// Accessibility: High Contrast Mode
+// ============================================
+
+@media (prefers-contrast: more) {
+  .item {
+    border-width: 2px;
+    border-color: var(--fui-text-primary, $fui-text-primary);
+  }
+}
+
+// ============================================
+// Subgrid — item children align to parent tracks
+// ============================================
+
+.subgridRows {
+  display: grid;
+  grid-template-rows: subgrid;
+}
+
+.subgridColumns {
+  display: grid;
+  grid-template-columns: subgrid;
+}
+
+.subgridBoth {
+  display: grid;
+  grid-template-rows: subgrid;
+  grid-template-columns: subgrid;
+}