@usefragments/ui 1.6.0 → 2.0.0

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

@@ -1,14 +1,19 @@
-@use '../../tokens/variables' as *;
-@use '../../tokens/mixins' as *;
-@use '../../recipes/action';
-@use '../../recipes/field';
-@use '../../recipes/popup';
-
-// 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;
 
 .wrapper {
   @include field.wrapper;
@@ -44,7 +49,6 @@ $fui-colorpicker-pointer-border: 2px !default;
     min-width: 80px;
     flex: 0 0 auto;
   }
-
 }
 
 .sizeMd {
@@ -75,7 +79,6 @@ $fui-colorpicker-pointer-border: 2px !default;
   .hexInput {
     min-width: 120px;
   }
-
 }
 
 .inputWrapper {
@@ -89,7 +92,27 @@ $fui-colorpicker-pointer-border: 2px !default;
   @include field.shell;
 
   flex-shrink: 0;
+
+  &:focus-visible,
+  &[data-popup-open] {
+    @include field.focus-state;
+  }
+
+  .wrapper[data-invalid] & {
+    @include field.invalid-state;
+
+    // Focused while invalid keeps the danger edge and takes the danger ring,
+    // the same pairing Input and Textarea render. Without it the ring stays
+    // accent-coloured and the control reads half-valid at the moment the user
+    // is actually in it.
+    &:focus-visible,
+    &[data-popup-open] {
+      @include field.invalid-focus-state;
+    }
+  }
+
   // Disabled state (opacity + pointer-events) comes from @include interactive-base.
+  @include high-contrast-outline;
 }
 
 // Hex input wrapper (using Input component)
@@ -112,8 +135,6 @@ $fui-colorpicker-pointer-border: 2px !default;
 .popup {
   @include popup.container;
 
-  border-radius: var(--fui-radius-lg, $fui-radius-lg);
-
   // react-colorful styling overrides
   :global(.react-colorful) {
     width: var(--fui-colorpicker-size, #{$fui-colorpicker-size});
@@ -133,22 +154,11 @@ $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);
   }
 }
 
-// ============================================
-// Accessibility: High Contrast Mode
-// ============================================
-
-@media (prefers-contrast: more) {
-  .swatch {
-    border-width: 2px;
-    border-color: var(--fui-text-primary, $fui-text-primary);
-  }
-}
-
 // ============================================
 // Accessibility: Reduced Motion
 // ============================================

package/src/components/ColorPicker/index.tsx

@@ -25,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"
@@ -55,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>,
@@ -166,6 +167,7 @@ const ColorPickerRoot = React.forwardRef<HTMLDivElement, ColorPickerProps>(funct
             className={styles.swatch}
             style={{ backgroundColor: displayValue }}
             disabled={disabled}
+            aria-invalid={error || undefined}
             aria-label={label ? `Edit ${label} color` : "Edit color"}
           />
           <BasePopover.Portal>
@@ -192,6 +194,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": [

package/src/components/Combobox/Combobox.module.scss

@@ -1,5 +1,6 @@
 @use "../../tokens/variables" as *;
 @use "../../tokens/mixins" as *;
+@use "../../tokens/measurements.generated" as measurements;
 @use "../../recipes/action";
 @use "../../recipes/field";
 @use "../../recipes/layout";
@@ -44,9 +45,20 @@
   }
 
   &:has([data-disabled]) {
-    background-color: var(--fui-field-bg-disabled, $fui-bg-tertiary);
-    color: var(--fui-text-tertiary, $fui-text-tertiary);
+    @include field.disabled-state;
   }
+
+  .wrapper[data-invalid] & {
+    @include field.invalid-state;
+
+    // Focused while invalid keeps the danger edge and takes the danger ring,
+    // the same pairing Input and Textarea render.
+    &:focus-within {
+      @include field.invalid-focus-state;
+    }
+  }
+
+  @include high-contrast-outline;
 }
 
 // Size variants for input wrapper — override --_field-h.
@@ -67,7 +79,7 @@
   flex: 1;
   min-width: layout.measure("inline-floor");
   min-block-size: 0;
-  padding: 0;
+  padding: var(--fui-raw-space-0, #{measurements.raw-space(0)});
   background: transparent;
   border: none;
   border-radius: var(--fui-radius-sm, $fui-radius-sm);
@@ -183,7 +195,7 @@
 
 // Positioner — z-index must exceed Dialog positioner (51)
 .positioner {
-  z-index: 52;
+  z-index: var(--fui-overlay-layer-anchored, #{$fui-overlay-layer-anchored});
   outline: none;
 }
 
@@ -279,21 +291,6 @@
   @include popup.group-label;
 }
 
-// ============================================
-// Accessibility: High Contrast Mode
-// ============================================
-
-@media (prefers-contrast: more) {
-  .inputWrapper {
-    border-width: 2px;
-    border-color: var(--fui-text-primary, $fui-text-primary);
-
-    &:focus-within {
-      border-color: var(--fui-color-accent, $fui-color-accent);
-    }
-  }
-}
-
 // ============================================
 // Accessibility: Reduced Motion
 // ============================================

package/src/components/Combobox/index.tsx

@@ -4,10 +4,7 @@ import * as React from "react";
 import { Combobox as BaseCombobox } from "@base-ui/react/combobox";
 import { useResolvedControlSize } from "../ComponentDefaults";
 import { mergeAriaIds, useFormFieldIds, type FormFieldProps } from "../../utils/aria";
-import {
-  POPUP_OFFSET_PX,
-  resolvePopupViewportRows,
-} from "../../recipes/popup";
+import { POPUP_OFFSET_PX, resolvePopupViewportRows } from "../../recipes/popup";
 import styles from "./Combobox.module.scss";
 
 // ============================================
@@ -181,6 +178,9 @@ interface ComboboxContextValue {
   size: "sm" | "md" | "lg";
   // Id applied to Combobox.Input so a native <label htmlFor> can target it.
   inputId?: string;
+  /** Mirrors the wrapper's `data-invalid` onto the input as `aria-invalid`, so
+   * assistive tech hears the state the danger edge is painting. */
+  invalid?: boolean;
 }
 
 const EMPTY_STATIC_LABELS = new Map<string, string>();
@@ -293,6 +293,27 @@ function filterStaticChildren(
   };
 }
 
+/**
+ * True when the consumer already supplied a `Combobox.Empty` slot anywhere in
+ * the content. Used to decide whether the built-in "no results" fallback is
+ * needed — without it an unmatched query renders an empty, collapsed popup.
+ */
+function containsEmptySlot(node: React.ReactNode): boolean {
+  let found = false;
+  React.Children.forEach(node, (child) => {
+    if (found || !React.isValidElement(child)) return;
+    if (child.type === ComboboxEmpty) {
+      found = true;
+      return;
+    }
+    const props = child.props as { children?: React.ReactNode };
+    if (props.children !== undefined && containsEmptySlot(props.children)) {
+      found = true;
+    }
+  });
+  return found;
+}
+
 // ============================================
 // Components
 // ============================================
@@ -404,6 +425,7 @@ const ComboboxRoot = React.forwardRef<HTMLDivElement, ComboboxProps>(function Co
       registerTrigger,
       size,
       inputId,
+      invalid: hasError,
     }),
     [
       placeholder,
@@ -416,14 +438,17 @@ const ComboboxRoot = React.forwardRef<HTMLDivElement, ComboboxProps>(function Co
       registerTrigger,
       size,
       inputId,
+      hasError,
     ]
   );
 
   const wrapperClasses = [styles.wrapper, className].filter(Boolean).join(" ");
   const helperClasses = [styles.helper, hasError && styles.helperError].filter(Boolean).join(" ");
 
+  // data-invalid lets the shell pick up the error border, the same hook Select,
+  // DatePicker and RadioGroup use; without it `error` renders only the message.
   const wrapperContent = (inner: React.ReactNode) => (
-    <div ref={ref} className={wrapperClasses}>
+    <div ref={ref} className={wrapperClasses} data-invalid={hasError || undefined}>
       {inner}
       {helperText && (
         <span id={helperId} className={helperClasses}>
@@ -572,6 +597,7 @@ function ComboboxInput({
           placeholder={context.selectedValues.length === 0 ? inputPlaceholder : undefined}
           id={inputId}
           className={classes}
+          aria-invalid={context.invalid || undefined}
         />
         {renderTrigger && (
           <BaseCombobox.Trigger className={styles.trigger}>
@@ -589,6 +615,7 @@ function ComboboxInput({
         placeholder={inputPlaceholder}
         id={inputId}
         className={classes}
+        aria-invalid={context.invalid || undefined}
       />
       {renderTrigger && (
         <BaseCombobox.Trigger className={styles.trigger}>
@@ -631,6 +658,14 @@ function ComboboxContent({
     () => filterStaticChildren(children, visibleValues),
     [children, visibleValues]
   );
+  // No matches and no author-supplied empty slot would leave a bare, collapsed
+  // popup, so fall back to a readable "no results" row.
+  const popupChildren =
+    filteredContent.visibleItemCount === 0 && !containsEmptySlot(children) ? (
+      <ComboboxEmpty>No results found</ComboboxEmpty>
+    ) : (
+      filteredContent.children
+    );
 
   const popupStyle =
     maxVisibleItems != null
@@ -650,7 +685,7 @@ function ComboboxContent({
       >
         <BaseCombobox.Popup {...htmlProps} className={popupClasses} style={popupStyle}>
           <ComboboxFilteredItemIndexContext.Provider value={filteredItemIndices}>
-            {filteredContent.children}
+            {popupChildren}
           </ComboboxFilteredItemIndexContext.Provider>
         </BaseCombobox.Popup>
       </BaseCombobox.Positioner>

package/src/components/Command/Command.contract.json

@@ -1,16 +1,9 @@
 {
   "$schema": "https://usefragments.com/schemas/contract.v1.json",
   "name": "Command",
-  "description": "A searchable command palette for quick actions. Combines an input with a filterable, keyboard-navigable list of actions.",
+  "description": "Filters a list of actions as the user types.",
   "category": "navigation",
-  "tags": [
-    "command",
-    "palette",
-    "search",
-    "spotlight",
-    "quick-actions",
-    "cmdk"
-  ],
+  "tags": ["command", "palette", "search", "spotlight", "quick-actions", "cmdk"],
   "status": "stable",
   "sourcePath": "src/components/Command/index.tsx",
   "exportName": "Command",
@@ -54,27 +47,32 @@
       "description": "Whether to loop keyboard navigation",
       "default": "true",
       "required": false
+    },
+    "hosted": {
+      "type": "boolean",
+      "description": "The Command sits inside another surface (a Popover, a Dialog) that draws the frame, so it draws none of its own",
+      "default": "false",
+      "required": false
     }
   },
   "usage": {
     "when": [
-      "Quick-access command palettes (Ctrl+K)",
-      "Searchable action menus",
-      "Inline command lists with filtering",
-      "Application-wide search interfaces"
+      "A keyboard shortcut that jumps anywhere",
+      "Action lists too long to scan",
+      "Inline lists that need filtering",
+      "Search across everything the app can do"
     ],
     "whenNot": [
-      "Simple dropdown menus (use Menu)",
-      "Form field selection (use Select or Combobox)",
-      "Static navigation (use Sidebar or Tabs)",
-      "Search with complex result types (build custom)"
+      "A handful of actions (use Menu)",
+      "Picking a value for a form (use Select or Combobox)",
+      "Fixed navigation (use Sidebar or Tabs)"
     ],
     "guidelines": [
-      "Compose inside Dialog for modal command palette usage",
-      "Use Command.Group to organize items by category",
-      "Provide Command.Empty for no-results feedback",
-      "Use keywords prop for items that should match on aliases",
-      "Keep item labels short and action-oriented"
+      "Wrap in Dialog for the summon-anywhere palette",
+      "Group by category once the list gets long",
+      "Always supply Command.Empty",
+      "Add keywords so aliases and synonyms match",
+      "Label rows with a verb"
     ],
     "accessibility": [
       "Uses combobox + listbox ARIA pattern",
@@ -86,22 +84,22 @@
   "examples": [
     {
       "name": "Default",
-      "description": "Inline command list with search",
+      "description": "Search field over a flat list.",
       "code": "<div style={{ maxWidth: '400px', width: '100%' }}>\n  <Command>\n    <Command.Input placeholder=\"Type a command...\" />\n    <Command.List>\n      <Command.Item onItemSelect={() => {}}>Open File</Command.Item>\n      <Command.Item onItemSelect={() => {}}>Save Document</Command.Item>\n      <Command.Item onItemSelect={() => {}}>Print</Command.Item>\n      <Command.Empty>No results found.</Command.Empty>\n    </Command.List>\n  </Command>\n</div>"
     },
     {
       "name": "Dialog Command Palette",
-      "description": "Command palette inside a Dialog",
-      "code": "<Dialog>\n  <Dialog.Trigger asChild>\n    <Button variant=\"secondary\">Open Command Palette</Button>\n  </Dialog.Trigger>\n  <Dialog.Content size=\"sm\">\n    <Command>\n      <Command.Input placeholder=\"Search commands...\" />\n      <Command.List>\n        <Command.Group heading=\"Actions\">\n          <Command.Item onItemSelect={() => {}}>New File</Command.Item>\n          <Command.Item onItemSelect={() => {}}>Open Recent</Command.Item>\n        </Command.Group>\n        <Command.Separator />\n        <Command.Group heading=\"Settings\">\n          <Command.Item onItemSelect={() => {}}>Preferences</Command.Item>\n          <Command.Item onItemSelect={() => {}}>Keyboard Shortcuts</Command.Item>\n        </Command.Group>\n        <Command.Empty>No results found.</Command.Empty>\n      </Command.List>\n    </Command>\n  </Dialog.Content>\n</Dialog>"
+      "description": "The same list summoned over the page.",
+      "code": "<Dialog>\n  <Dialog.Trigger asChild>\n    <Button variant=\"soft\">Open Command Palette</Button>\n  </Dialog.Trigger>\n  <Dialog.Content width=\"sm\">\n    <Command>\n      <Command.Input placeholder=\"Search commands...\" />\n      <Command.List>\n        <Command.Group heading=\"Actions\">\n          <Command.Item onItemSelect={() => {}}>New File</Command.Item>\n          <Command.Item onItemSelect={() => {}}>Open Recent</Command.Item>\n        </Command.Group>\n        <Command.Separator />\n        <Command.Group heading=\"Settings\">\n          <Command.Item onItemSelect={() => {}}>Preferences</Command.Item>\n          <Command.Item onItemSelect={() => {}}>Keyboard Shortcuts</Command.Item>\n        </Command.Group>\n        <Command.Empty>No results found.</Command.Empty>\n      </Command.List>\n    </Command>\n  </Dialog.Content>\n</Dialog>"
     },
     {
       "name": "With Groups",
-      "description": "Organized by category groups",
+      "description": "Category labels survive filtering.",
       "code": "<div style={{ maxWidth: '400px', width: '100%' }}>\n  <Command>\n    <Command.Input placeholder=\"Search...\" />\n    <Command.List>\n      <Command.Group heading=\"Suggestions\">\n        <Command.Item onItemSelect={() => {}}>Calendar</Command.Item>\n        <Command.Item onItemSelect={() => {}}>Calculator</Command.Item>\n      </Command.Group>\n      <Command.Separator />\n      <Command.Group heading=\"Settings\">\n        <Command.Item onItemSelect={() => {}}>Profile</Command.Item>\n        <Command.Item onItemSelect={() => {}}>Billing</Command.Item>\n        <Command.Item disabled onItemSelect={() => {}}>\n          Team (coming soon)\n        </Command.Item>\n      </Command.Group>\n      <Command.Empty>No results found.</Command.Empty>\n    </Command.List>\n  </Command>\n</div>"
     },
     {
       "name": "With Icons",
-      "description": "Items with leading icons",
+      "description": "Leading glyphs speed up scanning.",
       "code": "<div style={{ maxWidth: '400px', width: '100%' }}>\n  <Command>\n    <Command.Input placeholder=\"What do you need?\" />\n    <Command.List>\n      <Command.Item onItemSelect={() => {}}>\n        <span style={{ marginRight: '0.5rem', fontSize: '1rem' }}>+</span> New Document\n      </Command.Item>\n      <Command.Item onItemSelect={() => {}}>\n        <span style={{ marginRight: '0.5rem', fontSize: '1rem' }}>{'>'}</span> Open Folder\n      </Command.Item>\n      <Command.Item onItemSelect={() => {}}>\n        <span style={{ marginRight: '0.5rem', fontSize: '1rem' }}>?</span> Search\n      </Command.Item>\n      <Command.Empty>No results found.</Command.Empty>\n    </Command.List>\n  </Command>\n</div>"
     }
   ],
@@ -132,26 +130,12 @@
       "Command.Item keywords: string[] - extra filter terms",
       "Command.Item onItemSelect: (value, event) => void - selection handler"
     ],
-    "a11yRules": [
-      "A11Y_COMBOBOX_ROLE",
-      "A11Y_LISTBOX_ROLE",
-      "A11Y_ACTIVE_DESCENDANT"
-    ]
+    "a11yRules": ["A11Y_COMBOBOX_ROLE", "A11Y_LISTBOX_ROLE", "A11Y_ACTIVE_DESCENDANT"]
   },
   "ai": {
     "compositionPattern": "compound",
-    "subComponents": [
-      "Input",
-      "List",
-      "Item",
-      "Group",
-      "Empty",
-      "Separator"
-    ],
-    "requiredChildren": [
-      "Input",
-      "List"
-    ],
+    "subComponents": ["Input", "List", "Item", "Group", "Empty", "Separator"],
+    "requiredChildren": ["Input", "List"],
     "commonPatterns": [
       "<Dialog><Dialog.Trigger><Button>Open Palette</Button></Dialog.Trigger><Dialog.Content size=\"sm\"><Command><Command.Input placeholder=\"Search...\" /><Command.List><Command.Group heading=\"Actions\"><Command.Item onItemSelect={() => {}}>Action 1</Command.Item></Command.Group><Command.Empty>No results.</Command.Empty></Command.List></Command></Dialog.Content></Dialog>"
     ]