@usefragments/ui 1.5.4 → 1.7.0

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

@@ -1,14 +1,9 @@
 {
   "$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.",
+  "description": "Sizes and colors any icon so it lines up with the text beside it.",
   "category": "display",
-  "tags": [
-    "icon",
-    "visual",
-    "symbol",
-    "graphic"
-  ],
+  "tags": ["icon", "visual", "symbol", "graphic"],
   "status": "stable",
   "sourcePath": "src/components/Icon/index.tsx",
   "exportName": "Icon",
@@ -37,27 +32,14 @@
       "description": "Icon size",
       "default": "md",
       "required": false,
-      "values": [
-        "xs",
-        "sm",
-        "md",
-        "lg",
-        "xl"
-      ]
+      "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"
-      ]
+      "values": ["thin", "light", "regular", "bold", "fill", "duotone"]
     },
     "variant": {
       "type": "enum",
@@ -79,15 +61,7 @@
       "type": "enum",
       "description": "Deprecated alias for variant",
       "required": false,
-      "values": [
-        "primary",
-        "secondary",
-        "tertiary",
-        "accent",
-        "success",
-        "warning",
-        "error"
-      ]
+      "values": ["primary", "secondary", "tertiary", "accent", "success", "warning", "error"]
     },
     "iconProps": {
       "type": "object",
@@ -97,55 +71,46 @@
   },
   "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)"
+      "A symbol sits beside text, inside a button, or leads a list item",
+      "State needs a glanceable marker"
     ],
+    "whenNot": ["Artwork or illustration (use Image)", "Multi-color or animated graphics"],
     "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"
+      "Reserve success, warning, and error colors for real state",
+      "Hold one size per context",
+      "Match weight to the text weight beside it",
+      "iconProps reaches options the wrapper does not expose"
     ],
     "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"
+      "Icons ship aria-hidden — they are decoration until you label them",
+      "An icon-only button needs VisuallyHidden text",
+      "Color alone never carries the message"
     ]
   },
   "examples": [
     {
       "name": "Default",
-      "description": "Basic icon with default styling",
+      "description": "Inherits the size and color of its surroundings.",
       "code": "<Icon icon={Heart} />"
     },
     {
       "name": "Sizes",
-      "description": "Available size options",
+      "description": "Steps tuned to the type scale, so icons never float off the baseline.",
       "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",
+      "description": "Color states carry meaning — never use them for decoration.",
       "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",
+      "description": "Match the stroke to the text weight next to it.",
       "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",
+      "description": "iconProps passes anything the underlying icon package supports.",
       "code": "<Icon icon={Heart} iconProps={{ mirrored: true }} />"
     }
   ],
@@ -174,16 +139,11 @@
       "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"
-    ]
+    "a11yRules": ["A11Y_ICON_LABEL", "A11Y_COLOR_CONTRAST"]
   },
   "ai": {
     "compositionPattern": "compound",
-    "subComponents": [
-      "Root"
-    ]
+    "subComponents": ["Root"]
   },
   "provenance": {
     "source": "migrated",

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

@@ -1,4 +1,5 @@
 @use "../../tokens/variables" as *;
+@use "../../recipes/representation" as representation;
 
 .icon {
   display: inline-flex;
@@ -6,6 +7,21 @@
   justify-content: center;
   color: currentColor;
   line-height: 1;
+
+  > svg {
+    inline-size: 100%;
+    block-size: 100%;
+  }
+}
+
+@each $size in ("xs", "sm", "md", "lg", "xl") {
+  .#{$size} {
+    @include representation.glyph($size);
+  }
+}
+
+.size2xl {
+  @include representation.glyph("2xl");
 }
 
 // Color variants (matching Badge/Alert pattern)

package/src/components/Icon/index.tsx

@@ -1,98 +1,85 @@
-'use client';
+"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;
+import * as React from "react";
+import { MEASUREMENT_PROFILES, measurementPx } from "../../measurements";
+import styles from "./Icon.module.scss";
 
 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
+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" | "2xl";
+  /** 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>>;
 };
 
-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 iconTargets = MEASUREMENT_PROFILES.targets.icon;
+type IconSize = NonNullable<IconProps["size"]>;
 
-    const classes = [
-      styles.icon,
-      colorVariant && colorVariant !== 'default' && styles[colorVariant],
-      className,
-    ]
-      .filter(Boolean)
-      .join(' ');
+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 resolvedIconProps = {
-      ...(iconProps as Record<string, unknown> | undefined),
-    };
+  const classes = [
+    styles.icon,
+    size === "2xl" ? styles.size2xl : styles[size as Exclude<IconSize, "2xl">],
+    colorVariant && colorVariant !== "default" && styles[colorVariant],
+    className,
+  ]
+    .filter(Boolean)
+    .join(" ");
 
-    // 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;
-    }
+  const resolvedIconProps = {
+    ...(iconProps as Record<string, unknown> | undefined),
+  };
 
-    return (
-      <span ref={ref} {...htmlProps} className={classes} style={style}>
-        <IconComponent {...resolvedIconProps} />
-      </span>
-    );
+  // Provide sensible defaults for icon libraries that support common props.
+  if (!("size" in resolvedIconProps)) {
+    resolvedIconProps.size = measurementPx(iconTargets[size], `targets.icon.${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>
@@ -100,6 +87,7 @@ type IconComponentSignature = <TIcon extends AnyIconComponent = AnyIconComponent
 
 export const Icon = Object.assign(IconRoot, {
   Root: IconRoot,
-}) as typeof IconRoot & IconComponentSignature & {
-  Root: typeof IconRoot;
-};
+}) as typeof IconRoot &
+  IconComponentSignature & {
+    Root: typeof IconRoot;
+  };

package/src/components/IconButton/IconButton.contract.json

@@ -1,8 +1,8 @@
 {
   "$schema": "https://usefragments.com/schemas/contract.v1.json",
   "name": "IconButton",
-  "description": "Compact square button for icon-only actions in dense toolbars, top bars, and row controls.",
-  "category": "forms",
+  "description": "Runs an action from an icon alone, for toolbars and table rows.",
+  "category": "actions",
   "tags": ["action", "button", "icon", "toolbar", "interactive"],
   "status": "stable",
   "sourcePath": "src/components/IconButton/index.tsx",
@@ -53,36 +53,52 @@
   },
   "usage": {
     "when": [
-      "Compact icon-only actions in toolbars or top bars",
-      "Row actions where a text button would be too wide",
-      "Toggle-style icon actions with a visible pressed state"
+      "Toolbars and top bars where text buttons crowd",
+      "Row actions too narrow for a label",
+      "Toggle actions that show a pressed state"
     ],
     "whenNot": [
-      "The action needs a visible text label (use Button)",
-      "The control changes a persistent boolean setting (use Switch)",
-      "The icon is decorative and not interactive (use Icon)"
+      "The action needs a visible label — use Button",
+      "It flips a persistent setting — use Switch",
+      "The icon is decorative — use Icon"
     ],
     "guidelines": [
-      "Always provide aria-label or aria-labelledby",
-      "Use ghost for ordinary toolbar actions and outlined when more separation is needed",
-      "Use pressed only when the button represents a persistent toggle state"
+      "aria-label or aria-labelledby is required, every time",
+      "ghost for ordinary toolbar actions; outlined when it needs separation",
+      "pressed only for real toggle state, not selection",
+      "Keep icon meaning obvious, or pair it with a Tooltip"
     ],
     "accessibility": [
-      "Every icon-only button must have an accessible name",
-      "The accessible name should describe the action, not the icon",
-      "Pressed state must be exposed with aria-pressed"
+      "Name the action, not the icon: \"Delete row\", not \"Trash\"",
+      "Pressed state is exposed via aria-pressed",
+      "Hit target stays at least 24px even at size=\"sm\""
     ]
   },
   "examples": [
     {
       "name": "Toolbar action",
-      "description": "A named icon-only toolbar action",
-      "code": "<IconButton aria-label=\"Add item\">\n  <PlusIcon aria-hidden />\n</IconButton>"
+      "description": "Icon carries the action; the label lives in aria-label.",
+      "code": "import { Plus as PlusIcon } from '@phosphor-icons/react';\n\n<IconButton aria-label=\"Add item\">\n  <PlusIcon aria-hidden />\n</IconButton>"
+    },
+    {
+      "name": "Variants",
+      "description": "Rising chrome: transparent, tinted, then bordered.",
+      "code": "import { Plus as PlusIcon } from '@phosphor-icons/react';\nimport { Stack } from '@/components/Stack';\n\n<Stack direction=\"row\" gap=\"sm\" align=\"center\">\n  <IconButton aria-label=\"Add item\" variant=\"ghost\">\n    <PlusIcon aria-hidden />\n  </IconButton>\n  <IconButton aria-label=\"Add item\" variant=\"subtle\">\n    <PlusIcon aria-hidden />\n  </IconButton>\n  <IconButton aria-label=\"Add item\" variant=\"outlined\">\n    <PlusIcon aria-hidden />\n  </IconButton>\n</Stack>"
+    },
+    {
+      "name": "Sizes",
+      "description": "sm for table rows, lg for primary chrome.",
+      "code": "import { Plus as PlusIcon } from '@phosphor-icons/react';\nimport { Stack } from '@/components/Stack';\n\n<Stack direction=\"row\" gap=\"sm\" align=\"center\">\n  <IconButton aria-label=\"Add item\" variant=\"outlined\" size=\"sm\">\n    <PlusIcon aria-hidden />\n  </IconButton>\n  <IconButton aria-label=\"Add item\" variant=\"outlined\" size=\"md\">\n    <PlusIcon aria-hidden />\n  </IconButton>\n  <IconButton aria-label=\"Add item\" variant=\"outlined\" size=\"lg\">\n    <PlusIcon aria-hidden />\n  </IconButton>\n</Stack>"
     },
     {
       "name": "Pressed state",
-      "description": "A toggle-style action with its state exposed",
-      "code": "import { PushPin as PinIcon } from '@phosphor-icons/react';\n\n<IconButton aria-label=\"Pin item\" pressed>\n  <PinIcon aria-hidden />\n</IconButton>"
+      "description": "Toggle that stays on, reported through aria-pressed.",
+      "code": "import { PushPin as PinIcon } from '@phosphor-icons/react';\nimport { Stack } from '@/components/Stack';\n\n<Stack direction=\"row\" gap=\"sm\" align=\"center\">\n  <IconButton aria-label=\"Pin item\" variant=\"outlined\">\n    <PinIcon aria-hidden />\n  </IconButton>\n  <IconButton aria-label=\"Unpin item\" variant=\"outlined\" pressed>\n    <PinIcon aria-hidden />\n  </IconButton>\n</Stack>"
+    },
+    {
+      "name": "Disabled",
+      "description": "Unavailable action, out of the tab order.",
+      "code": "import { Trash as TrashIcon } from '@phosphor-icons/react';\n\n<IconButton aria-label=\"Delete row\" variant=\"outlined\" disabled>\n  <TrashIcon aria-hidden />\n</IconButton>"
     }
   ],
   "relations": [

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

@@ -1,17 +1,16 @@
-@use '../../tokens/variables' as *;
-@use '../../tokens/mixins' as *;
+@use "../../tokens/variables" as *;
+@use "../../tokens/mixins" as *;
+@use "../../recipes/action";
+@use "../../recipes/target";
 
 .iconButton {
   @include button-reset;
   @include interactive-base;
+  @include action.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;
+  border: var(--fui-stroke-hairline, 1px) solid transparent;
   background-color: transparent;
   flex-shrink: 0;
 
@@ -24,37 +23,28 @@
   }
 }
 
-// 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);
+  @include action.icon-only("sm");
+  @include target.hit-area("compact");
 
   svg {
-    width: var(--fui-icon-sm, $fui-icon-sm);
-    height: var(--fui-icon-sm, $fui-icon-sm);
+    @include action.glyph("sm");
   }
 }
 
 .md {
-  width: var(--fui-button-height-md, $fui-button-height-md);
-  height: var(--fui-button-height-md, $fui-button-height-md);
+  @include action.icon-only("md");
 
   svg {
-    width: var(--fui-icon-md, $fui-icon-md);
-    height: var(--fui-icon-md, $fui-icon-md);
+    @include action.glyph("md");
   }
 }
 
 .lg {
-  width: var(--fui-button-height-lg, $fui-button-height-lg);
-  height: var(--fui-button-height-lg, $fui-button-height-lg);
+  @include action.icon-only("lg");
 
   svg {
-    width: var(--fui-icon-lg, $fui-icon-lg);
-    height: var(--fui-icon-lg, $fui-icon-lg);
+    @include action.glyph("lg");
   }
 }
 
@@ -94,9 +84,8 @@
   }
 }
 
-// Pressed (for toggle-style affordances) — sits on the active surface even
-// while idle so the "on" state reads clearly.
+// Pressed is a persistent toggle selection, not the pointer-down state.
 .pressed {
-  background-color: var(--fui-bg-active, $fui-bg-active);
+  background-color: var(--fui-control-selected-bg, $fui-bg-active);
   color: var(--fui-text-primary, $fui-text-primary);
 }

package/src/components/IconButton/index.tsx

@@ -4,6 +4,7 @@ import * as React from "react";
 import { Button as BaseButton } from "@base-ui/react/button";
 import { useResolvedControlSize } from "../ComponentDefaults";
 import styles from "./IconButton.module.scss";
+import { isProductionBuild } from "../../utils/env";
 
 /**
  * Compact square button for icon-only affordances — topbar actions, row
@@ -56,7 +57,7 @@ const IconButtonRoot = React.forwardRef<HTMLButtonElement, IconButtonProps>(func
   },
   ref
 ) {
-  if (process.env.NODE_ENV !== "production" && !ariaLabel && !ariaLabelledBy) {
+  if (!isProductionBuild() && !ariaLabel && !ariaLabelledBy) {
     console.warn(
       "[IconButton] Icon-only buttons need an accessible name. Provide `aria-label` or `aria-labelledby`."
     );