@usefragments/ui 1.5.4 → 1.7.0

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

@@ -1,13 +1,34 @@
 @use "../../tokens/variables" as *;
 @use "../../tokens/mixins" as *;
+@use "../../recipes/action";
+@use "../../recipes/field";
+@use "../../recipes/typography";
 
-// Form field wrapper (label + helper + error)
-@include form-field-wrapper;
+.wrapper {
+  @include field.wrapper;
+}
+
+.label {
+  @include field.label;
+}
+
+.required {
+  margin-inline-start: var(--fui-raw-space-2, 2px);
+  color: var(--fui-color-danger-text, $fui-color-danger-text);
+}
+
+.helper {
+  @include field.helper;
+}
+
+.helperError,
+.errorMessage {
+  @include field.error;
+}
 
 .input {
-  @include text-base;
   @include interactive-base;
-  @include field-shell;
+  @include field.shell;
 
   display: block;
   width: 100%;
@@ -17,25 +38,21 @@
   }
 
   &:focus-visible {
-    @include field-shell-focus;
+    @include field.focus-state;
   }
 }
 
-// Size variants — shared control-size path (matches Select/DatePicker)
+// Size variants — shared control-size + field-padding path
 .sm {
-  @include control-size("sm", "input");
+  @include field.size("sm");
 }
 
 .md {
-  @include control-size("md", "input");
+  @include field.size("md");
 }
 
 .lg {
-  @include control-size("lg", "input");
-}
-
-.labelSm {
-  font-size: var(--fui-font-size-xs, $fui-font-size-xs);
+  @include field.size("lg");
 }
 
 // Error state via :has() — detects aria-invalid on the input element.
@@ -43,7 +60,7 @@
 // The .error class is kept as a fallback for direct usage.
 .error,
 .input[aria-invalid] {
-  border-color: var(--fui-color-danger-text, $fui-color-danger-text);
+  @include field.invalid-state;
 
   &:focus-visible {
     border-color: var(--fui-color-danger-text, $fui-color-danger-text);
@@ -80,40 +97,36 @@
   position: relative;
   display: flex;
   align-items: center;
-
-  // Auto-detect shortcut kbd via :has() — replaces JS class toggle: `shortcut && styles.hasShortcut`
-  &:has(> .shortcut):not(.hasAdornment) .input {
-    padding-right: var(--fui-kbd-reserved-width, 2.714rem);
-    padding-left: var(--fui-space-2, $fui-space-2);
-  }
+  width: 100%;
 }
 
-// Adornment container — wraps input with start/end adornments inside field-shell border
-.hasAdornment {
-  @include field-shell;
+// Adornments and shortcuts share one painted shell. The input remains the
+// semantic control while every sibling participates intrinsically in layout.
+.hasAdornment,
+.inputContainer:has(> .shortcut) {
+  @include field.size("md");
+  @include field.shell;
 
-  height: var(--fui-input-height, $fui-input-height);
-  min-height: var(--fui-target-size-min, $fui-target-size-min);
-  gap: var(--fui-space-2, $fui-space-2);
-  padding: 0 var(--fui-space-2, $fui-space-2);
-  border-radius: var(--fui-radius-md, $fui-radius-md);
+  gap: action.gap("md");
 
   &:has(.sm) {
-    height: var(--fui-input-height-sm, $fui-input-height-sm);
+    @include field.size("sm");
+
+    gap: action.gap("sm");
   }
 
-  &:has(.lg) {
-    height: var(--fui-input-height-lg, $fui-input-height-lg);
+  &:has(.md) {
+    @include field.size("md");
   }
 
-  &:has(> .shortcut) {
-    padding-right: calc(
-      var(--fui-space-2, #{$fui-space-2}) + var(--fui-kbd-reserved-width, 2.714rem)
-    );
+  &:has(.lg) {
+    @include field.size("lg");
+
+    gap: action.gap("lg");
   }
 
   &:focus-within {
-    @include field-shell-focus;
+    @include field.focus-state;
   }
 
   // Strip the input's own shell when inside adornment container
@@ -122,7 +135,7 @@
     height: 100%;
     border: none;
     background: transparent;
-    padding: 0;
+    padding-inline: 0;
     box-shadow: none;
 
     &:focus-visible {
@@ -133,7 +146,7 @@
 
   // Error state on adornment container
   &:has(.error) {
-    border-color: var(--fui-color-danger-text, $fui-color-danger-text);
+    @include field.invalid-state;
 
     &:focus-within {
       border-color: var(--fui-color-danger-text, $fui-color-danger-text);
@@ -159,36 +172,36 @@
   color: var(--fui-text-secondary, $fui-text-secondary);
 
   svg {
-    width: var(--fui-icon-sm, $fui-icon-sm);
-    height: var(--fui-icon-sm, $fui-icon-sm);
+    @include action.glyph("md");
   }
 }
 
-// Kept as fallback for direct usage
-.hasShortcut {
-  padding-right: var(--fui-kbd-reserved-width, 2.714rem);
+.hasAdornment:has(.sm) .adornment svg {
+  @include action.glyph("sm");
+}
+
+.hasAdornment:has(.lg) .adornment svg {
+  @include action.glyph("lg");
 }
 
 .shortcut {
-  position: absolute;
-  right: var(--fui-space-1, $fui-space-1);
-  top: 50%;
-  transform: translateY(-50%);
+  @include typography.role("caption");
+
   display: inline-flex;
   align-items: center;
   justify-content: center;
-  gap: var(--fui-kbd-gap, calc(var(--fui-space-px, #{$fui-space-px}) * 2));
-  min-width: var(--fui-kbd-min-width, 1.714rem);
-  height: var(--fui-kbd-height, 1.286rem);
-  padding: 0 var(--fui-kbd-padding-x, $fui-space-0-75);
+  flex: 0 0 auto;
+  gap: var(--fui-raw-space-2, 2px);
+  min-inline-size: var(--fui-raw-space-24, 24px);
+  block-size: var(--fui-raw-space-20, 20px);
+  margin-inline-start: auto;
+  padding-inline: var(--fui-raw-space-4, 4px);
   font-family: var(--fui-font-mono, $fui-font-mono);
-  font-size: var(--fui-kbd-font-size, $fui-font-size-2xs);
-  font-weight: var(--fui-font-weight-medium, $fui-font-weight-medium);
-  line-height: 1;
   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: 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;
@@ -202,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 {

package/src/components/Input/index.tsx

@@ -179,7 +179,6 @@ const InputRoot = React.forwardRef<HTMLInputElement, InputProps>(function Input(
     styles[size],
     error && styles.error,
     success && styles.success,
-    shortcut && styles.hasShortcut,
     inputClassName,
   ]
     .filter(Boolean)
@@ -194,7 +193,7 @@ const InputRoot = React.forwardRef<HTMLInputElement, InputProps>(function Input(
     .join(" ");
 
   const wrapperClasses = [styles.wrapper, className].filter(Boolean).join(" ");
-  const labelClasses = [styles.label, size === "sm" && styles.labelSm].filter(Boolean).join(" ");
+  const labelClasses = styles.label;
 
   const sharedInputProps = {
     ...nativeInputProps,