# SearchField

A controlled search input with search icon, return-key callback, optional loading indicator, and value-dependent clear action.

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

## Guidance

{
  "summary": "A controlled search input with search icon, return-key callback, optional loading indicator, and value-dependent clear action.",
  "guidance": [
    {
      "heading": "Overview",
      "body": "A dedicated search input — a leading search icon, an inline `loading` spinner, and a clear\naction that appears once there is a query."
    },
    {
      "heading": "When to use",
      "body": "Reach for `SearchField` when the control's whole job is to filter or query — a broker search,\na website picker, a list filter. It composes `Input` with `type=\"search\"`, defaults\nautocorrect/autocapitalize/spellcheck off so the field stays quiet, fires `onSearch` on the\nreturn key, and gives you the clear affordance for free.\n\n-   Just need a **single-line text value** (email, name, a bare `type=\"search\"` box) with no clear\n    button or search-key semantics? Use `Input` directly.\n-   Need the query to also **drive a results dropdown** the user picks from? Use `Autocomplete` —\n    `SearchField` is the search primitive inside it, so don't rebuild the dropdown around a bare\n    `SearchField`.\n\nIn-app it backs the automations website search (`WebsiteSearchView`) and the add-to-dashboard\npicker (`AddToDashboardBottomSheet`)."
    }
  ],
  "usage": [],
  "examples": [],
  "source": "packages/design-system/src/components/forms/SearchField/SearchField.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": "value",
      "type": "string",
      "declared_type": "string",
      "required": true,
      "description": "Query text to display; a non-empty value is also what reveals the clear action.",
      "source": {
        "path": "packages/design-system/src/components/forms/SearchField/SearchField.tsx",
        "line": 24
      }
    },
    {
      "name": "onChange",
      "type": "((value: string) => void) | undefined",
      "declared_type": "(value: string) => void",
      "required": false,
      "description": "Called with the new text on each keystroke, and with `''` when the clear action fires.",
      "source": {
        "path": "packages/design-system/src/components/forms/SearchField/SearchField.tsx",
        "line": 26
      }
    },
    {
      "name": "onSearch",
      "type": "((value: string) => void) | undefined",
      "declared_type": "(value: string) => void",
      "required": false,
      "description": "Called when the search key is pressed.",
      "source": {
        "path": "packages/design-system/src/components/forms/SearchField/SearchField.tsx",
        "line": 28
      }
    },
    {
      "name": "enterBehavior",
      "type": "InputEnterBehavior | undefined",
      "declared_type": "InputEnterBehavior",
      "required": false,
      "description": "Return-key behavior. Defaults to search callback behavior.",
      "source": {
        "path": "packages/design-system/src/components/forms/SearchField/SearchField.tsx",
        "line": 30
      },
      "values": [
        "advance",
        "callback"
      ],
      "values_complete": true,
      "default": "'callback'",
      "default_kind": "source-expression"
    },
    {
      "name": "enterKeyHint",
      "type": "InputEnterKeyHint | undefined",
      "declared_type": "InputEnterKeyHint",
      "required": false,
      "description": "Native on-screen keyboard return key hint. Defaults to `search`.",
      "source": {
        "path": "packages/design-system/src/components/forms/SearchField/SearchField.tsx",
        "line": 32
      },
      "values": [
        "done",
        "enter",
        "go",
        "next",
        "previous",
        "search",
        "send"
      ],
      "values_complete": true,
      "default": "'search'",
      "default_kind": "source-expression"
    },
    {
      "name": "onClear",
      "type": "(() => void) | undefined",
      "declared_type": "() => void",
      "required": false,
      "description": "Called after the clear action resets the query.",
      "source": {
        "path": "packages/design-system/src/components/forms/SearchField/SearchField.tsx",
        "line": 34
      }
    },
    {
      "name": "placeholder",
      "type": "string | undefined",
      "declared_type": "string",
      "required": false,
      "description": "Placeholder text. Defaults to `Search`.",
      "source": {
        "path": "packages/design-system/src/components/forms/SearchField/SearchField.tsx",
        "line": 36
      },
      "default": "'Search'",
      "default_kind": "source-expression"
    },
    {
      "name": "size",
      "type": "InputSize",
      "declared_type": "SearchFieldSize",
      "required": true,
      "description": "Field height and type scale, shared with the underlying `Input`. Required — there is no default.",
      "source": {
        "path": "packages/design-system/src/components/forms/SearchField/SearchField.tsx",
        "line": 38
      },
      "values": [
        "md",
        "sm"
      ],
      "values_complete": true
    },
    {
      "name": "loading",
      "type": "boolean | undefined",
      "declared_type": "boolean",
      "required": false,
      "description": "Shows a spinner in the trailing slot. Typing and clearing stay available.",
      "source": {
        "path": "packages/design-system/src/components/forms/SearchField/SearchField.tsx",
        "line": 40
      },
      "values": [
        false,
        true
      ],
      "values_complete": true
    },
    {
      "name": "disabled",
      "type": "boolean | undefined",
      "declared_type": "boolean",
      "required": false,
      "description": "Blocks typing and the clear action.",
      "source": {
        "path": "packages/design-system/src/components/forms/SearchField/SearchField.tsx",
        "line": 42
      },
      "values": [
        false,
        true
      ],
      "values_complete": true
    },
    {
      "name": "surface",
      "type": "InputSurface | undefined",
      "declared_type": "SearchFieldSurface",
      "required": false,
      "description": "Container background treatment.",
      "source": {
        "path": "packages/design-system/src/components/forms/SearchField/SearchField.tsx",
        "line": 44
      },
      "values": [
        "default",
        "raised"
      ],
      "values_complete": true,
      "default": "'default'",
      "default_kind": "source-expression"
    },
    {
      "name": "autoCorrect",
      "type": "\"on\" | \"off\" | undefined",
      "declared_type": "'on' | 'off'",
      "required": false,
      "description": "Native autocorrect hint. Defaults to `off` so search fields stay quiet.",
      "source": {
        "path": "packages/design-system/src/components/forms/SearchField/SearchField.tsx",
        "line": 46
      },
      "values": [
        "off",
        "on"
      ],
      "values_complete": true,
      "default": "'off'",
      "default_kind": "source-expression"
    },
    {
      "name": "autoCapitalize",
      "type": "\"none\" | \"on\" | \"off\" | \"sentences\" | \"words\" | \"characters\" | undefined",
      "declared_type": "'off' | 'none' | 'on' | 'sentences' | 'words' | 'characters'",
      "required": false,
      "description": "Native autocapitalize hint. Defaults to `off` so search fields stay quiet.",
      "source": {
        "path": "packages/design-system/src/components/forms/SearchField/SearchField.tsx",
        "line": 48
      },
      "values": [
        "characters",
        "none",
        "off",
        "on",
        "sentences",
        "words"
      ],
      "values_complete": true,
      "default": "'off'",
      "default_kind": "source-expression"
    },
    {
      "name": "spellCheck",
      "type": "boolean | undefined",
      "declared_type": "boolean",
      "required": false,
      "description": "Native spellcheck hint. Defaults to `false` so search fields stay quiet.",
      "source": {
        "path": "packages/design-system/src/components/forms/SearchField/SearchField.tsx",
        "line": 50
      },
      "values": [
        false,
        true
      ],
      "values_complete": true,
      "default": "false",
      "default_kind": "source-expression"
    },
    {
      "name": "ariaLabel",
      "type": "string | undefined",
      "declared_type": "string",
      "required": false,
      "description": "Accessible name when no visible label is associated with the field.",
      "source": {
        "path": "packages/design-system/src/components/forms/SearchField/SearchField.tsx",
        "line": 52
      },
      "default": "'Search'",
      "default_kind": "source-expression"
    },
    {
      "name": "ariaControls",
      "type": "string | undefined",
      "declared_type": "string",
      "required": false,
      "description": "ID of the result list controlled by this search field.",
      "source": {
        "path": "packages/design-system/src/components/forms/SearchField/SearchField.tsx",
        "line": 54
      }
    },
    {
      "name": "className",
      "type": "string | undefined",
      "declared_type": "string",
      "required": false,
      "description": "",
      "source": {
        "path": "packages/design-system/src/components/forms/SearchField/SearchField.tsx",
        "line": 55
      }
    },
    {
      "name": "style",
      "type": "React.CSSProperties | undefined",
      "declared_type": "React.CSSProperties",
      "required": false,
      "description": "",
      "source": {
        "path": "packages/design-system/src/components/forms/SearchField/SearchField.tsx",
        "line": 56
      }
    },
    {
      "name": "testId",
      "type": "string | undefined",
      "declared_type": "string",
      "required": false,
      "description": "Optional test selector. Clear action derives `${testId}-clear`.",
      "source": {
        "path": "packages/design-system/src/components/forms/SearchField/SearchField.tsx",
        "line": 58
      }
    }
  ],
  "prop_shapes": {},
  "api": {
    "method": "typescript-type-checker",
    "typescript_version": "5.9.3",
    "public_export": "SearchField",
    "public_path": "SearchField",
    "import_path": "@cloakedinc/design-system",
    "root_kind": "component",
    "entrypoints": [
      {
        "name": "SearchField",
        "signature": 1,
        "visibility": "public",
        "source": {
          "path": "packages/design-system/src/components/forms/SearchField/SearchField.tsx",
          "line": 64
        },
        "props_type": "SearchFieldProps",
        "props": [
          {
            "name": "value",
            "type": "string",
            "declared_type": "string",
            "required": true,
            "description": "Query text to display; a non-empty value is also what reveals the clear action.",
            "source": {
              "path": "packages/design-system/src/components/forms/SearchField/SearchField.tsx",
              "line": 24
            }
          },
          {
            "name": "onChange",
            "type": "((value: string) => void) | undefined",
            "declared_type": "(value: string) => void",
            "required": false,
            "description": "Called with the new text on each keystroke, and with `''` when the clear action fires.",
            "source": {
              "path": "packages/design-system/src/components/forms/SearchField/SearchField.tsx",
              "line": 26
            }
          },
          {
            "name": "onSearch",
            "type": "((value: string) => void) | undefined",
            "declared_type": "(value: string) => void",
            "required": false,
            "description": "Called when the search key is pressed.",
            "source": {
              "path": "packages/design-system/src/components/forms/SearchField/SearchField.tsx",
              "line": 28
            }
          },
          {
            "name": "enterBehavior",
            "type": "InputEnterBehavior | undefined",
            "declared_type": "InputEnterBehavior",
            "required": false,
            "description": "Return-key behavior. Defaults to search callback behavior.",
            "source": {
              "path": "packages/design-system/src/components/forms/SearchField/SearchField.tsx",
              "line": 30
            },
            "values": [
              "advance",
              "callback"
            ],
            "values_complete": true,
            "default": "'callback'",
            "default_kind": "source-expression"
          },
          {
            "name": "enterKeyHint",
            "type": "InputEnterKeyHint | undefined",
            "declared_type": "InputEnterKeyHint",
            "required": false,
            "description": "Native on-screen keyboard return key hint. Defaults to `search`.",
            "source": {
              "path": "packages/design-system/src/components/forms/SearchField/SearchField.tsx",
              "line": 32
            },
            "values": [
              "done",
              "enter",
              "go",
              "next",
              "previous",
              "search",
              "send"
            ],
            "values_complete": true,
            "default": "'search'",
            "default_kind": "source-expression"
          },
          {
            "name": "onClear",
            "type": "(() => void) | undefined",
            "declared_type": "() => void",
            "required": false,
            "description": "Called after the clear action resets the query.",
            "source": {
              "path": "packages/design-system/src/components/forms/SearchField/SearchField.tsx",
              "line": 34
            }
          },
          {
            "name": "placeholder",
            "type": "string | undefined",
            "declared_type": "string",
            "required": false,
            "description": "Placeholder text. Defaults to `Search`.",
            "source": {
              "path": "packages/design-system/src/components/forms/SearchField/SearchField.tsx",
              "line": 36
            },
            "default": "'Search'",
            "default_kind": "source-expression"
          },
          {
            "name": "size",
            "type": "InputSize",
            "declared_type": "SearchFieldSize",
            "required": true,
            "description": "Field height and type scale, shared with the underlying `Input`. Required — there is no default.",
            "source": {
              "path": "packages/design-system/src/components/forms/SearchField/SearchField.tsx",
              "line": 38
            },
            "values": [
              "md",
              "sm"
            ],
            "values_complete": true
          },
          {
            "name": "loading",
            "type": "boolean | undefined",
            "declared_type": "boolean",
            "required": false,
            "description": "Shows a spinner in the trailing slot. Typing and clearing stay available.",
            "source": {
              "path": "packages/design-system/src/components/forms/SearchField/SearchField.tsx",
              "line": 40
            },
            "values": [
              false,
              true
            ],
            "values_complete": true
          },
          {
            "name": "disabled",
            "type": "boolean | undefined",
            "declared_type": "boolean",
            "required": false,
            "description": "Blocks typing and the clear action.",
            "source": {
              "path": "packages/design-system/src/components/forms/SearchField/SearchField.tsx",
              "line": 42
            },
            "values": [
              false,
              true
            ],
            "values_complete": true
          },
          {
            "name": "surface",
            "type": "InputSurface | undefined",
            "declared_type": "SearchFieldSurface",
            "required": false,
            "description": "Container background treatment.",
            "source": {
              "path": "packages/design-system/src/components/forms/SearchField/SearchField.tsx",
              "line": 44
            },
            "values": [
              "default",
              "raised"
            ],
            "values_complete": true,
            "default": "'default'",
            "default_kind": "source-expression"
          },
          {
            "name": "autoCorrect",
            "type": "\"on\" | \"off\" | undefined",
            "declared_type": "'on' | 'off'",
            "required": false,
            "description": "Native autocorrect hint. Defaults to `off` so search fields stay quiet.",
            "source": {
              "path": "packages/design-system/src/components/forms/SearchField/SearchField.tsx",
              "line": 46
            },
            "values": [
              "off",
              "on"
            ],
            "values_complete": true,
            "default": "'off'",
            "default_kind": "source-expression"
          },
          {
            "name": "autoCapitalize",
            "type": "\"none\" | \"on\" | \"off\" | \"sentences\" | \"words\" | \"characters\" | undefined",
            "declared_type": "'off' | 'none' | 'on' | 'sentences' | 'words' | 'characters'",
            "required": false,
            "description": "Native autocapitalize hint. Defaults to `off` so search fields stay quiet.",
            "source": {
              "path": "packages/design-system/src/components/forms/SearchField/SearchField.tsx",
              "line": 48
            },
            "values": [
              "characters",
              "none",
              "off",
              "on",
              "sentences",
              "words"
            ],
            "values_complete": true,
            "default": "'off'",
            "default_kind": "source-expression"
          },
          {
            "name": "spellCheck",
            "type": "boolean | undefined",
            "declared_type": "boolean",
            "required": false,
            "description": "Native spellcheck hint. Defaults to `false` so search fields stay quiet.",
            "source": {
              "path": "packages/design-system/src/components/forms/SearchField/SearchField.tsx",
              "line": 50
            },
            "values": [
              false,
              true
            ],
            "values_complete": true,
            "default": "false",
            "default_kind": "source-expression"
          },
          {
            "name": "ariaLabel",
            "type": "string | undefined",
            "declared_type": "string",
            "required": false,
            "description": "Accessible name when no visible label is associated with the field.",
            "source": {
              "path": "packages/design-system/src/components/forms/SearchField/SearchField.tsx",
              "line": 52
            },
            "default": "'Search'",
            "default_kind": "source-expression"
          },
          {
            "name": "ariaControls",
            "type": "string | undefined",
            "declared_type": "string",
            "required": false,
            "description": "ID of the result list controlled by this search field.",
            "source": {
              "path": "packages/design-system/src/components/forms/SearchField/SearchField.tsx",
              "line": 54
            }
          },
          {
            "name": "className",
            "type": "string | undefined",
            "declared_type": "string",
            "required": false,
            "description": "",
            "source": {
              "path": "packages/design-system/src/components/forms/SearchField/SearchField.tsx",
              "line": 55
            }
          },
          {
            "name": "style",
            "type": "React.CSSProperties | undefined",
            "declared_type": "React.CSSProperties",
            "required": false,
            "description": "",
            "source": {
              "path": "packages/design-system/src/components/forms/SearchField/SearchField.tsx",
              "line": 56
            }
          },
          {
            "name": "testId",
            "type": "string | undefined",
            "declared_type": "string",
            "required": false,
            "description": "Optional test selector. Clear action derives `${testId}-clear`.",
            "source": {
              "path": "packages/design-system/src/components/forms/SearchField/SearchField.tsx",
              "line": 58
            }
          }
        ],
        "branches": [],
        "constraints": [],
        "extraction_status": "extracted"
      }
    ],
    "type_sources": [
      {
        "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/forms/SearchField/SearchField.tsx",
        "line": 16,
        "name": "SearchFieldSize",
        "code": "export type SearchFieldSize = InputSize;"
      },
      {
        "path": "packages/design-system/src/components/forms/SearchField/SearchField.tsx",
        "line": 22,
        "name": "SearchFieldProps",
        "code": "export interface SearchFieldProps {\n    /** Query text to display; a non-empty value is also what reveals the clear action. */\n    value: string;\n    /** Called with the new text on each keystroke, and with `''` when the clear action fires. */\n    onChange?: (value: string) => void;\n    /** Called when the search key is pressed. */\n    onSearch?: (value: string) => void;\n    /** Return-key behavior. Defaults to search callback behavior. */\n    enterBehavior?: InputEnterBehavior;\n    /** Native on-screen keyboard return key hint. Defaults to `search`. */\n    enterKeyHint?: InputEnterKeyHint;\n    /** Called after the clear action resets the query. */\n    onClear?: () => void;\n    /** Placeholder text. Defaults to `Search`. */\n    placeholder?: string;\n    /** Field height and type scale, shared with the underlying `Input`. Required — there is no default. */\n    size: SearchFieldSize;\n    /** Shows a spinner in the trailing slot. Typing and clearing stay available. */\n    loading?: boolean;\n    /** Blocks typing and the clear action. */\n    disabled?: boolean;\n    /** Container background treatment. */\n    surface?: SearchFieldSurface;\n    /** Native autocorrect hint. Defaults to `off` so search fields stay quiet. */\n    autoCorrect?: 'on' | 'off';\n    /** Native autocapitalize hint. Defaults to `off` so search fields stay quiet. */\n    autoCapitalize?: 'off' | 'none' | 'on' | 'sentences' | 'words' | 'characters';\n    /** Native spellcheck hint. Defaults to `false` so search fields stay quiet. */\n    spellCheck?: boolean;\n    /** Accessible name when no visible label is associated with the field. */\n    ariaLabel?: string;\n    /** ID of the result list controlled by this search field. */\n    ariaControls?: string;\n    className?: string;\n    style?: React.CSSProperties;\n    /** Optional test selector. Clear action derives `${testId}-clear`. */\n    testId?: string;\n}"
      },
      {
        "path": "packages/design-system/src/components/primitives/Input/Input.tsx",
        "line": 8,
        "name": "InputSize",
        "code": "export type InputSize = 'sm' | 'md';"
      },
      {
        "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';"
      }
    ],
    "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": "SearchField",
      "status": "preview",
      "version": "1.1.0",
      "summary": "A controlled search input with search icon, return-key callback, optional loading indicator, and value-dependent clear action."
    },
    "parts": [
      {
        "id": "control",
        "label": "Control",
        "description": "Input shell that owns size, surface, focus, disabled state, and slots."
      },
      {
        "id": "search-icon",
        "label": "Search icon",
        "description": "Persistent leading icon that communicates search intent."
      },
      {
        "id": "field",
        "label": "Search input",
        "description": "Native search field that owns the controlled query and return-key behavior."
      },
      {
        "id": "loading-indicator",
        "label": "Loading indicator",
        "description": "Optional labelled trailing spinner shown while results update."
      },
      {
        "id": "clear-action",
        "label": "Clear action",
        "description": "Value-dependent trailing button that resets the query."
      }
    ],
    "allowedDesignChoices": {
      "variants": {
        "base": {
          "label": "Base",
          "description": "One search treatment configured through independent size and surface axes."
        }
      },
      "sizes": {
        "sm": {
          "label": "Small"
        },
        "md": {
          "label": "Medium"
        }
      },
      "surfaces": {
        "default": {
          "label": "Default",
          "description": "Uses the semantic input container."
        },
        "raised": {
          "label": "Raised",
          "description": "Uses the raised surface when the field sits directly on the page canvas."
        }
      }
    },
    "variants": [
      {
        "id": "base",
        "label": "Base",
        "description": "Search-specific composition of Input with fixed leading and conditional trailing affordances.",
        "platforms": [
          "ios",
          "android",
          "web"
        ]
      }
    ],
    "sizes": [
      {
        "id": "sm",
        "label": "Small",
        "description": "40-unit compact search field."
      },
      {
        "id": "md",
        "label": "Medium",
        "description": "56-unit standard search field."
      }
    ],
    "measurements": [
      {
        "id": "small-height",
        "label": "Small control height",
        "kind": "exact",
        "token": "--cds-size-40",
        "value": 40,
        "unit": "px",
        "appliesTo": [
          "control",
          "sm"
        ]
      },
      {
        "id": "medium-height",
        "label": "Medium control height",
        "kind": "exact",
        "token": "--cds-size-56",
        "value": 56,
        "unit": "px",
        "appliesTo": [
          "control",
          "md"
        ]
      },
      {
        "id": "web-input-font-size",
        "label": "Web search input font size",
        "kind": "exact",
        "token": "--cds-type-body-size",
        "value": 16,
        "unit": "px",
        "appliesTo": [
          "field",
          "sm",
          "md"
        ],
        "notes": "Web keeps the compact field at the 16px anti-zoom floor."
      }
    ],
    "layout": {
      "alignment": "Search icon, native input, loading indicator, and clear action share the control center line.",
      "flow": "Persistent search icon, flexible input, optional loading indicator, then optional clear action.",
      "notes": [
        "Loading and clear may coexist; each occupies its own trailing slot.",
        "Use Autocomplete when the search field must present selectable results."
      ]
    },
    "typographyAndColor": {
      "typography": [
        {
          "label": "Search query",
          "description": "Use body text on web to prevent focused-input viewport zoom.",
          "token": "--cds-type-body-size"
        }
      ],
      "colors": [
        {
          "label": "Default surface",
          "description": "Use the semantic input container.",
          "token": "--cds-input-container"
        },
        {
          "label": "Raised surface",
          "description": "Use the raised semantic surface.",
          "token": "--cds-bg-surface"
        },
        {
          "label": "Query",
          "description": "Use primary text emphasis.",
          "token": "--cds-text-primary"
        },
        {
          "label": "Placeholder and icons",
          "description": "Use secondary text emphasis.",
          "token": "--cds-text-secondary"
        }
      ]
    },
    "states": [
      {
        "id": "empty",
        "label": "Empty",
        "description": "Shows the placeholder and no clear action."
      },
      {
        "id": "filled",
        "label": "Filled",
        "description": "Shows the controlled query and the clear action."
      },
      {
        "id": "loading",
        "label": "Loading",
        "description": "Shows a labelled trailing spinner while preserving query editing."
      },
      {
        "id": "focused",
        "label": "Focused",
        "description": "Accepts search-key submission; the inherited Input control has no focus ring, since the design system targets a touch surface."
      },
      {
        "id": "disabled",
        "label": "Disabled",
        "description": "Blocks editing and clearing and dims the entire control."
      }
    ],
    "behavior": [
      {
        "label": "Controlled editing",
        "description": "Request query changes on each edit while the parent owns the rendered value."
      },
      {
        "label": "Search return key",
        "description": "Default to callback behavior and a search return-key hint, emitting the current query."
      },
      {
        "label": "Clear",
        "description": "Request an empty query before invoking the optional clear callback."
      },
      {
        "label": "Quiet typing defaults",
        "description": "Default autocorrect, autocapitalization, and spellcheck off for search terms."
      }
    ],
    "accessibility": [
      {
        "label": "Search role and name",
        "description": "Expose native searchbox semantics and require an accessible name."
      },
      {
        "label": "Controlled results",
        "description": "Associate the input with a result container through controls when one exists."
      },
      {
        "label": "Clear action",
        "description": "Name the clear button independently and give it a derived stable test identifier."
      }
    ],
    "contentAdaptation": [
      {
        "label": "Placeholder",
        "description": "Describe what can be searched rather than using generic instructional copy."
      },
      {
        "label": "Long queries",
        "description": "Let the native single-line input scroll horizontally without displacing fixed affordances."
      }
    ],
    "motionHaptics": {
      "motion": [
        {
          "label": "Trailing affordances",
          "description": "Add or remove loading and clear affordances without changing control height."
        }
      ],
      "haptics": [
        {
          "label": "No intrinsic feedback",
          "description": "Typing, search submission, and clearing do not request design-system haptics."
        }
      ]
    },
    "platformDifferences": [
      {
        "platforms": [
          "web"
        ],
        "description": "Small search fields retain a 16px input font instead of the 14px body-small token value.",
        "rationale": "WKWebView zooms focused inputs below 16px; the floor prevents a viewport jump while preserving the compact 40px shell."
      }
    ]
  },
  "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-size-40",
      "light": "40px",
      "dark": "40px"
    },
    {
      "name": "--cds-size-56",
      "light": "56px",
      "dark": "56px"
    },
    {
      "name": "--cds-type-body-size",
      "light": "1rem",
      "dark": "1rem"
    },
    {
      "name": "--cds-input-container",
      "light": "#f3f1ed",
      "dark": "#232321"
    },
    {
      "name": "--cds-bg-surface",
      "light": "#ffffff",
      "dark": "#1b1b18"
    },
    {
      "name": "--cds-text-primary",
      "light": "#141410",
      "dark": "#f3f1ed"
    },
    {
      "name": "--cds-text-secondary",
      "light": "#646260",
      "dark": "#ffffff99"
    }
  ],
  "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-searchfield--playground&viewMode=story) | export: Playground | source: packages/design-system/src/components/forms/SearchField/SearchField.stories.tsx

- [Sizes](/storybook/iframe.html?id=cloaked-design-system-forms-searchfield--sizes&viewMode=story) | export: Sizes | source: packages/design-system/src/components/forms/SearchField/SearchField.stories.tsx

- [Raised On Canvas](/storybook/iframe.html?id=cloaked-design-system-forms-searchfield--raised-on-canvas&viewMode=story) | export: RaisedOnCanvas | source: packages/design-system/src/components/forms/SearchField/SearchField.stories.tsx

- [State Matrix](/storybook/iframe.html?id=cloaked-design-system-forms-searchfield--state-matrix&viewMode=story) | export: StateMatrix | source: packages/design-system/src/components/forms/SearchField/SearchField.stories.tsx

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

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