# Autocomplete

A controlled search field with inline, sheet, or fullscreen result presentation and explicit loading, error, empty, and disabled states.

Version: 0.2.0-preview.1 (preview)
Content digest: 70ac710f4d22dce040e7ac593379ba8aca9dcb59a0b9c0f839819cae0e2bb721
Contract kind: source-derived
Source: packages/design-system/src/components/forms/Autocomplete/Autocomplete.tsx

## Guidance

{
  "summary": "A controlled search field with inline, sheet, or fullscreen result presentation and explicit loading, error, empty, and disabled states.",
  "guidance": [
    {
      "heading": "Overview",
      "body": "A controlled type-ahead field: a search input over a `role=\"listbox\"` of results. You own the\n`query` state, debouncing, and fetching, and feed it `items`; it renders the `loading`, `error`,\nand `emptyState` for you."
    },
    {
      "heading": "When to use",
      "body": "Reach for `Autocomplete` when the option set is too long or too dynamic to show at once and the\nuser needs to type to narrow it — broker search, address lookup, anything backed by a query. It is\npresentation only: fetching and filtering stay in the app.\n\n-   Short, fixed list of a handful of options? Use `Select` — no typing needed.\n-   A list of one-off commands rather than values to filter? That's a `Menu` (`selectionMode=\"none\"`).\n\n`error` and `emptyState` are distinct: `error` means the fetch failed, `emptyState` means it\nsucceeded with no matches. In-app it powers the address lookup in the data-removal profile\n(`AddressesField.tsx`), where it also joins keyboard next-field navigation."
    }
  ],
  "usage": [],
  "examples": [],
  "source": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.mdx",
  "status": "local-preview",
  "note": "Guidance is read from local documentation, originally imported from the frozen source. Platform assertions in guidance are not parity verification."
}

## Contract and public API

```json
{
  "props": [
    {
      "name": "query",
      "type": "string",
      "declared_type": "string",
      "required": true,
      "description": "Text shown in the search field. Display only: `items` is never filtered by it.",
      "source": {
        "path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.tsx",
        "line": 40
      }
    },
    {
      "name": "onQueryChange",
      "type": "(query: string) => void",
      "declared_type": "(query: string) => void",
      "required": true,
      "description": "Called with the new text on each keystroke, and with `''` when the clear action fires.",
      "source": {
        "path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.tsx",
        "line": 42
      }
    },
    {
      "name": "items",
      "type": "AutocompleteItem[]",
      "declared_type": "AutocompleteItem[]",
      "required": true,
      "description": "Results to render, already filtered and ordered by the app.",
      "source": {
        "path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.tsx",
        "line": 44
      }
    },
    {
      "name": "onSelect",
      "type": "(item: AutocompleteItem) => void",
      "declared_type": "(item: AutocompleteItem) => void",
      "required": true,
      "description": "Called with the tapped item. Disabled items never reach it.",
      "source": {
        "path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.tsx",
        "line": 46
      }
    },
    {
      "name": "loading",
      "type": "boolean | undefined",
      "declared_type": "boolean",
      "required": false,
      "description": "Replaces the list with a spinner and sets `aria-busy`. Wins over `error` and `items`.",
      "source": {
        "path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.tsx",
        "line": 48
      },
      "values": [
        false,
        true
      ],
      "values_complete": true
    },
    {
      "name": "error",
      "type": "React.ReactNode",
      "declared_type": "React.ReactNode",
      "required": false,
      "description": "Error copy shown instead of results.",
      "source": {
        "path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.tsx",
        "line": 50
      }
    },
    {
      "name": "emptyState",
      "type": "React.ReactNode",
      "declared_type": "React.ReactNode",
      "required": false,
      "description": "Empty state shown when there are no results.",
      "source": {
        "path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.tsx",
        "line": 52
      },
      "default": "'No results found.'",
      "default_kind": "source-expression"
    },
    {
      "name": "displayMode",
      "type": "AutocompleteDisplayMode | undefined",
      "declared_type": "AutocompleteDisplayMode",
      "required": false,
      "description": "Result presentation mode. Defaults to `inline`.",
      "source": {
        "path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.tsx",
        "line": 54
      },
      "values": [
        "fullscreen",
        "inline",
        "sheet"
      ],
      "values_complete": true,
      "default": "'inline'",
      "default_kind": "source-expression"
    },
    {
      "name": "placeholder",
      "type": "string | undefined",
      "declared_type": "string",
      "required": false,
      "description": "Placeholder in the search field. Defaults to `Search`.",
      "source": {
        "path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.tsx",
        "line": 56
      },
      "default": "'Search'",
      "default_kind": "source-expression"
    },
    {
      "name": "size",
      "type": "AutocompleteSize",
      "declared_type": "AutocompleteSize",
      "required": true,
      "description": "Search field and result row size.",
      "source": {
        "path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.tsx",
        "line": 58
      },
      "values": [
        "md",
        "sm"
      ],
      "values_complete": true
    },
    {
      "name": "surface",
      "type": "import(\"@cloakedinc/design-system\").InputSurface | undefined",
      "declared_type": "AutocompleteSurface",
      "required": false,
      "description": "Search field background treatment. Defaults to `default`; use `raised` inside a raised form.",
      "source": {
        "path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.tsx",
        "line": 60
      },
      "values": [
        "default",
        "raised"
      ],
      "values_complete": true,
      "default": "'default'",
      "default_kind": "source-expression"
    },
    {
      "name": "enterBehavior",
      "type": "InputEnterBehavior | undefined",
      "declared_type": "InputEnterBehavior",
      "required": false,
      "description": "Return-key behavior for the search field. Left unset, `SearchField`'s `callback` applies.",
      "source": {
        "path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.tsx",
        "line": 62
      },
      "values": [
        "advance",
        "callback"
      ],
      "values_complete": true
    },
    {
      "name": "enterKeyHint",
      "type": "InputEnterKeyHint | undefined",
      "declared_type": "InputEnterKeyHint",
      "required": false,
      "description": "Native on-screen keyboard return key hint for the search field.",
      "source": {
        "path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.tsx",
        "line": 64
      },
      "values": [
        "done",
        "enter",
        "go",
        "next",
        "previous",
        "search",
        "send"
      ],
      "values_complete": true
    },
    {
      "name": "ariaLabel",
      "type": "string",
      "declared_type": "string",
      "required": true,
      "description": "Accessible label for the search field.",
      "source": {
        "path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.tsx",
        "line": 66
      }
    },
    {
      "name": "disabled",
      "type": "boolean | undefined",
      "declared_type": "boolean",
      "required": false,
      "description": "Prevents query and selection interaction.",
      "source": {
        "path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.tsx",
        "line": 68
      },
      "values": [
        false,
        true
      ],
      "values_complete": true
    },
    {
      "name": "haptic",
      "type": "HapticFeedback | undefined",
      "declared_type": "HapticFeedback",
      "required": false,
      "description": "Haptic feedback for result selection. Defaults to `true` (`selection`).",
      "source": {
        "path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.tsx",
        "line": 70
      },
      "values": [
        "error",
        "heavy",
        "light",
        "medium",
        "selection",
        "success",
        "warning",
        false,
        true
      ],
      "values_complete": true,
      "default": "true",
      "default_kind": "source-expression"
    },
    {
      "name": "className",
      "type": "string | undefined",
      "declared_type": "string",
      "required": false,
      "description": "",
      "source": {
        "path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.tsx",
        "line": 71
      }
    },
    {
      "name": "style",
      "type": "React.CSSProperties | undefined",
      "declared_type": "React.CSSProperties",
      "required": false,
      "description": "",
      "source": {
        "path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.tsx",
        "line": 72
      }
    },
    {
      "name": "testId",
      "type": "string | undefined",
      "declared_type": "string",
      "required": false,
      "description": "Optional test selector. Result rows derive `${testId}-${item.value}`.",
      "source": {
        "path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.tsx",
        "line": 74
      }
    }
  ],
  "prop_shapes": {},
  "api": {
    "method": "typescript-type-checker",
    "typescript_version": "5.9.3",
    "public_export": "Autocomplete",
    "public_path": "Autocomplete",
    "import_path": "@cloakedinc/design-system",
    "root_kind": "component",
    "entrypoints": [
      {
        "name": "Autocomplete",
        "signature": 1,
        "visibility": "public",
        "source": {
          "path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.tsx",
          "line": 80
        },
        "props_type": "AutocompleteProps",
        "props": [
          {
            "name": "query",
            "type": "string",
            "declared_type": "string",
            "required": true,
            "description": "Text shown in the search field. Display only: `items` is never filtered by it.",
            "source": {
              "path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.tsx",
              "line": 40
            }
          },
          {
            "name": "onQueryChange",
            "type": "(query: string) => void",
            "declared_type": "(query: string) => void",
            "required": true,
            "description": "Called with the new text on each keystroke, and with `''` when the clear action fires.",
            "source": {
              "path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.tsx",
              "line": 42
            }
          },
          {
            "name": "items",
            "type": "AutocompleteItem[]",
            "declared_type": "AutocompleteItem[]",
            "required": true,
            "description": "Results to render, already filtered and ordered by the app.",
            "source": {
              "path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.tsx",
              "line": 44
            }
          },
          {
            "name": "onSelect",
            "type": "(item: AutocompleteItem) => void",
            "declared_type": "(item: AutocompleteItem) => void",
            "required": true,
            "description": "Called with the tapped item. Disabled items never reach it.",
            "source": {
              "path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.tsx",
              "line": 46
            }
          },
          {
            "name": "loading",
            "type": "boolean | undefined",
            "declared_type": "boolean",
            "required": false,
            "description": "Replaces the list with a spinner and sets `aria-busy`. Wins over `error` and `items`.",
            "source": {
              "path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.tsx",
              "line": 48
            },
            "values": [
              false,
              true
            ],
            "values_complete": true
          },
          {
            "name": "error",
            "type": "React.ReactNode",
            "declared_type": "React.ReactNode",
            "required": false,
            "description": "Error copy shown instead of results.",
            "source": {
              "path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.tsx",
              "line": 50
            }
          },
          {
            "name": "emptyState",
            "type": "React.ReactNode",
            "declared_type": "React.ReactNode",
            "required": false,
            "description": "Empty state shown when there are no results.",
            "source": {
              "path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.tsx",
              "line": 52
            },
            "default": "'No results found.'",
            "default_kind": "source-expression"
          },
          {
            "name": "displayMode",
            "type": "AutocompleteDisplayMode | undefined",
            "declared_type": "AutocompleteDisplayMode",
            "required": false,
            "description": "Result presentation mode. Defaults to `inline`.",
            "source": {
              "path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.tsx",
              "line": 54
            },
            "values": [
              "fullscreen",
              "inline",
              "sheet"
            ],
            "values_complete": true,
            "default": "'inline'",
            "default_kind": "source-expression"
          },
          {
            "name": "placeholder",
            "type": "string | undefined",
            "declared_type": "string",
            "required": false,
            "description": "Placeholder in the search field. Defaults to `Search`.",
            "source": {
              "path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.tsx",
              "line": 56
            },
            "default": "'Search'",
            "default_kind": "source-expression"
          },
          {
            "name": "size",
            "type": "AutocompleteSize",
            "declared_type": "AutocompleteSize",
            "required": true,
            "description": "Search field and result row size.",
            "source": {
              "path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.tsx",
              "line": 58
            },
            "values": [
              "md",
              "sm"
            ],
            "values_complete": true
          },
          {
            "name": "surface",
            "type": "import(\"@cloakedinc/design-system\").InputSurface | undefined",
            "declared_type": "AutocompleteSurface",
            "required": false,
            "description": "Search field background treatment. Defaults to `default`; use `raised` inside a raised form.",
            "source": {
              "path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.tsx",
              "line": 60
            },
            "values": [
              "default",
              "raised"
            ],
            "values_complete": true,
            "default": "'default'",
            "default_kind": "source-expression"
          },
          {
            "name": "enterBehavior",
            "type": "InputEnterBehavior | undefined",
            "declared_type": "InputEnterBehavior",
            "required": false,
            "description": "Return-key behavior for the search field. Left unset, `SearchField`'s `callback` applies.",
            "source": {
              "path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.tsx",
              "line": 62
            },
            "values": [
              "advance",
              "callback"
            ],
            "values_complete": true
          },
          {
            "name": "enterKeyHint",
            "type": "InputEnterKeyHint | undefined",
            "declared_type": "InputEnterKeyHint",
            "required": false,
            "description": "Native on-screen keyboard return key hint for the search field.",
            "source": {
              "path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.tsx",
              "line": 64
            },
            "values": [
              "done",
              "enter",
              "go",
              "next",
              "previous",
              "search",
              "send"
            ],
            "values_complete": true
          },
          {
            "name": "ariaLabel",
            "type": "string",
            "declared_type": "string",
            "required": true,
            "description": "Accessible label for the search field.",
            "source": {
              "path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.tsx",
              "line": 66
            }
          },
          {
            "name": "disabled",
            "type": "boolean | undefined",
            "declared_type": "boolean",
            "required": false,
            "description": "Prevents query and selection interaction.",
            "source": {
              "path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.tsx",
              "line": 68
            },
            "values": [
              false,
              true
            ],
            "values_complete": true
          },
          {
            "name": "haptic",
            "type": "HapticFeedback | undefined",
            "declared_type": "HapticFeedback",
            "required": false,
            "description": "Haptic feedback for result selection. Defaults to `true` (`selection`).",
            "source": {
              "path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.tsx",
              "line": 70
            },
            "values": [
              "error",
              "heavy",
              "light",
              "medium",
              "selection",
              "success",
              "warning",
              false,
              true
            ],
            "values_complete": true,
            "default": "true",
            "default_kind": "source-expression"
          },
          {
            "name": "className",
            "type": "string | undefined",
            "declared_type": "string",
            "required": false,
            "description": "",
            "source": {
              "path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.tsx",
              "line": 71
            }
          },
          {
            "name": "style",
            "type": "React.CSSProperties | undefined",
            "declared_type": "React.CSSProperties",
            "required": false,
            "description": "",
            "source": {
              "path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.tsx",
              "line": 72
            }
          },
          {
            "name": "testId",
            "type": "string | undefined",
            "declared_type": "string",
            "required": false,
            "description": "Optional test selector. Result rows derive `${testId}-${item.value}`.",
            "source": {
              "path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.tsx",
              "line": 74
            }
          }
        ],
        "branches": [],
        "constraints": [],
        "extraction_status": "extracted"
      }
    ],
    "type_sources": [
      {
        "path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.tsx",
        "line": 11,
        "name": "AutocompleteDisplayMode",
        "code": "export type AutocompleteDisplayMode = 'inline' | 'sheet' | 'fullscreen';"
      },
      {
        "path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.tsx",
        "line": 12,
        "name": "AutocompleteSize",
        "code": "export type AutocompleteSize = 'sm' | 'md';"
      },
      {
        "path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.tsx",
        "line": 13,
        "name": "AutocompleteSurface",
        "code": "export type AutocompleteSurface = SearchFieldSurface;"
      },
      {
        "path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.tsx",
        "line": 19,
        "name": "AutocompleteItem",
        "code": "export interface AutocompleteItem {\n    /** Identifies the row; used as the React key and as the `${testId}-${value}` suffix. */\n    value: string;\n    /** Primary row text, sized from `size`: `body-small` at `sm`, `body` at `md`. */\n    label: React.ReactNode;\n    /** Second line under the label, always `body-small`. */\n    description?: React.ReactNode;\n    /** Optional leading visual, usually an `Icon`, `Avatar`, or `SFIcon`. */\n    leading?: React.ReactNode;\n    /** Optional visual after the copy, e.g. a chevron or a count. */\n    trailing?: React.ReactNode;\n    /** Prevents this result from being selected. */\n    disabled?: boolean;\n}"
      },
      {
        "path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.tsx",
        "line": 38,
        "name": "AutocompleteProps",
        "code": "export interface AutocompleteProps {\n    /** Text shown in the search field. Display only: `items` is never filtered by it. */\n    query: string;\n    /** Called with the new text on each keystroke, and with `''` when the clear action fires. */\n    onQueryChange: (query: string) => void;\n    /** Results to render, already filtered and ordered by the app. */\n    items: AutocompleteItem[];\n    /** Called with the tapped item. Disabled items never reach it. */\n    onSelect: (item: AutocompleteItem) => void;\n    /** Replaces the list with a spinner and sets `aria-busy`. Wins over `error` and `items`. */\n    loading?: boolean;\n    /** Error copy shown instead of results. */\n    error?: React.ReactNode;\n    /** Empty state shown when there are no results. */\n    emptyState?: React.ReactNode;\n    /** Result presentation mode. Defaults to `inline`. */\n    displayMode?: AutocompleteDisplayMode;\n    /** Placeholder in the search field. Defaults to `Search`. */\n    placeholder?: string;\n    /** Search field and result row size. */\n    size: AutocompleteSize;\n    /** Search field background treatment. Defaults to `default`; use `raised` inside a raised form. */\n    surface?: AutocompleteSurface;\n    /** Return-key behavior for the search field. Left unset, `SearchField`'s `callback` applies. */\n    enterBehavior?: InputEnterBehavior;\n    /** Native on-screen keyboard return key hint for the search field. */\n    enterKeyHint?: InputEnterKeyHint;\n    /** Accessible label for the search field. */\n    ariaLabel: string;\n    /** Prevents query and selection interaction. */\n    disabled?: boolean;\n    /** Haptic feedback for result selection. Defaults to `true` (`selection`). */\n    haptic?: HapticFeedback;\n    className?: string;\n    style?: React.CSSProperties;\n    /** Optional test selector. Result rows derive `${testId}-${item.value}`. */\n    testId?: string;\n}"
      },
      {
        "path": "packages/design-system/src/components/forms/SearchField/SearchField.tsx",
        "line": 15,
        "name": "SearchFieldSurface",
        "code": "export type SearchFieldSurface = InputSurface;"
      },
      {
        "path": "packages/design-system/src/components/primitives/Input/Input.tsx",
        "line": 9,
        "name": "InputEnterBehavior",
        "code": "export type InputEnterBehavior = 'advance' | 'callback';"
      },
      {
        "path": "packages/design-system/src/components/primitives/Input/Input.tsx",
        "line": 10,
        "name": "InputEnterKeyHint",
        "code": "export type InputEnterKeyHint = 'enter' | 'done' | 'go' | 'next' | 'previous' | 'search' | 'send';"
      },
      {
        "path": "packages/design-system/src/components/primitives/Input/Input.tsx",
        "line": 28,
        "name": "InputSurface",
        "code": "export type InputSurface = 'default' | 'raised';"
      },
      {
        "path": "packages/design-system/src/tokens/CdsHaptic.ts",
        "line": 6,
        "name": "HapticFeedback",
        "code": "export type HapticFeedback = boolean | HapticType;"
      },
      {
        "path": "packages/design-system/src/tokens/HapticType.ts",
        "line": 2,
        "name": "HapticType",
        "code": "export type HapticType = 'light' | 'medium' | 'heavy' | 'success' | 'warning' | 'error' | 'selection';"
      }
    ],
    "defaults_policy": "Only explicit destructured parameter initializers are extracted. Other runtime defaults remain in implementation source."
  },
  "spec": {
    "$schema": "../../../specs/component-spec.schema.json",
    "identity": {
      "name": "Autocomplete",
      "status": "preview",
      "version": "1.1.0",
      "summary": "A controlled search field with inline, sheet, or fullscreen result presentation and explicit loading, error, empty, and disabled states."
    },
    "parts": [
      {
        "id": "root",
        "label": "Root",
        "description": "Stacks the search field and result surface at the selected density."
      },
      {
        "id": "search-field",
        "label": "Search field",
        "description": "Owns the query, search semantics, loading indicator, clear action, and the surface treatment."
      },
      {
        "id": "result-surface",
        "label": "Result surface",
        "description": "Provides the labelled listbox and selected display mode."
      },
      {
        "id": "option",
        "label": "Option",
        "description": "Pressable result row with optional leading, description, and trailing content."
      },
      {
        "id": "feedback",
        "label": "Feedback",
        "description": "Replaces options with loading, error, or empty-state content."
      }
    ],
    "allowedDesignChoices": {
      "variants": {
        "base": {
          "label": "Base",
          "description": "One controlled search-and-pick pattern configured through mode and size axes."
        }
      },
      "sizes": {
        "sm": {
          "label": "Small"
        },
        "md": {
          "label": "Medium"
        }
      },
      "modes": {
        "inline": {
          "label": "Inline",
          "description": "Keeps a bounded result list directly below the search field."
        },
        "sheet": {
          "label": "Sheet",
          "description": "Uses a taller result surface with top-only rounding for sheet composition."
        },
        "fullscreen": {
          "label": "Fullscreen",
          "description": "Uses an unrounded, minimum-height result surface for a full-screen composition."
        }
      }
    },
    "variants": [
      {
        "id": "base",
        "label": "Base",
        "description": "Controlled search and listbox composition with mode, size, and async feedback kept orthogonal.",
        "platforms": [
          "ios",
          "android",
          "web"
        ]
      }
    ],
    "sizes": [
      {
        "id": "sm",
        "label": "Small",
        "description": "Compact search shell, 4-unit stack gap, and tighter result-row padding."
      },
      {
        "id": "md",
        "label": "Medium",
        "description": "Standard search shell, 8-unit stack gap, and roomier result rows."
      }
    ],
    "measurements": [
      {
        "id": "small-stack-gap",
        "label": "Small search-to-results gap",
        "kind": "exact",
        "token": "--cds-space-4",
        "value": 4,
        "unit": "px",
        "appliesTo": [
          "root",
          "sm"
        ]
      },
      {
        "id": "medium-stack-gap",
        "label": "Medium search-to-results gap",
        "kind": "exact",
        "token": "--cds-space-8",
        "value": 8,
        "unit": "px",
        "appliesTo": [
          "root",
          "md"
        ]
      },
      {
        "id": "medium-option-horizontal-padding",
        "label": "Medium option horizontal padding",
        "kind": "exact",
        "token": "--cds-space-16",
        "value": 16,
        "unit": "px",
        "appliesTo": [
          "option",
          "md"
        ]
      }
    ],
    "layout": {
      "alignment": "The search field and result surface fill the root width; option visuals align to the row start.",
      "flow": "Search field precedes one listbox whose contents are options or a single feedback state.",
      "notes": [
        "Keep data fetching and debouncing outside the component.",
        "Leading and trailing option content never consume the flexible copy column."
      ]
    },
    "typographyAndColor": {
      "typography": [
        {
          "label": "Option label",
          "description": "Medium rows use body text; compact rows use body-small text.",
          "token": "--cds-type-body-size"
        }
      ],
      "colors": [
        {
          "label": "Result surface",
          "description": "Uses the raised semantic surface.",
          "token": "--cds-bg-surface"
        },
        {
          "label": "Primary copy",
          "description": "Uses primary text emphasis for option labels.",
          "token": "--cds-text-primary"
        },
        {
          "label": "Secondary copy",
          "description": "Uses secondary emphasis for descriptions and neutral feedback.",
          "token": "--cds-text-secondary"
        },
        {
          "label": "Error copy",
          "description": "Uses the semantic danger text role.",
          "token": "--cds-status-danger-solid"
        }
      ]
    },
    "states": [
      {
        "id": "results",
        "label": "Results",
        "description": "Shows enabled and disabled options for the current query."
      },
      {
        "id": "loading",
        "label": "Loading",
        "description": "Marks the listbox busy and replaces options with a labelled spinner."
      },
      {
        "id": "empty",
        "label": "Empty",
        "description": "Shows calm no-results copy after a successful query with no matches."
      },
      {
        "id": "error",
        "label": "Error",
        "description": "Shows failure copy instead of empty-state copy or stale results."
      },
      {
        "id": "disabled",
        "label": "Disabled",
        "description": "Blocks query editing and every option press."
      }
    ],
    "behavior": [
      {
        "label": "Controlled query",
        "description": "Request each query update while the parent owns filtering, fetching, and the rendered query."
      },
      {
        "label": "Selection",
        "description": "Emit the complete selected item exactly once and ignore disabled options."
      },
      {
        "label": "Presentation modes",
        "description": "Change only result-surface composition; mode does not alter search or selection semantics."
      },
      {
        "label": "Surface treatment",
        "description": "The search field forwards a surface treatment (default or raised). Use raised inside a raised form so the field reads as an input rather than blending into the container."
      }
    ],
    "accessibility": [
      {
        "label": "Search name",
        "description": "Require a stable accessible name for the search field."
      },
      {
        "label": "Result relationship",
        "description": "Connect the search field to the labelled listbox and expose busy state during loading."
      },
      {
        "label": "Options",
        "description": "Expose each result as an option and preserve native disabled behavior."
      }
    ],
    "contentAdaptation": [
      {
        "label": "Long result copy",
        "description": "Allow labels and descriptions to wrap within the flexible copy column."
      },
      {
        "label": "Distinct feedback",
        "description": "Use empty copy only for successful zero-result queries and error copy only for failures."
      }
    ],
    "motionHaptics": {
      "motion": [
        {
          "label": "Stable replacement",
          "description": "Replace result and feedback content without moving the search field."
        }
      ],
      "haptics": [
        {
          "label": "Selection feedback",
          "description": "Request the selection haptic after an enabled option is chosen."
        }
      ]
    },
    "platformDifferences": [
      {
        "platforms": [
          "ios",
          "android"
        ],
        "description": "Sheet and fullscreen modes should use the host platform presentation container while web applies the documented result-surface geometry in place.",
        "rationale": "The interaction contract is shared, but native containers provide expected focus, keyboard, and dismissal behavior."
      }
    ]
  },
  "platforms": {
    "implemented": [
      "web"
    ],
    "native": "Imported design guidance only; no native implementation or parity verification in this preview.",
    "react": {
      "implementation": "local",
      "status": "preview",
      "parity": "web-reference"
    },
    "vue": {
      "implementation": "absent",
      "parity": "not-verified",
      "status": "reference-only"
    },
    "swift": {
      "implementation": "absent",
      "parity": "not-verified",
      "status": "reference-only"
    },
    "kotlin": {
      "implementation": "absent",
      "parity": "not-verified",
      "status": "reference-only"
    }
  },
  "tokens": [
    {
      "name": "--cds-space-4",
      "light": "4px",
      "dark": "4px"
    },
    {
      "name": "--cds-space-8",
      "light": "8px",
      "dark": "8px"
    },
    {
      "name": "--cds-space-16",
      "light": "16px",
      "dark": "16px"
    },
    {
      "name": "--cds-type-body-size",
      "light": "1rem",
      "dark": "1rem"
    },
    {
      "name": "--cds-bg-surface",
      "light": "#ffffff",
      "dark": "#1b1b18"
    },
    {
      "name": "--cds-text-primary",
      "light": "#141410",
      "dark": "#f3f1ed"
    },
    {
      "name": "--cds-text-secondary",
      "light": "#646260",
      "dark": "#ffffff99"
    },
    {
      "name": "--cds-status-danger-solid",
      "light": "#b83100",
      "dark": "#b83100"
    }
  ],
  "review": {
    "local_status": "not-reviewed",
    "source_approval": null,
    "imported_spec_status": "approved",
    "spec_origin": "imported-adapted",
    "local_spec_source_status": "approved",
    "imported_source_revision": "f96f416e1c3bfbfaffcd155a88b87b18b8bb25f1",
    "note": "Inherited specification status is provenance, not approval of the current local implementation or extracted contract."
  },
  "missing_facts": [
    {
      "code": "human-review-pending",
      "detail": "This local preview has no recorded human design or engineering sign-off."
    },
    {
      "code": "platform-parity-unverified",
      "detail": "Vue, Swift and Kotlin implementations are absent from this package; platform parity has not been verified."
    },
    {
      "code": "figma-mapping-unverified",
      "detail": "No current component-level Figma node and immutable revision have been verified for this contract."
    }
  ]
}
```

## Visual states

- [Playground](/storybook/iframe.html?id=cloaked-design-system-forms-autocomplete--playground&viewMode=story) | export: Playground | source: packages/design-system/src/components/forms/Autocomplete/Autocomplete.stories.tsx

- [Display Modes](/storybook/iframe.html?id=cloaked-design-system-forms-autocomplete--display-modes&viewMode=story) | export: DisplayModes | source: packages/design-system/src/components/forms/Autocomplete/Autocomplete.stories.tsx

- [Loading](/storybook/iframe.html?id=cloaked-design-system-forms-autocomplete--loading&viewMode=story) | export: Loading | source: packages/design-system/src/components/forms/Autocomplete/Autocomplete.stories.tsx

- [Empty](/storybook/iframe.html?id=cloaked-design-system-forms-autocomplete--empty&viewMode=story) | export: Empty | source: packages/design-system/src/components/forms/Autocomplete/Autocomplete.stories.tsx

- [Error](/storybook/iframe.html?id=cloaked-design-system-forms-autocomplete--error&viewMode=story) | export: Error | source: packages/design-system/src/components/forms/Autocomplete/Autocomplete.stories.tsx

- [Disabled](/storybook/iframe.html?id=cloaked-design-system-forms-autocomplete--disabled&viewMode=story) | export: Disabled | source: packages/design-system/src/components/forms/Autocomplete/Autocomplete.stories.tsx

- [Address Form Flow](/storybook/iframe.html?id=cloaked-design-system-forms-autocomplete--address-form-flow&viewMode=story) | export: AddressFormFlow | source: packages/design-system/src/components/forms/Autocomplete/Autocomplete.stories.tsx

- [Dark Theme](/storybook/iframe.html?id=cloaked-design-system-forms-autocomplete--dark-theme&viewMode=story) | export: DarkTheme | source: packages/design-system/src/components/forms/Autocomplete/Autocomplete.stories.tsx

Preview pending human sign-off. Source-derived APIs and successful checks do not certify accessibility, native parity or approval.