@usefragments/ui 1.5.4 → 1.7.0

package/src/components/ColorPicker/ColorPicker.contract.json

@@ -1,16 +1,9 @@
 {
   "$schema": "https://usefragments.com/schemas/contract.v1.json",
   "name": "ColorPicker",
-  "description": "Color selection control with hex input and visual picker. Displays a swatch that opens a full color picker on click.",
-  "category": "forms",
-  "tags": [
-    "color",
-    "picker",
-    "input",
-    "hex",
-    "swatch",
-    "theme"
-  ],
+  "description": "Selects a color through a visual picker and hexadecimal input.",
+  "category": "inputs",
+  "tags": ["color", "picker", "input", "hex", "swatch", "theme"],
   "status": "stable",
   "dependencies": [
     {
@@ -88,11 +81,7 @@
       "description": "Size variant",
       "default": "md",
       "required": false,
-      "values": [
-        "sm",
-        "md",
-        "lg"
-      ]
+      "values": ["sm", "md", "lg"]
     },
     "showInput": {
       "type": "boolean",
@@ -103,68 +92,67 @@
   },
   "usage": {
     "when": [
-      "Theme customization interfaces",
-      "Brand color selection",
-      "Design tool color inputs",
-      "User preference settings for colors"
+      "Theme and brand customisation",
+      "Any colour the user must pick freely",
+      "Design tool inputs"
     ],
     "whenNot": [
-      "Predefined color options only (use RadioGroup with swatches)",
-      "Simple color display without editing (use a colored Badge)",
-      "Color indication only (use semantic color tokens)"
+      "A fixed palette (use RadioGroup with swatches)",
+      "Showing a colour without editing it (use a tinted Badge)",
+      "Status colour that should come from a token"
     ],
     "guidelines": [
-      "Always provide a label to describe what the color is for",
-      "Use helperText to explain color usage or constraints",
-      "Consider providing color presets alongside the picker for common choices",
-      "Validate hex format (#RRGGBB) on input"
+      "Label says what the colour is for",
+      "Use helperText for constraints, such as contrast rules",
+      "Offer presets next to the picker for the common choices",
+      "Validate the hex as #RRGGBB before accepting it"
     ],
     "accessibility": [
-      "Label is associated with the color input",
-      "Swatch button has appropriate aria-label",
-      "Color picker popup is keyboard accessible",
-      "Hex input allows direct text entry"
+      "Label is tied to the hex input",
+      "The swatch button carries its own aria-label",
+      "The picker popup is reachable from the keyboard",
+      "Users can type a hex instead of dragging"
     ]
   },
   "examples": [
     {
       "name": "Default",
-      "description": "Basic color picker with label",
+      "description": "Swatch opens the picker; the hex field accepts typing.",
       "code": "<ColorPicker\n  label=\"Brand Color\"\n  defaultValue=\"#3b82f6\"\n/>"
     },
     {
       "name": "With Helper Text",
-      "description": "Color picker with helper text",
+      "description": "Supporting line says where the colour will be used.",
       "code": "<ColorPicker\n  label=\"Primary Color\"\n  defaultValue=\"#10b981\"\n  helperText=\"This color will be used for buttons and links\"\n/>"
     },
     {
       "name": "Controlled",
-      "description": "Controlled color picker that logs changes",
+      "description": "The parent owns the value and sees every change.",
       "code": "<ControlledColorPickerDemo />"
     },
     {
       "name": "Multiple Pickers",
-      "description": "Multiple color pickers for theme configuration",
+      "description": "A stacked set reads as one palette.",
       "code": "<div style={{ display: 'flex', flexDirection: 'column', gap: '16px', maxWidth: '240px' }}>\n  <ColorPicker label=\"Primary\" defaultValue=\"#3b82f6\" />\n  <ColorPicker label=\"Success\" defaultValue=\"#22c55e\" />\n  <ColorPicker label=\"Warning\" defaultValue=\"#f59e0b\" />\n  <ColorPicker label=\"Danger\" defaultValue=\"#ef4444\" />\n</div>"
     },
     {
       "name": "Compact",
-      "description": "Small size with swatch only (no input)",
+      "description": "showInput={false} drops the hex field, leaving a swatch row.",
       "code": "<div style={{ display: 'flex', gap: '8px', alignItems: 'center' }}>\n  <ColorPicker defaultValue=\"#ef4444\" size=\"sm\" showInput={false} />\n  <ColorPicker defaultValue=\"#f59e0b\" size=\"sm\" showInput={false} />\n  <ColorPicker defaultValue=\"#22c55e\" size=\"sm\" showInput={false} />\n  <ColorPicker defaultValue=\"#3b82f6\" size=\"sm\" showInput={false} />\n</div>"
     },
     {
       "name": "Sizes",
-      "description": "Different size variants",
+      "description": "Three swatch sizes: sm, md, lg.",
       "code": "<div style={{ display: 'flex', flexDirection: 'column', gap: '16px', maxWidth: '240px' }}>\n  <ColorPicker label=\"Small\" defaultValue=\"#3b82f6\" size=\"sm\" />\n  <ColorPicker label=\"Medium (default)\" defaultValue=\"#3b82f6\" size=\"md\" />\n  <ColorPicker label=\"Large\" defaultValue=\"#3b82f6\" size=\"lg\" />\n</div>"
     },
     {
       "name": "Error State",
-      "description": "Color picker with error styling",
-      "code": "<ColorPicker\n  label=\"Brand Color\"\n  defaultValue=\"#000000\"\n  error\n  helperText=\"Please select a valid brand color\"\n/>"
+      "description": "Red border on the hex field, and the reason below it.",
+      "code": "<ColorPicker\n  label=\"Brand Color\"\n  defaultValue=\"#7c3aed\"\n  error\n  helperText=\"This color fails contrast against the page background\"\n/>"
     },
     {
       "name": "Disabled",
-      "description": "Disabled color picker",
+      "description": "Swatch will not open and the hex field will not accept typing.",
       "code": "<ColorPicker\n  label=\"Locked Color\"\n  defaultValue=\"#64748b\"\n  helperText=\"This color cannot be changed\"\n  disabled\n/>"
     }
   ],
@@ -198,18 +186,11 @@
       "size: sm|md|lg - size variant",
       "showInput: boolean - show hex input field"
     ],
-    "a11yRules": [
-      "A11Y_LABEL_REQUIRED",
-      "A11Y_FOCUS_VISIBLE",
-      "A11Y_TARGET_SIZE_MIN"
-    ]
+    "a11yRules": ["A11Y_LABEL_REQUIRED", "A11Y_FOCUS_VISIBLE", "A11Y_TARGET_SIZE_MIN"]
   },
   "ai": {
     "compositionPattern": "compound",
-    "subComponents": [
-      "Root",
-      "preload"
-    ]
+    "subComponents": ["Root", "preload"]
   },
   "provenance": {
     "source": "migrated",

package/src/components/ColorPicker/ColorPicker.module.scss

@@ -1,73 +1,96 @@
-@use '../../tokens/variables' as *;
-@use '../../tokens/mixins' as *;
-
-// Local component tokens
+@use "../../tokens/variables" as *;
+@use "../../tokens/mixins" as *;
+@use "../../recipes/action";
+@use "../../recipes/field";
+@use "../../recipes/popup";
+
+// Local component tokens.
+//
+// The raw pixel values in this file (200px here, and the 80px/120px hex-input
+// min-widths below) are deliberate, not missed tokens: react-colorful lays the
+// saturation/hue canvas out in fixed pixels, and the hex field has to stay wide
+// enough for a full "#rrggbb" string. Spacing tokens do not map onto either
+// constraint, so these stay literal.
 $fui-colorpicker-size: 200px !default; // react-colorful saturation/hue square
 $fui-colorpicker-hue-height: $fui-target-size-min !default;
 $fui-colorpicker-pointer-size: $fui-target-size-min !default;
-$fui-colorpicker-pointer-border: 2px !default;
 
-// Form field wrapper (label + helper + error)
-@include form-field-wrapper;
+.wrapper {
+  @include field.wrapper;
+}
+
+.label {
+  @include field.label;
+}
+
+.helper {
+  @include field.helper;
+}
+
+.helperError,
+.errorMessage {
+  @include field.error;
+}
 
 // Size variants
 .sizeSm {
   .inputWrapper {
-    gap: var(--fui-space-1, $fui-space-1);
+    gap: action.gap("sm");
   }
 
   .swatch {
-    width: var(--fui-input-height-sm, $fui-input-height-sm);
-    height: var(--fui-input-height-sm, $fui-input-height-sm);
+    @include field.size("sm");
+
+    width: field.track("sm");
+    height: field.track("sm");
   }
 
   .hexInput {
     min-width: 80px;
     flex: 0 0 auto;
   }
-
-  .label {
-    font-size: var(--fui-font-size-xs, $fui-font-size-xs);
-  }
 }
 
 .sizeMd {
-  // Default size - no overrides needed
+  .inputWrapper {
+    gap: action.gap("md");
+  }
+
+  .swatch {
+    @include field.size("md");
+
+    width: field.track("md");
+    height: field.track("md");
+  }
 }
 
 .sizeLg {
   .inputWrapper {
-    gap: var(--fui-space-3, $fui-space-3);
+    gap: action.gap("lg");
   }
 
   .swatch {
-    width: var(--fui-input-height-lg, $fui-input-height-lg);
-    height: var(--fui-input-height-lg, $fui-input-height-lg);
+    @include field.size("lg");
+
+    width: field.track("lg");
+    height: field.track("lg");
   }
 
   .hexInput {
     min-width: 120px;
   }
-
-  .label {
-    font-size: var(--fui-font-size-base, $fui-font-size-base);
-  }
 }
 
 .inputWrapper {
   display: flex;
-  gap: var(--fui-space-2, $fui-space-2);
   align-items: center;
 }
 
 .swatch {
   @include button-reset;
   @include interactive-base;
-  @include min-target-size;
-  @include field-shell;
+  @include field.shell;
 
-  width: var(--fui-input-height, $fui-input-height);
-  height: var(--fui-input-height, $fui-input-height);
   flex-shrink: 0;
   // Disabled state (opacity + pointer-events) comes from @include interactive-base.
 }
@@ -80,7 +103,7 @@ $fui-colorpicker-pointer-border: 2px !default;
 
 // Style the actual input field inside Input component
 .hexInputField {
-  font-family: var(--fui-font-mono, $fui-font-mono) !important;
+  font-family: var(--fui-font-mono, $fui-font-mono);
   text-transform: lowercase;
 }
 
@@ -90,11 +113,9 @@ $fui-colorpicker-pointer-border: 2px !default;
 }
 
 .popup {
-  @include surface-elevated;
+  @include popup.container;
 
-  border-color: var(--fui-form-group-border, $fui-border);
   border-radius: var(--fui-radius-lg, $fui-radius-lg);
-  padding: var(--fui-space-2, $fui-space-2);
 
   // react-colorful styling overrides
   :global(.react-colorful) {
@@ -115,7 +136,7 @@ $fui-colorpicker-pointer-border: 2px !default;
   :global(.react-colorful__pointer) {
     width: var(--fui-colorpicker-pointer-size, #{$fui-colorpicker-pointer-size});
     height: var(--fui-colorpicker-pointer-size, #{$fui-colorpicker-pointer-size});
-    border: $fui-colorpicker-pointer-border solid var(--fui-text-inverse, $fui-text-inverse);
+    border: var(--fui-stroke-default, 2px) solid var(--fui-text-inverse, $fui-text-inverse);
     box-shadow: var(--fui-shadow-md, $fui-shadow-md);
   }
 }
@@ -126,7 +147,7 @@ $fui-colorpicker-pointer-border: 2px !default;
 
 @media (prefers-contrast: more) {
   .swatch {
-    border-width: 2px;
+    border-width: var(--fui-stroke-default, 2px);
     border-color: var(--fui-text-primary, $fui-text-primary);
   }
 }

package/src/components/ColorPicker/index.tsx

@@ -2,6 +2,7 @@
 
 import * as React from "react";
 import { Popover as BasePopover } from "@base-ui/react/popover";
+import { POPUP_OFFSET_PX } from "../../recipes/popup";
 
 // ============================================
 // Lazy-loaded dependency (react-colorful)
@@ -24,7 +25,7 @@ function loadColorfulDeps(): Promise<void> {
         _HexColorPicker = rc.HexColorPicker;
       } catch {
         _colorfulFailed = true;
-        if (process.env.NODE_ENV === "development") {
+        if (isDevelopmentBuild()) {
           console.warn(
             "[@usefragments/ui] ColorPicker: react-colorful is not installed. " +
               "Install it with: npm install react-colorful"
@@ -54,6 +55,7 @@ import { Field } from "@base-ui/react/field";
 import { useResolvedControlSize } from "../ComponentDefaults";
 import { Input } from "../Input";
 import styles from "./ColorPicker.module.scss";
+import { isDevelopmentBuild } from "../../utils/env";
 
 export interface ColorPickerProps extends Omit<
   React.HTMLAttributes<HTMLDivElement>,
@@ -171,7 +173,7 @@ const ColorPickerRoot = React.forwardRef<HTMLDivElement, ColorPickerProps>(funct
             <BasePopover.Positioner
               side="bottom"
               align="start"
-              sideOffset={4}
+              sideOffset={POPUP_OFFSET_PX}
               className={styles.positioner}
             >
               <BasePopover.Popup
@@ -191,6 +193,9 @@ const ColorPickerRoot = React.forwardRef<HTMLDivElement, ColorPickerProps>(funct
             onChange={handleInputChange}
             onBlur={handleInputBlur}
             disabled={disabled}
+            // Without this the hex field keeps its neutral border while the
+            // helper text turns red, so the error reads as a stray message.
+            error={error}
             size={size}
             className={styles.hexInput}
             inputClassName={styles.hexInputField}

package/src/components/Combobox/Combobox.contract.json

@@ -1,8 +1,8 @@
 {
   "$schema": "https://usefragments.com/schemas/contract.v1.json",
   "name": "Combobox",
-  "description": "Searchable select input that filters a dropdown list of options as you type. Supports single and multiple selection with chips.",
-  "category": "forms",
+  "description": "Filters a list of options as the user types.",
+  "category": "inputs",
   "tags": ["combobox", "autocomplete", "search", "select", "typeahead", "form", "multiselect"],
   "status": "stable",
   "sourcePath": "src/components/Combobox/index.tsx",
@@ -133,86 +133,85 @@
   },
   "usage": {
     "when": [
-      "Users need to search/filter through many options",
-      "Large option lists where scrolling is impractical",
-      "When users might know what they are looking for",
-      "Autocomplete or typeahead functionality",
-      "Multiple selections from a searchable list"
+      "Lists too long to scan by eye",
+      "The user roughly knows the value they want",
+      "Autocomplete or typeahead",
+      "Multi-select from a searchable list"
     ],
     "whenNot": [
-      "Few options (under 5) - use Select or RadioGroup",
-      "Free-form text with no predefined options - use Input",
-      "Non-searchable single selection - use Select",
-      "Actions, not selection - use Menu"
+      "Under five options (use Select or RadioGroup)",
+      "Free-form text with no known options (use Input)",
+      "Short list nobody needs to search (use Select)",
+      "Actions rather than values (use Menu)"
     ],
     "guidelines": [
-      "Include a placeholder that explains what to search for",
-      "Use label prop for accessible field labeling",
-      "Use helperText for guidance and error for validation messages",
-      "Provide an empty state message when no results match",
-      "Group related options with Combobox.Group for large lists",
-      "Static items may be composed through fragments and groups; filtering preserves wrapper composition",
-      "Keep option text concise and searchable",
-      "Use multiple prop for multi-select with chip display"
+      "Placeholder names what is searchable",
+      "Set label so the field is announced",
+      "helperText for guidance, error for the failure reason",
+      "Override the built-in \"No results found\" with Combobox.Empty when you have better wording",
+      "Group related options with Combobox.Group in long lists",
+      "Filtering keeps wrapper composition, so groups and fragments survive",
+      "Keep option text short and searchable",
+      "multiple turns selections into removable chips"
     ],
     "accessibility": [
-      "Full keyboard navigation support (arrow keys, enter, escape)",
-      "Type-ahead filtering within options",
-      "Proper ARIA combobox roles and attributes",
-      "Screen reader announcements for filtered results",
-      "Chip removal via keyboard in multi-select mode"
+      "Arrow keys, Enter, and Escape all work",
+      "Typing filters the list in place",
+      "Correct ARIA combobox roles and attributes",
+      "Filtered result counts are announced",
+      "Chips can be removed from the keyboard"
     ]
   },
   "examples": [
     {
       "name": "Default",
-      "description": "Basic searchable select",
+      "description": "Type to narrow the list; unmatched queries show a no-results row.",
       "code": "<StatefulCombobox placeholder=\"Select a fruit\">\n  <Combobox.Input />\n  <Combobox.Content>\n    <Combobox.Item value=\"apple\">Apple</Combobox.Item>\n    <Combobox.Item value=\"banana\">Banana</Combobox.Item>\n    <Combobox.Item value=\"orange\">Orange</Combobox.Item>\n    <Combobox.Item value=\"grape\">Grape</Combobox.Item>\n  </Combobox.Content>\n</StatefulCombobox>"
     },
     {
       "name": "Multiple Selection",
-      "description": "Multi-select with chips",
+      "description": "Each pick becomes a removable chip in the field.",
       "code": "<StatefulCombobox multiple placeholder=\"Select fruits...\">\n  <Combobox.Input />\n  <Combobox.Content>\n    <Combobox.Item value=\"apple\">Apple</Combobox.Item>\n    <Combobox.Item value=\"banana\">Banana</Combobox.Item>\n    <Combobox.Item value=\"orange\">Orange</Combobox.Item>\n    <Combobox.Item value=\"grape\">Grape</Combobox.Item>\n    <Combobox.Item value=\"mango\">Mango</Combobox.Item>\n    <Combobox.Item value=\"kiwi\">Kiwi</Combobox.Item>\n  </Combobox.Content>\n</StatefulCombobox>"
     },
     {
       "name": "With Label and Helper Text",
-      "description": "Combobox with built-in label and helper text",
+      "description": "Helper text tells the user the field is searchable.",
       "code": "<StatefulCombobox\n  label=\"Assignee\"\n  placeholder=\"Search assignees...\"\n  helperText=\"Type to filter the list of available assignees.\"\n>\n  <Combobox.Input />\n  <Combobox.Content>\n    <Combobox.Empty>No matches</Combobox.Empty>\n    <Combobox.Item value=\"alice\">Alice Johnson</Combobox.Item>\n    <Combobox.Item value=\"bob\">Bob Chen</Combobox.Item>\n    <Combobox.Item value=\"carol\">Carol Smith</Combobox.Item>\n  </Combobox.Content>\n</StatefulCombobox>"
     },
     {
       "name": "Error State",
-      "description": "Validation error with message",
-      "code": "<Combobox\n  label=\"Reviewer\"\n  placeholder=\"Search reviewers...\"\n  error=\"Please select a reviewer\"\n  disabled\n>\n  <Combobox.Input />\n  <Combobox.Content>\n    <Combobox.Item value=\"alice\">Alice</Combobox.Item>\n  </Combobox.Content>\n</Combobox>"
+      "description": "Red border, and the message replaces helper text.",
+      "code": "<Combobox\n  label=\"Reviewer\"\n  placeholder=\"Search reviewers...\"\n  error=\"Please select a reviewer\"\n>\n  <Combobox.Input />\n  <Combobox.Content>\n    <Combobox.Item value=\"alice\">Alice</Combobox.Item>\n  </Combobox.Content>\n</Combobox>"
     },
     {
       "name": "With Groups",
-      "description": "Options organized into groups",
+      "description": "Headed sections stay intact while filtering.",
       "code": "<StatefulCombobox placeholder=\"Search countries...\">\n  <Combobox.Input />\n  <Combobox.Content>\n    <>\n      <Combobox.Group>\n        <Combobox.GroupLabel>North America</Combobox.GroupLabel>\n        <Combobox.Item value=\"us\">United States</Combobox.Item>\n        <Combobox.Item value=\"ca\">Canada</Combobox.Item>\n        <Combobox.Item value=\"mx\">Mexico</Combobox.Item>\n      </Combobox.Group>\n      <Combobox.Group>\n        <Combobox.GroupLabel>Europe</Combobox.GroupLabel>\n        <Combobox.Item value=\"uk\">United Kingdom</Combobox.Item>\n        <Combobox.Item value=\"de\">Germany</Combobox.Item>\n        <Combobox.Item value=\"fr\">France</Combobox.Item>\n      </Combobox.Group>\n      <Combobox.Empty>No matching country</Combobox.Empty>\n    </>\n  </Combobox.Content>\n</StatefulCombobox>"
     },
     {
       "name": "With Empty State",
-      "description": "Shows message when no results match",
-      "code": "<StatefulCombobox placeholder=\"Search programming languages...\">\n  <Combobox.Input />\n  <Combobox.Content>\n    <Combobox.Empty>No results found</Combobox.Empty>\n    <Combobox.Item value=\"js\">JavaScript</Combobox.Item>\n    <Combobox.Item value=\"ts\">TypeScript</Combobox.Item>\n    <Combobox.Item value=\"py\">Python</Combobox.Item>\n    <Combobox.Item value=\"rs\">Rust</Combobox.Item>\n    <Combobox.Item value=\"go\">Go</Combobox.Item>\n  </Combobox.Content>\n</StatefulCombobox>"
+      "description": "Combobox.Empty replaces the default no-results wording.",
+      "code": "<StatefulCombobox placeholder=\"Filter languages...\">\n  <Combobox.Input />\n  <Combobox.Content>\n    <Combobox.Empty>No language matches that search</Combobox.Empty>\n    <Combobox.Item value=\"js\">JavaScript</Combobox.Item>\n    <Combobox.Item value=\"ts\">TypeScript</Combobox.Item>\n    <Combobox.Item value=\"py\">Python</Combobox.Item>\n    <Combobox.Item value=\"rs\">Rust</Combobox.Item>\n    <Combobox.Item value=\"go\">Go</Combobox.Item>\n  </Combobox.Content>\n</StatefulCombobox>"
     },
     {
       "name": "Scrollable List",
-      "description": "Long list with scroll hint — shows 4 items with half-peek of the 5th",
+      "description": "Caps at four rows and half-shows the fifth as a scroll hint.",
       "code": "<StatefulCombobox placeholder=\"Search languages...\">\n  <Combobox.Input />\n  <Combobox.Content>\n    <Combobox.Empty>No results found</Combobox.Empty>\n    <Combobox.Item value=\"js\">JavaScript</Combobox.Item>\n    <Combobox.Item value=\"ts\">TypeScript</Combobox.Item>\n    <Combobox.Item value=\"py\">Python</Combobox.Item>\n    <Combobox.Item value=\"rs\">Rust</Combobox.Item>\n    <Combobox.Item value=\"go\">Go</Combobox.Item>\n    <Combobox.Item value=\"rb\">Ruby</Combobox.Item>\n    <Combobox.Item value=\"java\">Java</Combobox.Item>\n    <Combobox.Item value=\"swift\">Swift</Combobox.Item>\n    <Combobox.Item value=\"kt\">Kotlin</Combobox.Item>\n    <Combobox.Item value=\"cpp\">C++</Combobox.Item>\n  </Combobox.Content>\n</StatefulCombobox>"
     },
     {
       "name": "Custom Max Visible Items",
-      "description": "Show 6 items before scrolling with half-peek scroll hint",
+      "description": "maxVisibleItems raises the cap to six rows.",
       "code": "<StatefulCombobox placeholder=\"Search cities...\">\n  <Combobox.Input />\n  <Combobox.Content maxVisibleItems={6}>\n    <Combobox.Empty>No results found</Combobox.Empty>\n    <Combobox.Item value=\"nyc\">New York</Combobox.Item>\n    <Combobox.Item value=\"lon\">London</Combobox.Item>\n    <Combobox.Item value=\"tok\">Tokyo</Combobox.Item>\n    <Combobox.Item value=\"par\">Paris</Combobox.Item>\n    <Combobox.Item value=\"syd\">Sydney</Combobox.Item>\n    <Combobox.Item value=\"ber\">Berlin</Combobox.Item>\n    <Combobox.Item value=\"tor\">Toronto</Combobox.Item>\n    <Combobox.Item value=\"sin\">Singapore</Combobox.Item>\n    <Combobox.Item value=\"dub\">Dubai</Combobox.Item>\n    <Combobox.Item value=\"sao\">São Paulo</Combobox.Item>\n  </Combobox.Content>\n</StatefulCombobox>"
     },
     {
       "name": "Disabled",
-      "description": "Disabled combobox",
+      "description": "Dimmed and unfocusable.",
       "code": "<Combobox disabled placeholder=\"Search...\">\n  <Combobox.Input />\n  <Combobox.Content>\n    <Combobox.Item value=\"1\">Option 1</Combobox.Item>\n  </Combobox.Content>\n</Combobox>"
     },
     {
       "name": "Explicit Trigger",
-      "description": "Hide the built-in input trigger when rendering a separate Combobox.Trigger",
-      "code": "<StatefulCombobox placeholder=\"Search assignees...\">\n  <Combobox.Input showTrigger={false} />\n  <Combobox.Trigger aria-label=\"Open assignee list\" />\n  <Combobox.Content>\n    <Combobox.Item value=\"alice\">Alice</Combobox.Item>\n    <Combobox.Item value=\"bob\">Bob</Combobox.Item>\n    <Combobox.Item value=\"carol\">Carol</Combobox.Item>\n  </Combobox.Content>\n</StatefulCombobox>"
+      "description": "showTrigger={false} hands the open control to your own Combobox.Trigger.",
+      "code": "<StatefulCombobox placeholder=\"Search assignees...\">\n  <div style={{ display: 'flex', alignItems: 'center', gap: '8px' }}>\n    <Combobox.Input showTrigger={false} />\n    <Combobox.Trigger aria-label=\"Open assignee list\" />\n  </div>\n  <Combobox.Content>\n    <Combobox.Item value=\"alice\">Alice</Combobox.Item>\n    <Combobox.Item value=\"bob\">Bob</Combobox.Item>\n    <Combobox.Item value=\"carol\">Carol</Combobox.Item>\n  </Combobox.Content>\n</StatefulCombobox>"
     }
   ],
   "relations": [