@usefragments/ui 1.6.0 → 2.0.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 colours 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",
@@ -17,8 +12,8 @@
     "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",
+    "tone: accent|info|success|warning|danger",
+    "color: primary|secondary|tertiary",
     "iconProps: object"
   ],
   "props": {
@@ -37,57 +32,26 @@
       "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": {
+    "tone": {
       "type": "enum",
-      "description": "Semantic color variant",
-      "default": "default",
+      "description": "Semantic colour. Reserve success, warning and danger for real state; omit to inherit currentColor",
       "required": false,
-      "values": [
-        "default",
-        "primary",
-        "secondary",
-        "tertiary",
-        "accent",
-        "success",
-        "warning",
-        "error"
-      ]
+      "values": ["accent", "info", "success", "warning", "danger"]
     },
     "color": {
       "type": "enum",
-      "description": "Deprecated alias for variant",
+      "description": "Text-hierarchy colour, the same axis as Text color. tone wins when both are set",
       "required": false,
-      "values": [
-        "primary",
-        "secondary",
-        "tertiary",
-        "accent",
-        "success",
-        "warning",
-        "error"
-      ]
+      "values": ["primary", "secondary", "tertiary"]
     },
     "iconProps": {
       "type": "object",
@@ -97,55 +61,51 @@
   },
   "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 the success, warning, and danger tones 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",
-      "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": "Tones",
+      "description": "Tone states carry meaning — never use them for decoration.",
+      "code": "<div style={{ display: 'flex', gap: '12px', alignItems: 'center' }}>\n  <Icon icon={Check} tone=\"success\" />\n  <Icon icon={Warning} tone=\"warning\" />\n  <Icon icon={Warning} tone=\"danger\" />\n  <Icon icon={Info} tone=\"accent\" />\n</div>"
+    },
+    {
+      "name": "Hierarchy",
+      "description": "The text colour ladder, for glyphs that sit beside secondary or tertiary copy.",
+      "code": "<div style={{ display: 'flex', gap: '12px', alignItems: 'center' }}>\n  <Icon icon={Heart} color=\"primary\" />\n  <Icon icon={Heart} color=\"secondary\" />\n  <Icon icon={Heart} color=\"tertiary\" />\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 }} />"
     }
   ],
@@ -171,19 +131,15 @@
       "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",
+      "tone: accent|info|success|warning|danger - semantic colour",
+      "color: primary|secondary|tertiary - text-hierarchy colour",
       "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

@@ -20,35 +20,36 @@
   }
 }
 
-.size2xl {
-  @include representation.glyph("2xl");
-}
-
-// Color variants (matching Badge/Alert pattern)
-.primary {
+// Text-hierarchy colour (Text's `color` axis). Absence inherits currentColor.
+.colorPrimary {
   color: var(--fui-text-primary, $fui-text-primary);
 }
 
-.secondary {
+.colorSecondary {
   color: var(--fui-text-secondary, $fui-text-secondary);
 }
 
-.tertiary {
+.colorTertiary {
   color: var(--fui-text-tertiary, $fui-text-tertiary);
 }
 
-.accent {
+// Tone paints the shared status ramp (same `*-text` stops as Badge and Text).
+.toneAccent {
   color: var(--fui-color-accent, $fui-color-accent);
 }
 
-.success {
+.toneInfo {
+  color: var(--fui-color-info-text, $fui-color-info-text);
+}
+
+.toneSuccess {
   color: var(--fui-color-success-text, $fui-color-success-text);
 }
 
-.warning {
+.toneWarning {
   color: var(--fui-color-warning-text, $fui-color-warning-text);
 }
 
-.error {
+.toneDanger {
   color: var(--fui-color-danger-text, $fui-color-danger-text);
 }

package/src/components/Icon/index.tsx

@@ -7,56 +7,56 @@ import styles from "./Icon.module.scss";
 type AnyIconComponent = React.ComponentType<any>;
 type IconComponentProps<TIcon extends AnyIconComponent> = React.ComponentPropsWithoutRef<TIcon>;
 
+export type IconSize = "xs" | "sm" | "md" | "lg" | "xl";
+export type IconTone = "accent" | "info" | "success" | "warning" | "danger";
+export type IconColor = "primary" | "secondary" | "tertiary";
+
 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";
+  /** Size of the icon. `xl` is the largest step (24px); the glyph inherits
+   * `currentColor` and the surrounding line height.
+   * @default "md" */
+  size?: IconSize;
   /** 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";
+  /** Semantic colour. Reserve `success`, `warning` and `danger` for real
+   * state; `accent` is the brand spend. Omit to inherit `currentColor`. */
+  tone?: IconTone;
+  /** Text-hierarchy colour, the same axis as Text's `color`. `tone` wins when
+   * both are set. Omit to inherit `currentColor`. */
+  color?: IconColor;
   /** Additional props forwarded to the underlying icon component (typed from `icon`) */
   iconProps?: Partial<IconComponentProps<TIcon>>;
 };
 
 const iconTargets = MEASUREMENT_PROFILES.targets.icon;
-type IconSize = NonNullable<IconProps["size"]>;
+
+const TONE_CLASS: Record<IconTone, string> = {
+  accent: styles.toneAccent,
+  info: styles.toneInfo,
+  success: styles.toneSuccess,
+  warning: styles.toneWarning,
+  danger: styles.toneDanger,
+};
+
+const COLOR_CLASS: Record<IconColor, string> = {
+  primary: styles.colorPrimary,
+  secondary: styles.colorSecondary,
+  tertiary: styles.colorTertiary,
+};
 
 const IconRoot = React.forwardRef<HTMLSpanElement, IconProps>(function Icon(
-  {
-    icon: IconComponent,
-    size = "md",
-    weight = "regular",
-    variant,
-    color,
-    iconProps,
-    className,
-    style,
-    ...htmlProps
-  },
+  { icon: IconComponent, size = "md", weight = "regular", tone, color, iconProps, className, style, ...htmlProps },
   ref
 ) {
-  // Support deprecated color prop (variant takes precedence)
-  const colorVariant = variant || color;
-
   const classes = [
     styles.icon,
-    size === "2xl" ? styles.size2xl : styles[size as Exclude<IconSize, "2xl">],
-    colorVariant && colorVariant !== "default" && styles[colorVariant],
+    styles[size],
+    tone ? TONE_CLASS[tone] : color ? COLOR_CLASS[color] : undefined,
     className,
   ]
     .filter(Boolean)

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

@@ -1,15 +1,15 @@
 {
   "$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",
   "exportName": "IconButton",
   "propsSummary": [
     "children: node (required)",
-    "variant: ghost|subtle|outlined (default: ghost)",
+    "variant: ghost|soft|outline (default: ghost)",
     "size: sm|md|lg (default: md)",
     "pressed: boolean",
     "aria-label: string",
@@ -26,7 +26,7 @@
       "description": "Visual treatment for the icon-only action",
       "default": "ghost",
       "required": false,
-      "values": ["ghost", "subtle", "outlined"]
+      "values": ["ghost", "soft", "outline"]
     },
     "size": {
       "type": "enum",
@@ -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; outline 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=\"soft\">\n    <PlusIcon aria-hidden />\n  </IconButton>\n  <IconButton aria-label=\"Add item\" variant=\"outline\">\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=\"outline\" size=\"sm\">\n    <PlusIcon aria-hidden />\n  </IconButton>\n  <IconButton aria-label=\"Add item\" variant=\"outline\" size=\"md\">\n    <PlusIcon aria-hidden />\n  </IconButton>\n  <IconButton aria-label=\"Add item\" variant=\"outline\" 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=\"outline\">\n    <PinIcon aria-hidden />\n  </IconButton>\n  <IconButton aria-label=\"Unpin item\" variant=\"outline\" 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=\"outline\" disabled>\n  <TrashIcon aria-hidden />\n</IconButton>"
     }
   ],
   "relations": [
@@ -100,7 +116,7 @@
   "contract": {
     "propsSummary": [
       "children: ReactNode - icon element (required)",
-      "variant: ghost|subtle|outlined - visual treatment",
+      "variant: ghost|soft|outline - visual treatment",
       "size: sm|md|lg - square control size",
       "pressed: boolean - toggle state exposed with aria-pressed",
       "aria-label or aria-labelledby - required accessible name"

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

@@ -1,16 +1,17 @@
-@use '../../tokens/variables' as *;
-@use '../../tokens/mixins' as *;
-@use '../../recipes/action';
-@use '../../recipes/target';
+@use "../../tokens/variables" as *;
+@use "../../tokens/mixins" as *;
+@use "../../recipes/action";
+@use "../../recipes/target";
 
 .iconButton {
   @include button-reset;
   @include interactive-base;
   @include action.base;
+  @include high-contrast-outline;
 
-  border-radius: var(--fui-radius-md, $fui-radius-md);
+  border-radius: var(--fui-radius-l2, $fui-radius-l2);
   color: var(--fui-text-secondary, $fui-text-secondary);
-  border: var(--fui-stroke-hairline, 1px) solid transparent;
+  border: var(--fui-stroke-hairline, #{$fui-stroke-hairline}) solid transparent;
   background-color: transparent;
   flex-shrink: 0;
 
@@ -18,6 +19,14 @@
     color: var(--fui-text-primary, $fui-text-primary);
   }
 
+  // Tactile press. 0.96 exactly: lower reads as exaggerated. Rides the
+  // interactive-base transition, so a release mid-press eases back.
+  @media (prefers-reduced-motion: no-preference) {
+    &:active:not(:disabled):not([data-disabled]) {
+      scale: 0.96;
+    }
+  }
+
   svg {
     display: block;
   }
@@ -59,7 +68,7 @@
   }
 }
 
-.subtle {
+.soft {
   background-color: var(--fui-bg-tertiary, $fui-bg-tertiary);
 
   &:hover:not(:disabled):not([data-disabled]) {
@@ -71,7 +80,7 @@
   }
 }
 
-.outlined {
+.outline {
   border-color: var(--fui-border, $fui-border);
 
   &:hover:not(:disabled):not([data-disabled]) {
@@ -84,9 +93,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
@@ -27,12 +28,12 @@ export interface IconButtonProps extends Omit<
    *
    * - `ghost` (default): transparent at rest, subtle hover. Fits inside
    *   dense topbars and row affordances.
-   * - `subtle`: painted with the tertiary surface; use when the affordance
+   * - `soft`: 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`.
+   * - `outline`: hairline border; use as a secondary control alongside a
+   *   solid `Button`.
    * @default "ghost" */
-  variant?: "ghost" | "subtle" | "outlined";
+  variant?: "ghost" | "soft" | "outline";
   /** Button size. Uses the same height ladder as Button so icon-only
    * affordances align with toolbar actions and adjacent fields.
    * @default "md" */
@@ -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`."
     );