@usefragments/ui 1.0.0

package/src/components/Icon/Icon.contract.json

@@ -0,0 +1,194 @@
+{
+  "$schema": "https://usefragments.com/schemas/contract.v1.json",
+  "name": "Icon",
+  "description": "Wrapper for icon components with consistent sizing and semantic colors. Provides standardized icon rendering across the design system.",
+  "category": "display",
+  "tags": [
+    "icon",
+    "visual",
+    "symbol",
+    "graphic"
+  ],
+  "status": "stable",
+  "sourcePath": "src/components/Icon/index.tsx",
+  "exportName": "Icon",
+  "propsSummary": [
+    "style: object",
+    "icon: union (required)",
+    "size: xs|sm|md|lg|xl (default: md)",
+    "weight: string (default: regular)",
+    "variant: default|primary|secondary|tertiary|accent|success|warning|error",
+    "color: primary|secondary|tertiary|accent|success|warning|error",
+    "iconProps: object"
+  ],
+  "props": {
+    "style": {
+      "type": "object",
+      "description": "",
+      "required": false
+    },
+    "icon": {
+      "type": "union",
+      "description": "Icon component to render",
+      "required": true
+    },
+    "size": {
+      "type": "enum",
+      "description": "Icon size",
+      "default": "md",
+      "required": false,
+      "values": [
+        "xs",
+        "sm",
+        "md",
+        "lg",
+        "xl"
+      ]
+    },
+    "weight": {
+      "type": "string",
+      "description": "Optional icon style/weight hint (forwarded when supported by the icon component)",
+      "default": "regular",
+      "required": false,
+      "values": [
+        "thin",
+        "light",
+        "regular",
+        "bold",
+        "fill",
+        "duotone"
+      ]
+    },
+    "variant": {
+      "type": "enum",
+      "description": "Semantic color variant",
+      "default": "default",
+      "required": false,
+      "values": [
+        "default",
+        "primary",
+        "secondary",
+        "tertiary",
+        "accent",
+        "success",
+        "warning",
+        "error"
+      ]
+    },
+    "color": {
+      "type": "enum",
+      "description": "Deprecated alias for variant",
+      "required": false,
+      "values": [
+        "primary",
+        "secondary",
+        "tertiary",
+        "accent",
+        "success",
+        "warning",
+        "error"
+      ]
+    },
+    "iconProps": {
+      "type": "object",
+      "description": "Additional props forwarded to the underlying icon component (typed from the icon prop in TypeScript)",
+      "required": false
+    }
+  },
+  "usage": {
+    "when": [
+      "Displaying UI icons alongside text or in buttons",
+      "Indicating status or state visually",
+      "Adding visual hierarchy to feature lists",
+      "Decorating cards or stats with relevant symbols"
+    ],
+    "whenNot": [
+      "Large decorative illustrations (use Image or custom SVG)",
+      "Logo display (use dedicated Logo component)",
+      "Complex graphics with multiple colors",
+      "Animated icons (use custom implementation)"
+    ],
+    "guidelines": [
+      "Use semantic color variants (success, error, warning) for status indication",
+      "Pair icons with text labels for accessibility",
+      "Match icon weight/style to surrounding text weight for visual consistency when supported by the icon package",
+      "Use consistent sizes within the same context",
+      "Use iconProps for package-specific icon options not exposed directly on the wrapper"
+    ],
+    "accessibility": [
+      "Icons are decorative by default (aria-hidden)",
+      "Always pair with visible or visually-hidden text for meaning",
+      "Do not rely on color alone to convey information",
+      "Consider using VisuallyHidden for icon-only buttons"
+    ]
+  },
+  "examples": [
+    {
+      "name": "Default",
+      "description": "Basic icon with default styling",
+      "code": "<Icon icon={Heart} />"
+    },
+    {
+      "name": "Sizes",
+      "description": "Available size options",
+      "code": "<div style={{ display: 'flex', gap: '12px', alignItems: 'center' }}>\n  <Icon icon={Star} size=\"xs\" />\n  <Icon icon={Star} size=\"sm\" />\n  <Icon icon={Star} size=\"md\" />\n  <Icon icon={Star} size=\"lg\" />\n  <Icon icon={Star} size=\"xl\" />\n</div>"
+    },
+    {
+      "name": "Semantic Colors",
+      "description": "Status and semantic color variants",
+      "code": "<div style={{ display: 'flex', gap: '12px', alignItems: 'center' }}>\n  <Icon icon={Check} variant=\"success\" />\n  <Icon icon={Warning} variant=\"warning\" />\n  <Icon icon={Warning} variant=\"error\" />\n  <Icon icon={Info} variant=\"accent\" />\n</div>"
+    },
+    {
+      "name": "Weights",
+      "description": "Icon weight/style options",
+      "code": "<div style={{ display: 'flex', gap: '12px', alignItems: 'center' }}>\n  <Icon icon={Heart} weight=\"thin\" />\n  <Icon icon={Heart} weight=\"light\" />\n  <Icon icon={Heart} weight=\"regular\" />\n  <Icon icon={Heart} weight=\"bold\" />\n  <Icon icon={Heart} weight=\"fill\" />\n  <Icon icon={Heart} weight=\"duotone\" />\n</div>"
+    },
+    {
+      "name": "Advanced Icon Props",
+      "description": "Forward extra icon-package-specific props through iconProps",
+      "code": "<Icon icon={Heart} iconProps={{ mirrored: true }} />"
+    }
+  ],
+  "relations": [
+    {
+      "component": "Button",
+      "relationship": "child",
+      "note": "Use inside icon-only buttons with VisuallyHidden label"
+    },
+    {
+      "component": "VisuallyHidden",
+      "relationship": "sibling",
+      "note": "Pair with VisuallyHidden for accessible icon-only elements"
+    },
+    {
+      "component": "Badge",
+      "relationship": "child",
+      "note": "Can be used as badge icon prop"
+    }
+  ],
+  "contract": {
+    "propsSummary": [
+      "icon: React component - icon component (required)",
+      "size: xs|sm|md|lg|xl - icon size",
+      "weight: string - optional style/weight hint for icons that support it",
+      "variant: default|primary|secondary|tertiary|accent|success|warning|error - color",
+      "iconProps: typed from the passed icon component - advanced icon-specific props"
+    ],
+    "a11yRules": [
+      "A11Y_ICON_LABEL",
+      "A11Y_COLOR_CONTRAST"
+    ]
+  },
+  "ai": {
+    "compositionPattern": "compound",
+    "subComponents": [
+      "Root"
+    ]
+  },
+  "provenance": {
+    "source": "migrated",
+    "verified": false,
+    "frameworkSupport": "native",
+    "extractedAt": "2026-03-13T23:18:58.998Z"
+  }
+}

package/src/components/Icon/Icon.module.scss

@@ -0,0 +1,38 @@
+@use "../../tokens/variables" as *;
+
+.icon {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  color: currentColor;
+  line-height: 1;
+}
+
+// Color variants (matching Badge/Alert pattern)
+.primary {
+  color: var(--fui-text-primary, $fui-text-primary);
+}
+
+.secondary {
+  color: var(--fui-text-secondary, $fui-text-secondary);
+}
+
+.tertiary {
+  color: var(--fui-text-tertiary, $fui-text-tertiary);
+}
+
+.accent {
+  color: var(--fui-color-accent, $fui-color-accent);
+}
+
+.success {
+  color: var(--fui-color-success-text, $fui-color-success-text);
+}
+
+.warning {
+  color: var(--fui-color-warning-text, $fui-color-warning-text);
+}
+
+.error {
+  color: var(--fui-color-danger-text, $fui-color-danger-text);
+}

package/src/components/Icon/Icon.stories.tsx

@@ -0,0 +1,80 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Heart, Star, Check, Warning, Info } from '@phosphor-icons/react';
+import { Icon } from '.';
+
+/**
+ * Icon is a wrapper for icon components with consistent sizing and semantic
+ * colors. Pass any icon component (Phosphor, Lucide, etc.) via the required
+ * `icon` prop. Icons are decorative by default and should be paired with text
+ * for meaning.
+ */
+const meta = {
+  title: 'Display/Icon',
+  component: Icon,
+  tags: ['autodocs', 'canonical'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'Wrapper for icon components with consistent sizing and semantic colors.',
+      },
+    },
+  },
+  argTypes: {
+    size: {
+      control: 'select',
+      options: ['xs', 'sm', 'md', 'lg', 'xl'],
+      description: 'Icon size',
+    },
+    weight: {
+      control: 'select',
+      options: ['thin', 'light', 'regular', 'bold', 'fill', 'duotone'],
+      description: 'Optional icon style/weight hint',
+    },
+    variant: {
+      control: 'select',
+      options: [
+        'default',
+        'primary',
+        'secondary',
+        'tertiary',
+        'accent',
+        'success',
+        'warning',
+        'error',
+      ],
+      description: 'Semantic color variant',
+    },
+  },
+  args: {
+    icon: Heart,
+    size: 'md',
+    weight: 'regular',
+    variant: 'default',
+  },
+} satisfies Meta<typeof Icon>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: { icon: Heart },
+};
+
+export const Large: Story = {
+  args: { icon: Star, size: 'xl' },
+};
+
+export const Success: Story = {
+  args: { icon: Check, variant: 'success' },
+};
+
+export const Warning_: Story = {
+  name: 'Warning',
+  args: { icon: Warning, variant: 'warning' },
+};
+
+export const Accent: Story = {
+  args: { icon: Info, variant: 'accent', weight: 'fill' },
+};

package/src/components/Icon/index.tsx

@@ -0,0 +1,105 @@
+'use client';
+
+import * as React from 'react';
+import styles from './Icon.module.scss';
+
+// Pixel values of the shared `--fui-icon-*` ladder (also exported as CSS vars
+// from the token layer). The icon library `size` prop needs a numeric px value,
+// so the same ladder is mirrored here as the single source instead of a bespoke
+// per-component scale.
+const FUI_ICON_PX = {
+  xs: 12,
+  sm: 14,
+  md: 16,
+  lg: 20,
+  xl: 24,
+  '2xl': 32,
+} as const;
+
+type AnyIconComponent = React.ComponentType<any>;
+type IconComponentProps<TIcon extends AnyIconComponent> = React.ComponentPropsWithoutRef<TIcon>;
+
+export type IconProps<TIcon extends AnyIconComponent = AnyIconComponent> =
+  Omit<React.HTMLAttributes<HTMLSpanElement>, 'color'> & {
+    /** The icon component to render */
+    icon: TIcon;
+    /** Size of the icon */
+    size?: 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+    /** Optional style/weight hint forwarded when the icon component supports a `weight` prop */
+    weight?: string;
+    /** Semantic color variant */
+    variant?: 'default' | 'primary' | 'secondary' | 'tertiary' | 'accent' | 'success' | 'warning' | 'error';
+    /** @deprecated Use variant instead */
+    color?: 'primary' | 'secondary' | 'tertiary' | 'accent' | 'success' | 'warning' | 'error';
+    /** Additional props forwarded to the underlying icon component (typed from `icon`) */
+    iconProps?: Partial<IconComponentProps<TIcon>>;
+  };
+
+// Sourced from the shared `--fui-icon-*` ladder (12/14/16/20/24/32px) so this
+// stops being a separate hardcoded size scale. NOTE: Icon's public size names
+// are offset by one step from the icon-token names — Icon `xs/sm/md/lg/xl` map
+// to icon `xs/md/lg/xl/2xl` (skipping icon-sm=14). Preserved to keep the
+// rendered px identical for existing consumers.
+const sizeMap: Record<NonNullable<IconProps['size']>, number> = {
+  xs: FUI_ICON_PX['xs'], // 12
+  sm: FUI_ICON_PX['md'], // 16
+  md: FUI_ICON_PX['lg'], // 20
+  lg: FUI_ICON_PX['xl'], // 24
+  xl: FUI_ICON_PX['2xl'], // 32
+};
+
+const IconRoot = React.forwardRef<HTMLSpanElement, IconProps>(
+  function Icon(
+    {
+      icon: IconComponent,
+      size = 'md',
+      weight = 'regular',
+      variant,
+      color,
+      iconProps,
+      className,
+      style,
+      ...htmlProps
+    },
+    ref
+  ) {
+    // Support deprecated color prop (variant takes precedence)
+    const colorVariant = variant || color;
+
+    const classes = [
+      styles.icon,
+      colorVariant && colorVariant !== 'default' && styles[colorVariant],
+      className,
+    ]
+      .filter(Boolean)
+      .join(' ');
+
+    const resolvedIconProps = {
+      ...(iconProps as Record<string, unknown> | undefined),
+    };
+
+    // Provide sensible defaults for icon libraries that support common props.
+    if (!('size' in resolvedIconProps)) {
+      resolvedIconProps.size = sizeMap[size];
+    }
+    if (weight && !('weight' in resolvedIconProps)) {
+      resolvedIconProps.weight = weight;
+    }
+
+    return (
+      <span ref={ref} {...htmlProps} className={classes} style={style}>
+        <IconComponent {...resolvedIconProps} />
+      </span>
+    );
+  }
+);
+
+type IconComponentSignature = <TIcon extends AnyIconComponent = AnyIconComponent>(
+  props: IconProps<TIcon> & React.RefAttributes<HTMLSpanElement>
+) => React.ReactElement | null;
+
+export const Icon = Object.assign(IconRoot, {
+  Root: IconRoot,
+}) as typeof IconRoot & IconComponentSignature & {
+  Root: typeof IconRoot;
+};

package/src/components/IconButton/IconButton.module.scss

@@ -0,0 +1,102 @@
+@use '../../tokens/variables' as *;
+@use '../../tokens/mixins' as *;
+
+.iconButton {
+  @include button-reset;
+  @include interactive-base;
+
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  aspect-ratio: 1 / 1;
+  border-radius: var(--fui-radius-md, $fui-radius-md);
+  color: var(--fui-text-secondary, $fui-text-secondary);
+  border: 1px solid transparent;
+  background-color: transparent;
+  flex-shrink: 0;
+
+  &:hover:not(:disabled):not([data-disabled]) {
+    color: var(--fui-text-primary, $fui-text-primary);
+  }
+
+  svg {
+    display: block;
+  }
+}
+
+// Sizes — square targets share the Button height ladder so an IconButton
+// lines up with its sibling Buttons in toolbars. Icon sizing is driven by
+// the button height so a single <IconButton size="sm"><Icon /></> always
+// renders a correctly-scaled glyph without consumer math.
+.sm {
+  width: var(--fui-button-height-sm, $fui-button-height-sm);
+  height: var(--fui-button-height-sm, $fui-button-height-sm);
+
+  svg {
+    width: var(--fui-icon-sm, $fui-icon-sm);
+    height: var(--fui-icon-sm, $fui-icon-sm);
+  }
+}
+
+.md {
+  width: var(--fui-button-height-md, $fui-button-height-md);
+  height: var(--fui-button-height-md, $fui-button-height-md);
+
+  svg {
+    width: var(--fui-icon-md, $fui-icon-md);
+    height: var(--fui-icon-md, $fui-icon-md);
+  }
+}
+
+.lg {
+  width: var(--fui-button-height-lg, $fui-button-height-lg);
+  height: var(--fui-button-height-lg, $fui-button-height-lg);
+
+  svg {
+    width: var(--fui-icon-lg, $fui-icon-lg);
+    height: var(--fui-icon-lg, $fui-icon-lg);
+  }
+}
+
+// Variants
+.ghost {
+  &:hover:not(:disabled):not([data-disabled]) {
+    background-color: var(--fui-bg-hover, $fui-bg-hover);
+  }
+
+  &:active:not(:disabled):not([data-disabled]) {
+    background-color: var(--fui-bg-active, $fui-bg-active);
+  }
+}
+
+.subtle {
+  background-color: var(--fui-bg-tertiary, $fui-bg-tertiary);
+
+  &:hover:not(:disabled):not([data-disabled]) {
+    background-color: var(--fui-bg-hover, $fui-bg-hover);
+  }
+
+  &:active:not(:disabled):not([data-disabled]) {
+    background-color: var(--fui-bg-active, $fui-bg-active);
+  }
+}
+
+.outlined {
+  border-color: var(--fui-border, $fui-border);
+
+  &:hover:not(:disabled):not([data-disabled]) {
+    background-color: var(--fui-bg-hover, $fui-bg-hover);
+    border-color: var(--fui-border-strong, $fui-border-strong);
+  }
+
+  &:active:not(:disabled):not([data-disabled]) {
+    background-color: var(--fui-bg-active, $fui-bg-active);
+  }
+}
+
+// Pressed (for toggle-style affordances) — sits on the active surface even
+// while idle so the "on" state reads clearly.
+.pressed {
+  background-color: var(--fui-bg-active, $fui-bg-active);
+  color: var(--fui-text-primary, $fui-text-primary);
+}

package/src/components/IconButton/IconButton.stories.tsx

@@ -0,0 +1,78 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Gear, Trash, Plus, DotsThree } from '@phosphor-icons/react';
+import { IconButton } from '.';
+
+/**
+ * IconButton is a compact square button for icon-only affordances such as
+ * topbar actions, row controls, and workspace rails. Icon-only buttons need an
+ * accessible name, so always provide an aria-label describing the action.
+ */
+const meta = {
+  title: 'Components/IconButton',
+  component: IconButton,
+  tags: ['autodocs', 'canonical'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'Compact square button for icon-only affordances in dense chrome.',
+      },
+    },
+  },
+  argTypes: {
+    variant: {
+      control: 'select',
+      options: ['ghost', 'subtle', 'outlined'],
+      description: 'Visual style variant',
+    },
+    size: {
+      control: 'select',
+      options: ['sm', 'md', 'lg'],
+      description: 'Button size',
+    },
+    pressed: {
+      control: 'boolean',
+      description: 'Mark as pressed for toggle-style affordances',
+    },
+  },
+  args: {
+    variant: 'ghost',
+    size: 'md',
+    'aria-label': 'Settings',
+    children: <Gear />,
+  },
+} satisfies Meta<typeof IconButton>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Ghost: Story = {
+  args: { variant: 'ghost', 'aria-label': 'More options', children: <DotsThree /> },
+};
+
+export const Subtle: Story = {
+  args: { variant: 'subtle', 'aria-label': 'Add item', children: <Plus /> },
+};
+
+export const Outlined: Story = {
+  args: { variant: 'outlined', 'aria-label': 'Settings', children: <Gear /> },
+};
+
+export const Pressed: Story = {
+  args: {
+    variant: 'subtle',
+    pressed: true,
+    'aria-label': 'Toggle setting',
+    children: <Gear />,
+  },
+};
+
+export const Destructive: Story = {
+  args: {
+    variant: 'outlined',
+    size: 'lg',
+    'aria-label': 'Delete',
+    children: <Trash />,
+  },
+};

package/src/components/IconButton/index.tsx

@@ -0,0 +1,93 @@
+"use client";
+
+import * as React from "react";
+import { Button as BaseButton } from "@base-ui/react/button";
+import { useResolvedControlSize } from "../ComponentDefaults";
+import styles from "./IconButton.module.scss";
+
+/**
+ * Compact square button for icon-only affordances — topbar actions, row
+ * controls, workspace rails. Where `Button` with an icon is the general-
+ * purpose control, `IconButton` is specifically sized and padded for dense
+ * chrome: three tight preset sizes, a square shape, and a ghost variant
+ * that's transparent at rest.
+ *
+ * Icon-only buttons need an accessible name — pass `aria-label` describing
+ * the action. Runtime dev check warns if both are missing.
+ *
+ * @see https://usefragments.com/components/icon-button
+ */
+export interface IconButtonProps extends Omit<
+  React.ButtonHTMLAttributes<HTMLButtonElement>,
+  "children"
+> {
+  /** Icon element to render (a Phosphor/Lucide icon, SVG, etc.) */
+  children: React.ReactNode;
+  /** Visual style variant.
+   *
+   * - `ghost` (default): transparent at rest, subtle hover. Fits inside
+   *   dense topbars and row affordances.
+   * - `subtle`: painted with the tertiary surface; use when the affordance
+   *   sits on a matching surface and needs a touch more weight.
+   * - `outlined`: hairline border; use as a secondary control alongside a
+   *   primary `Button`.
+   * @default "ghost" */
+  variant?: "ghost" | "subtle" | "outlined";
+  /** Button size. Uses the same height ladder as Button so icon-only
+   * affordances align with toolbar actions and adjacent fields.
+   * @default "md" */
+  size?: "sm" | "md" | "lg";
+  /** Mark as pressed (for toggle-style affordances). Sets `aria-pressed`
+   * and applies the active surface styling. */
+  pressed?: boolean;
+}
+
+const IconButtonRoot = React.forwardRef<HTMLButtonElement, IconButtonProps>(function IconButton(
+  {
+    children,
+    variant = "ghost",
+    size: sizeProp,
+    pressed,
+    className,
+    "aria-label": ariaLabel,
+    "aria-labelledby": ariaLabelledBy,
+    type = "button",
+    ...htmlProps
+  },
+  ref
+) {
+  if (process.env.NODE_ENV !== "production" && !ariaLabel && !ariaLabelledBy) {
+    console.warn(
+      "[IconButton] Icon-only buttons need an accessible name. Provide `aria-label` or `aria-labelledby`."
+    );
+  }
+
+  const size = useResolvedControlSize(sizeProp);
+  const classes = [
+    styles.iconButton,
+    styles[size],
+    styles[variant],
+    pressed && styles.pressed,
+    className,
+  ]
+    .filter(Boolean)
+    .join(" ");
+
+  return (
+    <BaseButton
+      ref={ref}
+      type={type}
+      className={classes}
+      aria-label={ariaLabel}
+      aria-labelledby={ariaLabelledBy}
+      aria-pressed={pressed}
+      {...htmlProps}
+    >
+      {children}
+    </BaseButton>
+  );
+});
+
+export const IconButton = Object.assign(IconButtonRoot, {
+  Root: IconButtonRoot,
+});