@usefragments/ui 1.0.0

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

@@ -0,0 +1,296 @@
+@use "../../tokens/variables" as *;
+@use "../../tokens/mixins" as *;
+
+.button {
+  @include button-reset;
+  @include interactive-base;
+  @include text-base;
+
+  --_button-bg: transparent;
+  --_button-bg-hover: var(--fui-bg-hover, #{$fui-bg-hover});
+  --_button-bg-active: var(--fui-bg-active, #{$fui-bg-active});
+  --_button-border: transparent;
+  --_button-border-hover: var(--_button-border);
+  --_button-color: var(--fui-text-primary, #{$fui-text-primary});
+  --_button-shadow: none;
+  --_button-shadow-hover: var(--_button-shadow);
+  --_button-shadow-active: var(--_button-shadow);
+
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: var(--fui-space-1, $fui-space-1);
+  border: 1px solid var(--_button-border);
+  border-radius: var(--fui-button-radius, var(--fui-radius-lg, #{$fui-radius-lg}));
+  background: var(--_button-bg);
+  box-shadow: var(--_button-shadow);
+  color: var(--_button-color);
+  font-weight: var(--fui-font-weight-medium, $fui-font-weight-medium);
+  white-space: nowrap;
+  user-select: none;
+
+  &:hover:not(:disabled):not([data-disabled]) {
+    border-color: var(--_button-border-hover);
+    background: var(--_button-bg-hover);
+    box-shadow: var(--_button-shadow-hover);
+  }
+
+  &:active:not(:disabled):not([data-disabled]),
+  &[data-pressed] {
+    border-color: var(--_button-border-hover);
+    background: var(--_button-bg-active);
+    box-shadow: var(--_button-shadow-active);
+  }
+
+  &:focus-visible {
+    box-shadow:
+      0 0 0 1px
+        color-mix(in srgb, var(--fui-focus-ring-color, #{$fui-focus-ring-color}) 34%, transparent),
+      0 0 0 calc(var(--fui-focus-ring-width, #{$fui-focus-ring-width}) + 1px)
+        color-mix(in srgb, var(--fui-focus-ring-color, #{$fui-focus-ring-color}) 14%, transparent),
+      var(--_button-shadow);
+  }
+
+  &:disabled,
+  &[data-disabled] {
+    box-shadow: none;
+  }
+}
+
+// Sizes
+// Note: Button padding intentionally diverges from the control-size mixin
+// (md: space-3 vs mixin's space-4, lg: space-4 vs mixin's space-5).
+// Buttons need tighter horizontal padding than inputs for visual balance,
+// since button text is typically shorter than input content.
+.xs {
+  min-height: var(--fui-button-height-xs, $fui-button-height-xs);
+  padding: 0 var(--fui-space-1, $fui-space-1);
+  font-size: var(--fui-font-size-xs, $fui-font-size-xs);
+}
+
+.sm {
+  min-height: var(--fui-button-height-sm, $fui-button-height-sm);
+  padding: 0 var(--fui-space-2, $fui-space-2);
+  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-3, $fui-space-3);
+  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-4, $fui-space-4);
+  font-size: var(--fui-font-size-base, $fui-font-size-base);
+}
+
+// ============================================
+// Optical alignment: icon + text combinations
+// ============================================
+// Icons (SVGs) have built-in whitespace that makes symmetric padding look
+// uneven. When an icon leads or trails text, reduce padding on the icon
+// side so the content appears optically centered.
+//
+// Uses :has() + :first-child/:last-child to detect icon position without
+// JS. The negative margin pulls the icon into the padding zone, compensating
+// for the icon's inherent visual whitespace.
+
+.button:not(.icon) {
+  > svg:first-child:not(:last-child) {
+    // Leading icon: pull left to optically balance
+    margin-left: calc(var(--fui-space-1, $fui-space-1) * -0.5);
+  }
+
+  > svg:last-child:not(:first-child) {
+    // Trailing icon: pull right to optically balance
+    margin-right: calc(var(--fui-space-1, $fui-space-1) * -0.5);
+  }
+}
+
+// Variants
+.primary {
+  --_button-bg: var(--fui-button-primary-bg);
+  --_button-bg-hover: var(--fui-button-primary-bg-hover);
+  --_button-bg-active: var(--fui-button-primary-bg-active);
+  --_button-border: var(--fui-button-primary-border);
+  --_button-border-hover: var(--fui-button-primary-border-hover);
+  --_button-color: var(
+    --fui-button-primary-color,
+    var(--fui-color-on-accent, #{$fui-color-on-accent})
+  );
+  --_button-shadow: var(--fui-button-primary-shadow);
+  --_button-shadow-hover: var(--fui-button-primary-shadow);
+  --_button-shadow-active: var(--fui-button-primary-shadow-active);
+}
+
+.secondary {
+  --_button-bg: var(--fui-button-neutral-bg);
+  --_button-bg-hover: var(--fui-button-neutral-bg-hover);
+  --_button-bg-active: var(--fui-button-neutral-bg-active);
+  --_button-border: var(--fui-button-neutral-border);
+  --_button-border-hover: var(--fui-button-neutral-border-hover);
+  --_button-color: var(--fui-button-neutral-color, var(--fui-text-primary, #{$fui-text-primary}));
+  --_button-shadow: var(--fui-button-neutral-shadow);
+  --_button-shadow-hover: var(--fui-button-neutral-shadow);
+  --_button-shadow-active: var(--fui-button-neutral-shadow-active);
+}
+
+.ghost {
+  --_button-bg: transparent;
+  --_button-bg-hover: var(--fui-bg-hover, #{$fui-bg-hover});
+  --_button-bg-active: var(--fui-bg-active, #{$fui-bg-active});
+  --_button-border: transparent;
+  --_button-border-hover: transparent;
+  --_button-color: var(--fui-text-primary, #{$fui-text-primary});
+  --_button-shadow: none;
+  --_button-shadow-hover: none;
+  --_button-shadow-active: none;
+}
+
+// Link: accent-coloured, transparent background. For tertiary CTAs
+// ("View all →", "Learn more →") that should feel linkish but live in
+// button contexts. Differs from ghost (text-primary) by using accent.
+.link {
+  --_button-bg: transparent;
+  --_button-bg-hover: color-mix(
+    in srgb,
+    var(--fui-color-accent, #{$fui-color-accent}) 10%,
+    transparent
+  );
+  --_button-bg-active: color-mix(
+    in srgb,
+    var(--fui-color-accent, #{$fui-color-accent}) 18%,
+    transparent
+  );
+  --_button-border: transparent;
+  --_button-border-hover: transparent;
+  --_button-color: var(--fui-color-accent, #{$fui-color-accent});
+  --_button-shadow: none;
+  --_button-shadow-hover: none;
+  --_button-shadow-active: none;
+}
+
+.danger {
+  --_button-bg: linear-gradient(
+    to bottom,
+    color-mix(in srgb, var(--fui-color-danger, #{$fui-color-danger}) 82%, white 18%) 0%,
+    var(--fui-color-danger, #{$fui-color-danger}) 52%,
+    color-mix(in srgb, var(--fui-color-danger, #{$fui-color-danger}) 86%, black 14%) 100%
+  );
+  --_button-bg-hover: linear-gradient(
+    to bottom,
+    color-mix(in srgb, var(--fui-color-danger, #{$fui-color-danger}) 76%, white 24%) 0%,
+    color-mix(in srgb, var(--fui-color-danger, #{$fui-color-danger}) 94%, black 6%) 52%,
+    color-mix(in srgb, var(--fui-color-danger, #{$fui-color-danger}) 78%, black 22%) 100%
+  );
+  --_button-bg-active: linear-gradient(
+    to bottom,
+    color-mix(in srgb, var(--fui-color-danger, #{$fui-color-danger}) 72%, black 28%) 0%,
+    color-mix(in srgb, var(--fui-color-danger, #{$fui-color-danger}) 82%, black 18%) 100%
+  );
+  --_button-border: color-mix(
+    in srgb,
+    var(--fui-color-danger, #{$fui-color-danger}) 76%,
+    black 24%
+  );
+  --_button-border-hover: color-mix(
+    in srgb,
+    var(--fui-color-danger, #{$fui-color-danger}) 62%,
+    black 38%
+  );
+  --_button-color: color-mix(in srgb, var(--fui-color-danger, #{$fui-color-danger}) 8%, white);
+  --_button-shadow: var(--fui-button-primary-shadow);
+  --_button-shadow-hover: var(--fui-button-primary-shadow);
+  --_button-shadow-active: var(--fui-button-primary-shadow-active);
+}
+
+.outlined {
+  --_button-bg: color-mix(in srgb, var(--fui-bg-elevated, #{$fui-bg-elevated}) 42%, transparent);
+  --_button-bg-hover: var(--fui-button-neutral-bg-hover);
+  --_button-bg-active: var(--fui-button-neutral-bg-active);
+  --_button-border: var(--fui-button-neutral-border);
+  --_button-border-hover: var(--fui-button-neutral-border-hover);
+  --_button-color: var(--fui-button-neutral-color, var(--fui-text-primary, #{$fui-text-primary}));
+  --_button-shadow: inset 0 1px 0
+    light-dark(
+      color-mix(in srgb, white 72%, transparent),
+      color-mix(in srgb, white 5%, transparent)
+    );
+  --_button-shadow-hover: var(--fui-button-neutral-shadow);
+  --_button-shadow-active: var(--fui-button-neutral-shadow-active);
+}
+
+// Icon-only button (square aspect ratio)
+.icon {
+  aspect-ratio: 1;
+  padding: 0;
+
+  &.xs {
+    width: var(--fui-button-height-xs, $fui-button-height-xs);
+  }
+
+  &.sm {
+    width: var(--fui-button-height-sm, $fui-button-height-sm);
+  }
+
+  &.md {
+    width: var(--fui-button-height-md, $fui-button-height-md);
+  }
+
+  &.lg {
+    width: var(--fui-button-height-lg, $fui-button-height-lg);
+  }
+}
+
+// Full width
+.fullWidth {
+  width: 100%;
+}
+
+// ============================================
+// Accessibility: High Contrast Mode
+// ============================================
+
+// ============================================
+// Accessibility: Reduced Motion
+// ============================================
+
+@media (prefers-reduced-motion: reduce) {
+  .button {
+    transition: none;
+  }
+}
+
+// ============================================
+// Accessibility: High Contrast Mode
+// ============================================
+
+@media (prefers-contrast: more) {
+  .secondary {
+    border-width: 2px;
+    border-color: var(--fui-text-primary, $fui-text-primary);
+  }
+
+  .outlined {
+    border-width: 2px;
+    border-color: var(--fui-text-primary, $fui-text-primary);
+  }
+
+  .ghost {
+    border-width: 2px;
+
+    &:hover:not(:disabled) {
+      border-color: var(--fui-text-primary, $fui-text-primary);
+    }
+  }
+
+  .link {
+    border-width: 2px;
+
+    &:hover:not(:disabled) {
+      border-color: var(--fui-color-accent, $fui-color-accent);
+    }
+  }
+}

package/src/components/Button/Button.stories.tsx

@@ -0,0 +1,103 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { CaretDown } from "@phosphor-icons/react";
+import { Button } from ".";
+import { ButtonGroup } from "../ButtonGroup";
+import { Stack } from "../Stack";
+
+/**
+ * The Button is the canonical action primitive. Every CTA, form submit, and
+ * row action in the design system routes through it — agents should reuse it
+ * rather than hand-rolling a styled `<button>`.
+ */
+const meta = {
+  title: "Forms/Button",
+  component: Button,
+  tags: ["autodocs", "canonical"],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "Interactive element for user actions and form submissions. Prefer this over a raw <button>.",
+      },
+    },
+  },
+  argTypes: {
+    variant: {
+      control: "select",
+      options: ["primary", "secondary", "ghost", "link", "danger", "outlined", "icon"],
+      description: "Visual style variant",
+    },
+    size: {
+      control: "select",
+      options: ["xs", "sm", "md", "lg"],
+      description: "Button size",
+    },
+    icon: { control: "boolean", description: "Icon-only square layout" },
+    fullWidth: { control: "boolean", description: "Stretch to container width" },
+    disabled: { control: "boolean" },
+  },
+  args: {
+    variant: "primary",
+    size: "md",
+    children: "Save changes",
+  },
+} satisfies Meta<typeof Button>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Primary: Story = {
+  args: { variant: "primary", children: "Save changes" },
+};
+
+export const Secondary: Story = {
+  args: { variant: "secondary", children: "Cancel" },
+};
+
+export const Ghost: Story = {
+  args: { variant: "ghost", children: "Dismiss" },
+};
+
+export const Danger: Story = {
+  args: { variant: "danger", children: "Delete" },
+};
+
+export const Small: Story = {
+  args: { size: "sm", children: "Compact" },
+};
+
+export const FullWidth: Story = {
+  args: { fullWidth: true, children: "Continue" },
+};
+
+export const Disabled: Story = {
+  args: { disabled: true, children: "Unavailable" },
+};
+
+export const ReferenceChrome: Story = {
+  render: () => (
+    <Stack direction="row" gap="lg" align="center" wrap>
+      <ButtonGroup gap="none" role="group" aria-label="RSVP answer">
+        <Button variant="primary" size="lg">
+          Yes
+        </Button>
+        <Button variant="primary" size="lg" icon aria-label="More yes options">
+          <CaretDown weight="bold" />
+        </Button>
+      </ButtonGroup>
+
+      <Button variant="secondary" size="lg">
+        No
+      </Button>
+
+      <Button variant="secondary" size="lg">
+        Maybe
+      </Button>
+
+      <Button variant="secondary" size="lg">
+        Add Note
+      </Button>
+    </Stack>
+  ),
+};

package/src/components/Button/index.tsx

@@ -0,0 +1,190 @@
+"use client";
+
+import * as React from "react";
+import { Button as BaseButton } from "@base-ui/react/button";
+import { useResolvedControlSize } from "../ComponentDefaults";
+import { fragmentsCanonicalStampProps } from "../../utils/canonical-stamp";
+import styles from "./Button.module.scss";
+
+function composeEventHandlers<T extends (...args: any[]) => void>(
+  childHandler: T | undefined,
+  parentHandler: T | undefined
+) {
+  if (!childHandler) return parentHandler;
+  if (!parentHandler) return childHandler;
+  return ((...args: Parameters<T>) => {
+    childHandler(...args);
+    parentHandler(...args);
+  }) as T;
+}
+
+/**
+ * Button props.
+ * @see https://usefragments.com/components/button
+ */
+type ButtonBaseProps = {
+  children: React.ReactNode;
+  /** Visual style variant.
+   * @default "primary"
+   * @see https://usefragments.com/components/button#variants
+   * @remarks
+   * - `"link"` — accent-coloured, transparent; for tertiary CTAs like "View all →"
+   * - `"icon"` — convenience alias for outlined + icon-only layout
+   * - `"outline"` — alias for `"outlined"` */
+  variant?: "primary" | "secondary" | "ghost" | "link" | "danger" | "outlined" | "outline" | "icon";
+  /** Button size. `"xs"` is for inline row-action controls (accept/dismiss, table-row icons) where `"sm"` is too tall.
+   * @default "md"
+   * @see https://usefragments.com/components/button#sizes */
+  size?: "xs" | "sm" | "md" | "lg";
+  /** Render as icon-only button (square aspect ratio). Prefer `variant="icon"` for the default outlined icon button. */
+  icon?: boolean;
+  /** Make button full width of container */
+  fullWidth?: boolean;
+  /** Merge props onto child element instead of rendering a button. Useful for composition with Link components.
+   * @see https://usefragments.com/components/button#aschild */
+  asChild?: boolean;
+};
+
+// Button as native button element
+export interface ButtonAsButtonProps
+  extends ButtonBaseProps, Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "children"> {
+  as?: "button";
+}
+
+// Button as anchor element
+export interface ButtonAsAnchorProps
+  extends ButtonBaseProps, Omit<React.AnchorHTMLAttributes<HTMLAnchorElement>, "children"> {
+  as: "a";
+}
+
+export type ButtonProps = ButtonAsButtonProps | ButtonAsAnchorProps;
+
+const ButtonRoot = React.forwardRef<HTMLButtonElement | HTMLAnchorElement, ButtonProps>(
+  function Button(props, ref) {
+    const {
+      children,
+      variant: variantProp = "primary",
+      size: sizeProp,
+      icon = false,
+      fullWidth = false,
+      asChild = false,
+      className,
+      ...rest
+    } = props;
+
+    const size = useResolvedControlSize(sizeProp);
+    const iconOnly = icon || variantProp === "icon";
+
+    // Resolve aliases:
+    // "outline" → "outlined"
+    // "icon" → visual "outlined" + icon-only sizing
+    const variant =
+      variantProp === "outline" ? "outlined" : variantProp === "icon" ? "outlined" : variantProp;
+    const canonicalStamp = fragmentsCanonicalStampProps("Button");
+
+    const classNames = [
+      styles.button,
+      styles[size],
+      styles[variant],
+      iconOnly && styles.icon,
+      fullWidth && styles.fullWidth,
+      className,
+    ]
+      .filter(Boolean)
+      .join(" ");
+
+    // asChild: merge button styling onto child element (e.g. Next.js Link)
+    if (asChild && React.isValidElement(children)) {
+      const {
+        as: _as,
+        disabled,
+        style,
+        onClick,
+        onKeyDown,
+        ...childProps
+      } = rest as React.ButtonHTMLAttributes<HTMLButtonElement> &
+        React.AnchorHTMLAttributes<HTMLAnchorElement> & { as?: "a" | "button"; disabled?: boolean };
+      const childElement = children as React.ReactElement<Record<string, unknown>>;
+      const childElementProps = childElement.props as Record<string, unknown>;
+      const isIntrinsicButton =
+        typeof childElement.type === "string" && childElement.type === "button";
+      const isDisabled = Boolean(disabled);
+
+      const mergedProps: Record<string, unknown> = {
+        ...childProps,
+        ...canonicalStamp,
+        className: [classNames, childElementProps.className].filter(Boolean).join(" "),
+        style: {
+          ...(style as React.CSSProperties | undefined),
+          ...(childElementProps.style as React.CSSProperties | undefined),
+        },
+        ref,
+      };
+
+      if (isIntrinsicButton) {
+        mergedProps.disabled = isDisabled;
+      } else if (isDisabled) {
+        mergedProps["aria-disabled"] = true;
+        mergedProps["data-disabled"] = "";
+        mergedProps.tabIndex = -1;
+        mergedProps.onClick = (event: React.MouseEvent<HTMLElement>) => {
+          event.preventDefault();
+          event.stopPropagation();
+        };
+        mergedProps.onKeyDown = (event: React.KeyboardEvent<HTMLElement>) => {
+          if (event.key === "Enter" || event.key === " ") {
+            event.preventDefault();
+            event.stopPropagation();
+          }
+        };
+      } else {
+        mergedProps.onClick = composeEventHandlers(
+          childElementProps.onClick as ((event: React.MouseEvent<HTMLElement>) => void) | undefined,
+          onClick as ((event: React.MouseEvent<HTMLElement>) => void) | undefined
+        );
+        mergedProps.onKeyDown = composeEventHandlers(
+          childElementProps.onKeyDown as
+            | ((event: React.KeyboardEvent<HTMLElement>) => void)
+            | undefined,
+          onKeyDown as ((event: React.KeyboardEvent<HTMLElement>) => void) | undefined
+        );
+      }
+
+      return React.cloneElement(childElement, mergedProps);
+    }
+
+    // Render as anchor
+    if (props.as === "a") {
+      const { as: _as, ...anchorProps } = rest as ButtonAsAnchorProps & { as?: "a" };
+      return (
+        <a
+          ref={ref as React.Ref<HTMLAnchorElement>}
+          className={classNames}
+          {...anchorProps}
+          {...canonicalStamp}
+        >
+          {children}
+        </a>
+      );
+    }
+
+    // Render as button (default)
+    const { as: _as, ...buttonProps } = rest as ButtonAsButtonProps;
+    return (
+      <BaseButton
+        ref={ref as React.Ref<HTMLButtonElement>}
+        type={(buttonProps as ButtonAsButtonProps).type || "button"}
+        disabled={(buttonProps as ButtonAsButtonProps).disabled || false}
+        className={classNames}
+        {...buttonProps}
+        {...canonicalStamp}
+      >
+        {children}
+      </BaseButton>
+    );
+  }
+);
+
+export const Button = Object.assign(ButtonRoot, {
+  Root: ButtonRoot,
+});