@usefragments/ui 1.6.0 → 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/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,7 +1,7 @@
-@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;
@@ -84,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`."
     );

package/src/components/Image/Image.contract.json

@@ -1,15 +1,9 @@
 {
   "$schema": "https://usefragments.com/schemas/contract.v1.json",
   "name": "Image",
-  "description": "Responsive image component with aspect ratio control, loading states, and error fallbacks. Handles image display with consistent styling.",
+  "description": "Renders a picture at a fixed shape with a built-in fallback when loading fails.",
   "category": "display",
-  "tags": [
-    "image",
-    "media",
-    "photo",
-    "picture",
-    "visual"
-  ],
+  "tags": ["image", "media", "photo", "picture", "visual"],
   "status": "stable",
   "sourcePath": "src/components/Image/index.tsx",
   "exportName": "Image",
@@ -44,25 +38,14 @@
       "description": "Aspect ratio of the image container",
       "default": "auto",
       "required": false,
-      "values": [
-        "1:1",
-        "4:3",
-        "16:9",
-        "21:9",
-        "auto"
-      ]
+      "values": ["1:1", "4:3", "16:9", "21:9", "auto"]
     },
     "objectFit": {
       "type": "enum",
       "description": "How the image fits within its container",
       "default": "cover",
       "required": false,
-      "values": [
-        "cover",
-        "contain",
-        "fill",
-        "none"
-      ]
+      "values": ["cover", "contain", "fill", "none"]
     },
     "width": {
       "type": "union",
@@ -79,13 +62,7 @@
       "description": "Border radius",
       "default": "none",
       "required": false,
-      "values": [
-        "none",
-        "sm",
-        "md",
-        "lg",
-        "full"
-      ]
+      "values": ["none", "sm", "md", "lg", "full"]
     },
     "fallback": {
       "type": "node",
@@ -120,50 +97,45 @@
   },
   "usage": {
     "when": [
-      "Displaying product images in cards or grids",
-      "Hero images with specific aspect ratios",
-      "User-uploaded content that may fail to load",
-      "Thumbnails in lists or galleries"
+      "Product shots, thumbnails, and hero art",
+      "Uploads you do not control and cannot trust to load"
     ],
     "whenNot": [
-      "User avatars (use Avatar component)",
-      "Icons or symbols (use Icon component)",
-      "Background images (use CSS background-image)",
-      "SVG illustrations (use inline SVG or Image component)"
+      "A person (use Avatar)",
+      "A symbol (use Icon)",
+      "Pure decoration behind content (use a CSS background)"
     ],
     "guidelines": [
-      "Always provide meaningful alt text for accessibility",
-      "Use appropriate aspect ratios for consistent layouts",
-      "Provide fallback content for failed loads",
-      "Use objectFit=\"contain\" for logos to preserve aspect ratio",
-      "Use imgProps / onImageLoad / onImageError when you need lower-level img control"
+      "Set aspectRatio so a grid holds its shape before the file arrives",
+      "objectFit=\"contain\" for logos, \"cover\" for photography",
+      "Always give fallback something to say",
+      "imgProps, onImageLoad, and onImageError expose the raw img when you need it"
     ],
     "accessibility": [
-      "Alt text is required and must describe the image content",
-      "Decorative images should have empty alt=\"\"",
-      "Avoid text in images; if necessary, describe the text in alt",
-      "Ensure sufficient contrast between image and surrounding content"
+      "alt is required — describe what the picture shows",
+      "Decoration takes alt=\"\"",
+      "Words baked into an image must be repeated in alt"
     ]
   },
   "examples": [
     {
       "name": "Default",
-      "description": "Basic image display",
+      "description": "src plus alt — the shape follows the file.",
       "code": "<Image\n  src=\"https://images.unsplash.com/photo-1555066931-4365d14bab8c?w=400&h=300&fit=crop\"\n  alt=\"Code on a screen\"\n  width={300}\n/>"
     },
     {
       "name": "Aspect Ratios",
-      "description": "Different aspect ratio options",
+      "description": "Lock the frame so a grid stays even whatever the file is.",
       "code": "<div style={{ display: 'flex', gap: '16px', flexWrap: 'wrap' }}>\n  <Image\n    src=\"https://images.unsplash.com/photo-1555066931-4365d14bab8c?w=200&h=200&fit=crop\"\n    alt=\"Square image\"\n    aspectRatio=\"1:1\"\n    width={100}\n  />\n  <Image\n    src=\"https://images.unsplash.com/photo-1555066931-4365d14bab8c?w=200&h=150&fit=crop\"\n    alt=\"4:3 image\"\n    aspectRatio=\"4:3\"\n    width={120}\n  />\n  <Image\n    src=\"https://images.unsplash.com/photo-1555066931-4365d14bab8c?w=320&h=180&fit=crop\"\n    alt=\"16:9 image\"\n    aspectRatio=\"16:9\"\n    width={160}\n  />\n</div>"
     },
     {
       "name": "Rounded Corners",
-      "description": "Border radius options",
+      "description": "Rounding softens the frame; match it to the surface it sits on.",
       "code": "<div style={{ display: 'flex', gap: '16px', alignItems: 'center' }}>\n  <Image\n    src=\"https://images.unsplash.com/photo-1555066931-4365d14bab8c?w=100&h=100&fit=crop\"\n    alt=\"No rounding\"\n    rounded=\"none\"\n    width={80}\n    height={80}\n  />\n  <Image\n    src=\"https://images.unsplash.com/photo-1555066931-4365d14bab8c?w=100&h=100&fit=crop\"\n    alt=\"Medium rounding\"\n    rounded=\"md\"\n    width={80}\n    height={80}\n  />\n  <Image\n    src=\"https://images.unsplash.com/photo-1555066931-4365d14bab8c?w=100&h=100&fit=crop\"\n    alt=\"Full rounding\"\n    rounded=\"full\"\n    width={80}\n    height={80}\n  />\n</div>"
     },
     {
       "name": "With Fallback",
-      "description": "Fallback content for loading/error states",
+      "description": "A dead URL shows this instead of a broken-image glyph.",
       "code": "<Image\n  src=\"https://invalid-url.example/image.jpg\"\n  alt=\"Image that will fail\"\n  width={200}\n  height={150}\n  rounded=\"md\"\n  fallback={\n    <div style={{ display: 'flex', alignItems: 'center', justifyContent: 'center', height: '100%', background: 'var(--fui-color-surface-secondary)' }}>\n      <span style={{ color: 'var(--fui-color-text-tertiary)' }}>No image</span>\n    </div>\n  }\n/>"
     }
   ],
@@ -189,16 +161,11 @@
       "fallback: ReactNode - loading/error content",
       "imgProps/onImageLoad/onImageError - low-level img customization and events"
     ],
-    "a11yRules": [
-      "A11Y_IMG_ALT",
-      "A11Y_IMG_DECORATIVE"
-    ]
+    "a11yRules": ["A11Y_IMG_ALT", "A11Y_IMG_DECORATIVE"]
   },
   "ai": {
     "compositionPattern": "compound",
-    "subComponents": [
-      "Root"
-    ]
+    "subComponents": ["Root"]
   },
   "provenance": {
     "source": "migrated",

package/src/components/Input/Input.contract.json

@@ -1,8 +1,8 @@
 {
   "$schema": "https://usefragments.com/schemas/contract.v1.json",
   "name": "Input",
-  "description": "Text input field for single-line user data entry",
-  "category": "forms",
+  "description": "Collects a single line of user-entered text.",
+  "category": "inputs",
   "tags": ["form", "input", "text"],
   "status": "stable",
   "sourcePath": "src/components/Input/index.tsx",
@@ -181,10 +181,9 @@
   },
   "usage": {
     "when": [
-      "Collecting single-line text data from users",
-      "Email, password, phone number, or URL input",
+      "Single-line answers: name, email, password, phone, URL",
       "Search fields",
-      "Short form fields (name, title, etc.)"
+      "Short free-form values a list cannot cover"
     ],
     "whenNot": [
       "Multi-line text (use Textarea)",
@@ -193,83 +192,78 @@
       "Date/time input (use DatePicker)"
     ],
     "guidelines": [
-      "Always provide a label for accessibility",
-      "Use appropriate input type for data validation",
-      "Show validation errors with error prop and helperText",
-      "Use placeholder for format hints, not labels",
-      "Use the shortcut prop for embedded keyboard hints instead of custom kbd markup around inputs",
-      "Shortcut hints are display-only by default; set shortcutBehavior=\"focus-input\" to opt into global hotkey focusing"
+      "Give every field a label",
+      "Match type to the data — it drives validation and mobile keyboards",
+      "Placeholder shows format; it never replaces the label",
+      "Pair error with helperText so the reason is announced",
+      "Use the shortcut prop for kbd hints instead of custom markup",
+      "shortcut is display-only; shortcutBehavior=\"focus-input\" adds the global hotkey"
     ],
     "accessibility": [
-      "Labels must be associated with inputs",
-      "Error messages should be announced to screen readers",
-      "Required fields should be indicated"
+      "Label is programmatically tied to the input",
+      "Error text is announced to screen readers",
+      "Required fields are marked"
     ]
   },
   "examples": [
     {
       "name": "Default",
-      "description": "Basic text input",
+      "description": "Label plus a placeholder that hints the format.",
       "code": "<Input label=\"Name\" placeholder=\"Enter your name\" />"
     },
     {
       "name": "With Value",
-      "description": "Input with pre-filled value",
+      "description": "Starts with a value already in the field.",
       "code": "<Input label=\"Email\" type=\"email\" value=\"user@example.com\" />"
     },
     {
       "name": "With Helper",
-      "description": "Input with helper text",
+      "description": "Supporting text sits under the field.",
       "code": "<Input\n  label=\"Password\"\n  type=\"password\"\n  placeholder=\"Create a password\"\n  helperText=\"Must be at least 8 characters\"\n/>"
     },
     {
       "name": "Error State",
-      "description": "Input showing validation error",
+      "description": "Red border, and helperText becomes the reason.",
       "code": "<Input\n  label=\"Email\"\n  type=\"email\"\n  value=\"invalid-email\"\n  error\n  helperText=\"Please enter a valid email address\"\n/>"
     },
     {
       "name": "Disabled",
-      "description": "Non-interactive input",
-      "code": "<Input label=\"Username\" value=\"readonly-user\" disabled />"
+      "description": "Dimmed, unfocusable, still shows its value.",
+      "code": "<Input label=\"Username\" value=\"ada.lovelace\" disabled />"
     },
     {
       "name": "Required",
-      "description": "Required field with asterisk indicator",
+      "description": "Asterisk marks the field as mandatory.",
       "code": "<Input\n  label=\"Email\"\n  type=\"email\"\n  placeholder=\"user@example.com\"\n  required\n/>"
     },
     {
       "name": "Sizes",
-      "description": "Available size variants",
+      "description": "Three heights: sm, md, lg.",
       "code": "<div style={{ display: 'flex', flexDirection: 'column', gap: '12px', maxWidth: '300px' }}>\n  <Input label=\"Small\" size=\"sm\" placeholder=\"Small input\" />\n  <Input label=\"Medium\" size=\"md\" placeholder=\"Medium input\" />\n  <Input label=\"Large\" size=\"lg\" placeholder=\"Large input\" />\n</div>"
     },
     {
       "name": "Bare Input (Field Composition)",
-      "description": "Disable the built-in wrapper for custom Field composition",
+      "description": "Drops the built-in label wrapper so Field owns the layout.",
       "code": "<Input\n  withFieldWrapper={false}\n  aria-label=\"Search\"\n  placeholder=\"Search...\"\n  rootProps={{ 'data-demo': 'bare-input-wrapper' }}\n/>"
     },
-    {
-      "name": "Shortcut Focus Hotkey",
-      "description": "Display shortcut hint and opt into focus behavior",
-      "code": "<Input\n  label=\"Command Palette\"\n  placeholder=\"Search commands\"\n  shortcut=\"⌘K\"\n  shortcutBehavior=\"focus-input\"\n/>"
-    },
     {
       "name": "Search With Shortcut",
-      "description": "Search input with a leading icon and embedded kbd hint",
+      "description": "Leading icon and a ⌘K hint that focuses the field.",
       "code": "<Input\n  aria-label=\"Search findings\"\n  placeholder=\"Search findings...\"\n  shortcut=\"⌘K\"\n  shortcutBehavior=\"focus-input\"\n  startAdornment={<MagnifyingGlass aria-hidden=\"true\" />}\n  withFieldWrapper={false}\n/>"
     },
     {
       "name": "Success State",
-      "description": "Input showing validated/success styling",
+      "description": "Green border confirms the value passed validation.",
       "code": "<Input\n  label=\"Email\"\n  type=\"email\"\n  value=\"user@example.com\"\n  success\n  helperText=\"Email verified\"\n/>"
     },
     {
       "name": "With Start Adornment",
-      "description": "Input with icon or prefix before the text",
+      "description": "Prefix sits inside the field, before the text.",
       "code": "<Input\n  label=\"Price\"\n  placeholder=\"0.00\"\n  startAdornment={<span>$</span>}\n/>"
     },
     {
       "name": "With End Adornment",
-      "description": "Input with icon or suffix after the text",
+      "description": "Suffix sits inside the field, after the text.",
       "code": "<Input\n  label=\"Weight\"\n  placeholder=\"0\"\n  endAdornment={<span>kg</span>}\n/>"
     }
   ],

package/src/components/Input/Input.module.scss

@@ -200,7 +200,8 @@
   font-variant-numeric: tabular-nums;
   color: var(--fui-kbd-color, var(--fui-text-tertiary, #{$fui-text-tertiary}));
   background: var(--fui-kbd-bg, var(--fui-bg-elevated, #{$fui-bg-elevated}));
-  border: var(--fui-stroke-hairline, 1px) solid var(--fui-kbd-border, var(--fui-border, #{$fui-border}));
+  border: var(--fui-stroke-hairline, 1px) solid
+    var(--fui-kbd-border, var(--fui-border, #{$fui-border}));
   border-radius: var(--fui-kbd-radius, var(--fui-radius-sm, #{$fui-radius-sm}));
   box-shadow: var(--fui-kbd-shadow, none);
   pointer-events: none;
@@ -214,7 +215,7 @@
 
 @media (prefers-contrast: more) {
   .input {
-    border-width: 2px;
+    border-width: var(--fui-stroke-default, 2px);
     border-color: var(--fui-text-primary, $fui-text-primary);
 
     &:focus-visible {