diff --git a/design-system/apps/design-lab/src/i18n/messages.ts b/design-system/apps/design-lab/src/i18n/messages.ts
index e8a7318e65..0537a227e5 100644
--- a/design-system/apps/design-lab/src/i18n/messages.ts
+++ b/design-system/apps/design-lab/src/i18n/messages.ts
@@ -528,6 +528,9 @@ export const enUSMessages = {
   "detail.option.selected-item": "Selected item",
   "detail.option.focus-visible": "Focus visible",
   "detail.option.disabled": "Disabled",
+  "detail.option.filled": "Filled",
+  "detail.option.read-only": "Read only",
+  "components.preview.searchClear": "Clear search",
   "detail.option.display": "Display",
   "detail.option.completed": "Completed",
   "detail.option.expanded": "Expanded",
@@ -1268,6 +1271,9 @@ export const zhCNMessages = {
   "detail.option.selected-item": "选中项目",
   "detail.option.focus-visible": "焦点可见",
   "detail.option.disabled": "禁用",
+  "detail.option.filled": "已输入",
+  "detail.option.read-only": "只读",
+  "components.preview.searchClear": "清除搜索",
   "detail.option.display": "展示",
   "detail.option.completed": "已完成",
   "detail.option.expanded": "展开",
@@ -1947,6 +1953,9 @@ export const zhTWMessages = {
   "detail.option.selected-item": "選取項目",
   "detail.option.focus-visible": "焦點可見",
   "detail.option.disabled": "停用",
+  "detail.option.filled": "已輸入",
+  "detail.option.read-only": "唯讀",
+  "components.preview.searchClear": "清除搜尋",
   "detail.option.display": "展示",
   "detail.option.completed": "已完成",
   "detail.option.expanded": "展開",
diff --git a/design-system/apps/design-lab/src/pages/ComponentDetailPage.tsx b/design-system/apps/design-lab/src/pages/ComponentDetailPage.tsx
index 5c7012c66a..73075f9fd7 100644
--- a/design-system/apps/design-lab/src/pages/ComponentDetailPage.tsx
+++ b/design-system/apps/design-lab/src/pages/ComponentDetailPage.tsx
@@ -178,6 +178,8 @@ const optionLabelKeys: Readonly<Record<string, MessageKey>> = {
   default: "detail.option.default",
   replacing: "detail.option.replacing",
   disabled: "detail.option.disabled",
+  filled: "detail.option.filled",
+  "read-only": "detail.option.read-only",
   display: "detail.option.display",
   error: "detail.option.error",
   expanded: "detail.option.expanded",
@@ -298,6 +300,27 @@ function NumberInputPreview({ state }: { state: string }) {
   );
 }
 
+function SearchFieldStatePreview({ state }: { state: string }) {
+  const { t } = useI18n();
+  const [value, setValue] = useState(state === "default" ? "" : "OpenBitFun");
+  return (
+    <SearchField
+      aria-label={t("components.preview.searchLabel")}
+      className={state === "hover" ? "lab-force-hover" : state === "focus-visible" ? "lab-force-focus" : undefined}
+      clearLabel={t("components.preview.searchClear")}
+      disabled={state === "disabled"}
+      invalid={state === "invalid"}
+      leadingIcon={<Icon name="search" />}
+      onClear={() => setValue("")}
+      onValueChange={setValue}
+      placeholder={t("components.preview.searchPlaceholder")}
+      readOnly={state === "read-only"}
+      shortcut={<KeyHint icon={<Icon name="command-mac" />}>K</KeyHint>}
+      value={value}
+    />
+  );
+}
+
 export function ComponentDetailPage({
   colorScheme,
   component,
@@ -399,7 +422,7 @@ export function ComponentDetailPage({
         return ["raised", "subtle", "media"] as const;
       case "Input":
       case "SearchField":
-        return ["default", "hover", "focus-visible", "invalid", "disabled"] as const;
+        return ["default", "filled", "hover", "focus-visible", "read-only", "invalid", "disabled"] as const;
       case "Select":
         return ["default", "hover", "focus-visible", "open", "invalid", "disabled"] as const;
       case "Field":
@@ -541,7 +564,9 @@ export function ComponentDetailPage({
         ? " disabled"
         : previewState === "invalid"
           ? " invalid"
-          : "";
+          : previewState === "read-only"
+            ? ' readOnly defaultValue="OpenBitFun"'
+            : previewState === "default" ? "" : ' defaultValue="OpenBitFun"';
       return `import { Icon, Input } from "@openbitfun/ui";\n\n<Input\n  aria-label="${t("components.preview.inputLabel")}"\n  placeholder="${t("components.preview.inputPlaceholder")}"\n  trailing={<Icon name="eye" />}${stateProps}\n/>`;
     }
     if (component.name === "KeyHint") {
@@ -570,12 +595,8 @@ export function ComponentDetailPage({
       return `import { Icon, IconButton, PageHeader } from "@openbitfun/ui";\n\n<PageHeader\n  action={<IconButton aria-label="${t("components.preview.close")}" icon={<Icon name="xmark" />} />}\n  align="${pageHeaderAlign}"\n  description="${t("components.preview.appearanceDescription")}"\n  leading={<Icon name="gear" />}\n  level={2}${requiredProp}\n  size="${pageHeaderSize}"\n  title="${t("components.preview.appearance")}"\n/>`;
     }
     if (component.name === "SearchField") {
-      const stateProps = previewState === "disabled"
-        ? " disabled"
-        : previewState === "invalid"
-          ? " invalid"
-          : "";
-      return `import { Icon, KeyHint, SearchField } from "@openbitfun/ui";\n\n<SearchField\n  aria-label="${t("components.preview.searchLabel")}"\n  leadingIcon={<Icon name="search" />}\n  placeholder="${t("components.preview.searchPlaceholder")}"\n  shortcut={<KeyHint icon={<Icon name="command-mac" />}>K</KeyHint>}${stateProps}\n/>`;
+      const searchStateProps = previewState === "disabled" ? " disabled" : previewState === "invalid" ? " invalid" : previewState === "read-only" ? " readOnly" : "";
+      return `import { useState } from "react";\nimport { Icon, KeyHint, SearchField } from "@openbitfun/ui";\n\nfunction Example() {\n  const [query, setQuery] = useState(${JSON.stringify(previewState === "default" ? "" : "OpenBitFun")});\n  return (\n    <SearchField\n      clearLabel="${t("components.preview.searchClear")}"\n      onClear={() => setQuery("")}\n      onValueChange={setQuery}\n      value={query}\n      aria-label="${t("components.preview.searchLabel")}"\n      leadingIcon={<Icon name="search" />}\n      placeholder="${t("components.preview.searchPlaceholder")}"\n      shortcut={<KeyHint icon={<Icon name="command-mac" />}>K</KeyHint>}${searchStateProps}\n    />\n  );\n}`;
     }
     if (component.name === "Combobox") {
       return `import { Combobox } from "@openbitfun/ui";\n\n<Combobox\n  aria-label="Mode"\n  onValueChange={setMode}\n  options={[\n    { label: "Ask", value: "ask" },\n    { label: "Plan", value: "plan" },\n    { disabled: true, label: "Agent", value: "agent" },\n  ]}\n  value={mode}\n/>`;
@@ -1327,10 +1348,13 @@ export function ComponentDetailPage({
         <Input
           aria-label={t("components.preview.inputLabel")}
           className={previewClassName}
+          defaultValue={state === "default" ? undefined : "OpenBitFun"}
+          key={state}
           disabled={state === "disabled"}
           invalid={state === "invalid"}
           placeholder={t("components.preview.inputPlaceholder")}
-          trailing={<Icon name="eye" size="lg" aria-hidden="true" />}
+          readOnly={state === "read-only"}
+          trailing={<Icon name="eye" />}
         />
       );
     }
@@ -1775,22 +1799,7 @@ export function ComponentDetailPage({
     }
 
     if (component.name === "SearchField") {
-      const previewClassName = state === "hover"
-        ? "lab-force-hover"
-        : state === "focus-visible"
-          ? "lab-force-focus"
-          : undefined;
-      return (
-        <SearchField
-          aria-label={t("components.preview.searchLabel")}
-          className={previewClassName}
-          disabled={state === "disabled"}
-          invalid={state === "invalid"}
-          leadingIcon={<Icon name="search" size="lg" aria-hidden="true" />}
-          placeholder={t("components.preview.searchPlaceholder")}
-          shortcut={<KeyHint icon={<Icon name="command-mac" size="lg" aria-hidden="true" />}>K</KeyHint>}
-        />
-      );
+      return <SearchFieldStatePreview key={state} state={state} />;
     }
 
     if (component.name === "NavigationPanel") {
diff --git a/design-system/apps/design-lab/src/styles.css b/design-system/apps/design-lab/src/styles.css
index b568ea3728..249290617c 100644
--- a/design-system/apps/design-lab/src/styles.css
+++ b/design-system/apps/design-lab/src/styles.css
@@ -1096,11 +1096,6 @@ body,
   outline-offset: var(--openbitfun-focus-offset);
 }
 
-input.lab-force-focus {
-  border-color: var(--openbitfun-color-field-border-focus) !important;
-  box-shadow: 0 0 0 var(--openbitfun-focus-width) var(--openbitfun-color-focus-ring) !important;
-}
-
 [data-openbitfun-component="input"].lab-force-hover,
 [data-openbitfun-component="search-field"].lab-force-hover [data-openbitfun-component="input"] {
   border-color: var(--openbitfun-color-field-border-hover);
@@ -1109,8 +1104,8 @@ input.lab-force-focus {
 
 [data-openbitfun-component="input"].lab-force-focus,
 [data-openbitfun-component="search-field"].lab-force-focus [data-openbitfun-component="input"] {
-  border-color: var(--openbitfun-color-field-border-focus);
-  box-shadow: 0 0 0 var(--openbitfun-focus-width) var(--openbitfun-color-focus-ring);
+  border-color: var(--openbitfun-color-field-border-active);
+  box-shadow: none;
 }
 
 .component-code-panel {
diff --git a/design-system/apps/design-lab/vite/component-detail-contract.test.mjs b/design-system/apps/design-lab/vite/component-detail-contract.test.mjs
index ccb3768dc4..476ec6efe7 100644
--- a/design-system/apps/design-lab/vite/component-detail-contract.test.mjs
+++ b/design-system/apps/design-lab/vite/component-detail-contract.test.mjs
@@ -419,14 +419,24 @@ test("ConfirmDialog preview exposes semantic, destructive, preview, and pending
 test("Input, KeyHint, and SearchField previews expose composable slot and state contracts", async () => {
   const source = await readFile(detailSource, "utf8");
 
-  assert.match(source, /case "Input":\s*case "SearchField":\s*return \["default", "hover", "focus-visible", "invalid", "disabled"\] as const/);
+  assert.match(source, /case "Input":\s*case "SearchField":\s*return \["default", "filled", "hover", "focus-visible", "read-only", "invalid", "disabled"\] as const/);
   assert.match(source, /case "Select":\s*return \["default", "hover", "focus-visible", "open", "invalid", "disabled"\] as const/);
   assert.match(source, /component\.name === "Input"/);
   assert.match(source, /component\.name === "KeyHint"/);
   assert.match(source, /component\.name === "SearchField"/);
-  assert.match(source, /trailing=\{<Icon name="eye" size="lg" aria-hidden="true" \/>\}/);
-  assert.match(source, /leadingIcon=\{<Icon name="search" size="lg" aria-hidden="true" \/>\}/);
-  assert.match(source, /shortcut=\{<KeyHint icon=\{<Icon name="command-mac" size="lg" aria-hidden="true" \/>\}>K<\/KeyHint>\}/);
+  assert.match(source, /trailing=\{<Icon name="eye" \/>\}/);
+  assert.match(source, /leadingIcon=\{<Icon name="search" \/>\}/);
+  assert.match(source, /shortcut=\{<KeyHint icon=\{<Icon name="command-mac" \/>\}>K<\/KeyHint>\}/);
+  assert.match(source, /onClear=\{\(\) => setValue\(""\)\}/);
+  assert.match(source, /readOnly=\{state === "read-only"\}/);
+
+  const styles = await readFile(stylesSource, "utf8");
+  const fieldFocus = styles.match(/\[data-openbitfun-component="input"\]\.lab-force-focus,[^{]+\{([^}]+)\}/)?.[1];
+  assert.ok(fieldFocus, "Input and SearchField must share their preview focus treatment");
+  assert.match(fieldFocus, /border-color: var\(--openbitfun-color-field-border-active\)/);
+  assert.match(fieldFocus, /box-shadow: none/);
+  assert.doesNotMatch(fieldFocus, /border-width:|outline:|--openbitfun-focus-width/);
+  assert.doesNotMatch(styles, /input\.lab-force-focus\s*\{/);
 });
 
 test("ScrollArea preview exposes direction and native scrollbar visibility contracts", async () => {
diff --git a/design-system/packages/theme-openbitfun/README.md b/design-system/packages/theme-openbitfun/README.md
index 549e73f356..29f6a9d2a6 100644
--- a/design-system/packages/theme-openbitfun/README.md
+++ b/design-system/packages/theme-openbitfun/README.md
@@ -28,6 +28,24 @@ The same data is available as `@openbitfun/theme-openbitfun/reference-colors.jso
 
 ## Surface and state roles
 
+`color.field.*` owns shared field surfaces and state borders. Light uses neutral
+8% borders, with 20% hover and active Input/SearchField borders. The dedicated
+`color.field.borderActive` owns the editing border because Input's design differs
+from the stronger focus treatment used by other controls. These text
+fields use one unchanged border for both pointer and keyboard focus; native
+`:focus-visible` must not substitute the stronger generic focus palette or add
+a second ring. Dark and high-contrast modes retain their own focus color, and forced
+colors use Highlight. `color.field.borderFocus` retains its 3:1 contract for
+other controls that consume that stronger focus treatment.
+`color.field.placeholder` separates
+40% empty hints and decorative adornments from general secondary prose; dark
+and high-contrast modes retain their readable muted content colors. The default
+light Web UI consumes these published values in root and chrome scopes. Named
+presets keep their own palette, and imported packages that only supply
+`color.content.muted` retain that field hint color unless explicitly overridden.
+Old packages that supply `color.field.borderFocus` retain that editing border
+unless they explicitly provide `color.field.borderActive`.
+
 `component.button.*` owns Button's state palette. Its light fill stays at black
 8% while the shared neutral actions retain their 5/8/10% feedback; its primary
 background uses black 80/60/90% and disabled content 20%. Outline and text variants
diff --git a/design-system/packages/theme-openbitfun/src/dark.tokens.json b/design-system/packages/theme-openbitfun/src/dark.tokens.json
index 6e395cebee..153120ddd6 100644
--- a/design-system/packages/theme-openbitfun/src/dark.tokens.json
+++ b/design-system/packages/theme-openbitfun/src/dark.tokens.json
@@ -175,6 +175,8 @@
       }
     },
     "field": {
+      "borderActive": { "$type": "color", "$value": "{color.field.borderFocus}" },
+      "placeholder": { "$type": "color", "$value": "{color.content.muted}" },
       "background": { "$type": "color", "$value": "{ref.color.neutral.900}" },
       "backgroundHover": { "$type": "color", "$value": "rgba(255, 255, 255, 0.06)" },
       "border": { "$type": "color", "$value": "rgba(255, 255, 255, 0.18)" },
diff --git a/design-system/packages/theme-openbitfun/src/high-contrast-dark.tokens.json b/design-system/packages/theme-openbitfun/src/high-contrast-dark.tokens.json
index fe7434f4e5..5561e02ac7 100644
--- a/design-system/packages/theme-openbitfun/src/high-contrast-dark.tokens.json
+++ b/design-system/packages/theme-openbitfun/src/high-contrast-dark.tokens.json
@@ -51,6 +51,8 @@
       }
     },
     "field": {
+      "borderActive": { "$type": "color", "$value": "{color.field.borderFocus}" },
+      "placeholder": { "$type": "color", "$value": "{color.content.muted}" },
       "border": { "$type": "color", "$value": "{ref.color.gray.250}" },
       "borderHover": { "$type": "color", "$value": "{ref.color.gray.0}" },
       "borderFocus": { "$type": "color", "$value": "{ref.color.amber.400}" }
diff --git a/design-system/packages/theme-openbitfun/src/high-contrast-light.tokens.json b/design-system/packages/theme-openbitfun/src/high-contrast-light.tokens.json
index a522d1e2b8..cc823429e7 100644
--- a/design-system/packages/theme-openbitfun/src/high-contrast-light.tokens.json
+++ b/design-system/packages/theme-openbitfun/src/high-contrast-light.tokens.json
@@ -51,6 +51,8 @@
       }
     },
     "field": {
+      "borderActive": { "$type": "color", "$value": "{color.field.borderFocus}" },
+      "placeholder": { "$type": "color", "$value": "{color.content.muted}" },
       "border": { "$type": "color", "$value": "{ref.color.gray.650}" },
       "borderHover": { "$type": "color", "$value": "{ref.color.gray.1000}" },
       "borderFocus": { "$type": "color", "$value": "{ref.color.blue.700}" }
diff --git a/design-system/packages/theme-openbitfun/src/light.tokens.json b/design-system/packages/theme-openbitfun/src/light.tokens.json
index 7f997a7fbc..62f525e3fc 100644
--- a/design-system/packages/theme-openbitfun/src/light.tokens.json
+++ b/design-system/packages/theme-openbitfun/src/light.tokens.json
@@ -175,10 +175,12 @@
       }
     },
     "field": {
+      "borderActive": { "$description": "Input and SearchField editing border, distinct from the stronger generic focus indicator used by other controls.", "$type": "color", "$value": "{color.field.borderHover}" },
+      "placeholder": { "$description": "Empty field hints and decorative adornments; distinct from general secondary prose.", "$type": "color", "$value": "rgba(0, 0, 0, 0.40)" },
       "background": { "$type": "color", "$value": "{ref.color.neutral.0}" },
       "backgroundHover": { "$type": "color", "$value": "{color.field.background}" },
-      "border": { "$type": "color", "$value": "rgba(16, 26, 39, 0.15)" },
-      "borderHover": { "$type": "color", "$value": "rgba(16, 26, 39, 0.24)" },
+      "border": { "$type": "color", "$value": "rgba(0, 0, 0, 0.08)" },
+      "borderHover": { "$type": "color", "$value": "rgba(0, 0, 0, 0.20)" },
       "borderFocus": { "$type": "color", "$value": "{ref.color.neutral.550}" }
     },
     "control": {
diff --git a/design-system/packages/ui/README.md b/design-system/packages/ui/README.md
index 24e6ed19e4..5885a05f3b 100644
--- a/design-system/packages/ui/README.md
+++ b/design-system/packages/ui/README.md
@@ -280,6 +280,10 @@ The Web UI's legacy Select implementation is retired. Like retired Button and
 Switch overrides, legacy `components.select` Appearance rules are ignored at
 the existing read-only migration boundary; original packages are not rewritten.
 Selection visuals now come from the public field/menu semantic tokens.
+SearchField sizes its decorative wrapper through Input's icon slot, so default
+catalog icons and native SVGs occupy the same region. Shortcut hints and clear
+actions can coexist; disabled and read-only fields disable the clear action.
+
 Choose `size` explicitly when composing form rows: selectors default to `md`,
 while `Input` defaults to `sm`. The shared `control.height.sm/md/lg` tokens and
 active density own the actual heights; consumers must not replace them with
diff --git a/design-system/packages/ui/src/components/Input/Input.meta.ts b/design-system/packages/ui/src/components/Input/Input.meta.ts
index a0fbf5b407..8462fa2743 100644
--- a/design-system/packages/ui/src/components/Input/Input.meta.ts
+++ b/design-system/packages/ui/src/components/Input/Input.meta.ts
@@ -12,20 +12,23 @@ export const inputMeta = {
     { name: "leading", type: "ReactNode" },
     { name: "trailing", type: "ReactNode" },
     { defaultValue: "sm", name: "size", type: "sm | md | lg" },
+    { defaultValue: "false", name: "readOnly", type: "boolean" },
     { defaultValue: "false", name: "invalid", type: "boolean" },
     { defaultValue: "false", name: "disabled", type: "boolean" },
     { name: "onValueChange", type: "(value: string) => void" },
   ],
-  states: ["default", "hover", "focus-visible", "invalid", "disabled"],
+  states: ["default", "filled", "hover", "focus-visible", "read-only", "invalid", "disabled"],
   tokens: [
     "color.content.primary",
     "color.content.muted",
     "color.content.disabled",
     "color.field.background",
+    "color.field.placeholder",
+    "opacity.iconArtwork",
     "color.field.backgroundHover",
     "color.field.border",
     "color.field.borderHover",
-    "color.field.borderFocus",
+    "color.field.borderActive",
     "color.accent.default",
     "color.status.danger.border",
     "control.height.sm",
diff --git a/design-system/packages/ui/src/components/Input/Input.module.css b/design-system/packages/ui/src/components/Input/Input.module.css
index 768094b06c..bd6b1c02b1 100644
--- a/design-system/packages/ui/src/components/Input/Input.module.css
+++ b/design-system/packages/ui/src/components/Input/Input.module.css
@@ -29,7 +29,7 @@
   }
 
   .field:focus-within {
-    border-color: var(--openbitfun-color-field-border-focus);
+    border-color: var(--openbitfun-color-field-border-active);
     box-shadow: none;
   }
 
@@ -47,6 +47,10 @@
     --_field-icon-size: 16px;
   }
 
+  .field[data-disabled="true"] :is(.leading, .trailing) {
+    color: var(--openbitfun-color-content-disabled);
+  }
+
   .field[data-size="lg"] {
     --_field-height: var(--openbitfun-control-height-lg);
     --_field-icon-size: 20px;
@@ -71,7 +75,7 @@
   }
 
   .input::placeholder {
-    color: var(--openbitfun-color-content-muted);
+    color: var(--openbitfun-color-field-placeholder);
     opacity: 1;
   }
 
@@ -85,16 +89,18 @@
 
   .leading,
   .trailing {
+    --openbitfun-opacity-icon-artwork: 1;
     display: inline-flex;
     flex: 0 0 auto;
     align-items: center;
     justify-content: center;
-    color: var(--openbitfun-color-content-muted);
+    color: var(--openbitfun-color-field-placeholder);
   }
 
   .leading > :where(svg, img),
   .trailing > :where(svg, img),
   .leading > [data-openbitfun-component="icon"],
+  .leading > [data-openbitfun-part="icon"],
   .trailing > [data-openbitfun-component="icon"] {
     display: block;
     inline-size: var(--_field-icon-size);
diff --git a/design-system/packages/ui/src/components/SearchField/SearchField.meta.ts b/design-system/packages/ui/src/components/SearchField/SearchField.meta.ts
index bc1c280ada..d923f05a60 100644
--- a/design-system/packages/ui/src/components/SearchField/SearchField.meta.ts
+++ b/design-system/packages/ui/src/components/SearchField/SearchField.meta.ts
@@ -16,13 +16,14 @@ export const searchFieldMeta = {
     { name: "footer", type: "ReactNode (panel only)" },
     { name: "clearLabel", type: "string" },
     { defaultValue: "sm", name: "size", type: "sm | md | lg" },
+    { defaultValue: "false", name: "readOnly", type: "boolean" },
     { defaultValue: "false", name: "invalid", type: "boolean" },
     { defaultValue: "false", name: "disabled", type: "boolean" },
     { name: "onValueChange", type: "(value: string) => void" },
     { name: "onClear", type: "MouseEventHandler<HTMLButtonElement>" },
     { name: "onSearch", type: "(value: string) => void" },
   ],
-  states: ["default", "hover", "focus-visible", "invalid", "disabled"],
+  states: ["default", "filled", "hover", "focus-visible", "read-only", "invalid", "disabled"],
   tokens: [
     "color.content.primary",
     "color.content.muted",
@@ -31,9 +32,11 @@ export const searchFieldMeta = {
     "color.border.subtle",
     "color.border.default",
     "color.field.background",
+    "color.field.placeholder",
     "color.field.backgroundHover",
     "color.field.border",
     "color.field.borderHover",
+    "color.field.borderActive",
     "color.field.borderFocus",
     "color.status.danger.border",
     "control.height.sm",
diff --git a/design-system/packages/ui/src/components/SearchField/SearchField.module.css b/design-system/packages/ui/src/components/SearchField/SearchField.module.css
index ba7b939939..368eac4072 100644
--- a/design-system/packages/ui/src/components/SearchField/SearchField.module.css
+++ b/design-system/packages/ui/src/components/SearchField/SearchField.module.css
@@ -18,15 +18,24 @@
     border-color: var(--openbitfun-color-border-default);
   }
 
+  .field [data-openbitfun-part="trailing"] {
+    gap: var(--openbitfun-space-1);
+  }
+
   .root .clear {
     /* The clear action is already composited inside Input's field surface. */
     --_icon-button-background: transparent;
     --_icon-button-background-hover: transparent;
     --_icon-button-background-active: transparent;
+    --_icon-button-content: var(--openbitfun-color-field-placeholder);
 
     background: transparent;
   }
 
+  .root .clear:disabled {
+    --_icon-button-content: var(--openbitfun-color-content-disabled);
+  }
+
   .root[data-variant="embedded"] .field,
   .root[data-variant="embedded"] .field:is(:hover, :focus-within, [data-invalid="true"]) {
     block-size: 100%;
@@ -135,6 +144,13 @@
     justify-content: center;
   }
 
+  .icon > :where(svg, img),
+  .icon > [data-openbitfun-component="icon"] {
+    display: block;
+    inline-size: 100%;
+    block-size: 100%;
+  }
+
   .shortcut {
     display: inline-flex;
     align-items: center;
diff --git a/design-system/packages/ui/src/components/SearchField/SearchField.tsx b/design-system/packages/ui/src/components/SearchField/SearchField.tsx
index e62ca9dd74..6179d3ff16 100644
--- a/design-system/packages/ui/src/components/SearchField/SearchField.tsx
+++ b/design-system/packages/ui/src/components/SearchField/SearchField.tsx
@@ -28,11 +28,13 @@ export interface SearchFieldProps
 export const SearchField = forwardRef<HTMLInputElement, SearchFieldProps>(function SearchField({
   className,
   clearLabel,
+  disabled,
   footer,
   leadingIcon,
   onClear,
   onKeyDown,
   onSearch,
+  readOnly,
   shortcut,
   trailing,
   variant = "default",
@@ -49,8 +51,11 @@ export const SearchField = forwardRef<HTMLInputElement, SearchFieldProps>(functi
         <IconButton
           aria-label={clearLabel}
           className={styles.clear}
+          disabled={disabled || readOnly}
           icon={<Icon name="xmark" />}
-          onClick={onClear}
+          onClick={(event) => {
+            if (!disabled && !readOnly) onClear(event);
+          }}
           onMouseDown={(event) => event.preventDefault()}
           shape="circle"
           size="xs"
@@ -58,15 +63,16 @@ export const SearchField = forwardRef<HTMLInputElement, SearchFieldProps>(functi
         />
       )
     : undefined;
-  const endAdornment = clearAction ?? (shortcut === undefined ? undefined : (
+  const shortcutHint = shortcut === undefined ? undefined : (
     <span aria-hidden="true" className={styles.shortcut}>{shortcut}</span>
-  ));
-  const trailingContent = trailing === undefined && endAdornment === undefined
+  );
+  const trailingContent = trailing === undefined && shortcutHint === undefined && clearAction === undefined
     ? undefined
     : (
         <>
           {trailing}
-          {endAdornment}
+          {shortcutHint}
+          {clearAction}
         </>
       );
 
@@ -75,11 +81,13 @@ export const SearchField = forwardRef<HTMLInputElement, SearchFieldProps>(functi
       <Input
         {...props}
         className={styles.field}
+        disabled={disabled}
         leading={leadingIcon === undefined ? undefined : (
-          <span aria-hidden="true" className={styles.icon}>{leadingIcon}</span>
+          <span aria-hidden="true" className={styles.icon} data-openbitfun-part="icon">{leadingIcon}</span>
         )}
         onKeyDown={handleKeyDown}
         ref={ref}
+        readOnly={readOnly}
         trailing={trailingContent}
         type="search"
       />
diff --git a/design-system/packages/ui/src/components/Select/Select.meta.ts b/design-system/packages/ui/src/components/Select/Select.meta.ts
index 70e6668f9a..c7fb2c2299 100644
--- a/design-system/packages/ui/src/components/Select/Select.meta.ts
+++ b/design-system/packages/ui/src/components/Select/Select.meta.ts
@@ -21,6 +21,8 @@ export const selectMeta = {
   states: ["default", "hover", "focus-visible", "open", "invalid", "disabled"],
   tokens: [
     "color.field.background",
+    "color.field.placeholder",
+    "opacity.iconArtwork",
     "color.field.backgroundHover",
     "color.field.border",
     "color.field.borderHover",
diff --git a/design-system/packages/ui/src/components/Select/Select.module.css b/design-system/packages/ui/src/components/Select/Select.module.css
index 83d75ef508..9d5bd3b8e8 100644
--- a/design-system/packages/ui/src/components/Select/Select.module.css
+++ b/design-system/packages/ui/src/components/Select/Select.module.css
@@ -119,13 +119,14 @@
 
   .leading,
   .indicator {
+    --openbitfun-opacity-icon-artwork: 1;
     display: inline-flex;
     flex: 0 0 var(--openbitfun-control-select-indicator-size);
     align-items: center;
     justify-content: center;
     inline-size: var(--openbitfun-control-select-indicator-size);
     block-size: var(--openbitfun-control-select-indicator-size);
-    color: var(--openbitfun-color-content-muted);
+    color: var(--openbitfun-color-field-placeholder);
     pointer-events: none;
   }
 
@@ -147,7 +148,7 @@
   }
 
   .placeholder {
-    color: var(--openbitfun-color-content-muted);
+    color: var(--openbitfun-color-field-placeholder);
   }
 
   .indicator {
diff --git a/design-system/packages/ui/tests/icon-slots.test.mjs b/design-system/packages/ui/tests/icon-slots.test.mjs
index b178652e81..5633be4d2e 100644
--- a/design-system/packages/ui/tests/icon-slots.test.mjs
+++ b/design-system/packages/ui/tests/icon-slots.test.mjs
@@ -18,6 +18,7 @@ const slots = [
   ["KeyHint", "icon", "inline-size", "1em"],
   ["Input", "leading", "inline-size", "var(--_field-icon-size)"],
   ["Input", "trailing", "inline-size", "var(--_field-icon-size)"],
+  ["SearchField", "icon", "inline-size", "100%"],
   ["Select", "leading", "inline-size", "100%"],
   ["Select", "indicator", "inline-size", "100%"],
   ["StatusPill", "leading", "inline-size", "100%"],
diff --git a/design-system/packages/ui/tests/input.test.mjs b/design-system/packages/ui/tests/input.test.mjs
index 58c3c9b832..c189571e29 100644
--- a/design-system/packages/ui/tests/input.test.mjs
+++ b/design-system/packages/ui/tests/input.test.mjs
@@ -54,7 +54,7 @@ test("Input styles consume semantic field and status tokens", async () => {
   const styles = await readFile(new URL("../dist/styles.css", import.meta.url), "utf8");
 
   assert.match(styles, /--openbitfun-color-field-background/);
-  assert.match(styles, /--openbitfun-color-field-border-focus/);
+  assert.match(styles, /--openbitfun-color-field-border-active/);
   assert.match(styles, /--openbitfun-color-content-muted/);
   assert.match(styles, /--openbitfun-color-status-danger-border/);
   assert.match(styles, /--openbitfun-control-height-sm/);
diff --git a/design-system/packages/ui/tests/search-field.test.mjs b/design-system/packages/ui/tests/search-field.test.mjs
index ed8bd0dcac..240aa57722 100644
--- a/design-system/packages/ui/tests/search-field.test.mjs
+++ b/design-system/packages/ui/tests/search-field.test.mjs
@@ -162,7 +162,8 @@ test("SearchField owns a quiet single-border focus without changing Input's focu
   assert.ok(panelFocusRule);
   assert.match(panelFocusRule, /outline-color: var\(--openbitfun-color-border-default\)/);
   assert.ok(focusRule);
-  assert.match(focusRule, /border-color: var\(--openbitfun-color-field-border-focus\)/);
+  assert.match(focusRule, /border-color: var\(--openbitfun-color-field-border-active\)/);
+  assert.doesNotMatch(inputStyles, /--openbitfun-color-field-border-focus|\.field[^{}]*:focus-visible/);
   assert.match(focusRule, /box-shadow: none/);
   assert.doesNotMatch(focusRule, /border-width|outline/);
 });
diff --git a/src/apps/data-migrator/ui/generated/design-system.css b/src/apps/data-migrator/ui/generated/design-system.css
index 1a27397f4c..54da7f2e68 100644
--- a/src/apps/data-migrator/ui/generated/design-system.css
+++ b/src/apps/data-migrator/ui/generated/design-system.css
@@ -724,9 +724,11 @@
     --openbitfun-color-control-switch-track-checked: #059cb0;
     --openbitfun-color-field-background: #ffffff;
     --openbitfun-color-field-background-hover: #ffffff;
-    --openbitfun-color-field-border: rgba(16, 26, 39, 0.15);
+    --openbitfun-color-field-border: rgba(0, 0, 0, 0.08);
+    --openbitfun-color-field-border-active: rgba(0, 0, 0, 0.20);
     --openbitfun-color-field-border-focus: #858585;
-    --openbitfun-color-field-border-hover: rgba(16, 26, 39, 0.24);
+    --openbitfun-color-field-border-hover: rgba(0, 0, 0, 0.20);
+    --openbitfun-color-field-placeholder: rgba(0, 0, 0, 0.40);
     --openbitfun-color-focus-ring: #6a6a6a;
     --openbitfun-color-identity-assistant-border: color-mix(in srgb, #db2777 15%, transparent);
     --openbitfun-color-identity-assistant-content: #db2777;
@@ -870,8 +872,10 @@
     --openbitfun-color-field-background: #1c1c1f;
     --openbitfun-color-field-background-hover: rgba(255, 255, 255, 0.06);
     --openbitfun-color-field-border: rgba(255, 255, 255, 0.18);
+    --openbitfun-color-field-border-active: #858585;
     --openbitfun-color-field-border-focus: #858585;
     --openbitfun-color-field-border-hover: rgba(255, 255, 255, 0.24);
+    --openbitfun-color-field-placeholder: #858585;
     --openbitfun-color-focus-ring: #60a5fa;
     --openbitfun-color-identity-assistant-border: color-mix(in srgb, #ec4899 15%, transparent);
     --openbitfun-color-identity-assistant-content: #ec4899;
@@ -986,8 +990,10 @@
     --openbitfun-color-control-switch-track: #3b3b3b;
     --openbitfun-color-control-switch-track-checked: #005fcc;
     --openbitfun-color-field-border: #3b3b3b;
+    --openbitfun-color-field-border-active: #005fcc;
     --openbitfun-color-field-border-focus: #005fcc;
     --openbitfun-color-field-border-hover: #000000;
+    --openbitfun-color-field-placeholder: #343434;
     --openbitfun-color-focus-ring: #005fcc;
     --openbitfun-color-identity-global-search-open-terminal: #000000;
     --openbitfun-color-key-hint-background: #e6e6e6;
@@ -1045,8 +1051,10 @@
     --openbitfun-color-control-switch-track: #b5b5b5;
     --openbitfun-color-control-switch-track-checked: #ffcc00;
     --openbitfun-color-field-border: #b5b5b5;
+    --openbitfun-color-field-border-active: #ffcc00;
     --openbitfun-color-field-border-focus: #ffcc00;
     --openbitfun-color-field-border-hover: #ffffff;
+    --openbitfun-color-field-placeholder: #d0d0d0;
     --openbitfun-color-focus-ring: #ffcc00;
     --openbitfun-color-identity-global-search-open-terminal: #ffffff;
     --openbitfun-color-key-hint-background: #343434;
diff --git a/src/apps/desktop/src/generated/bootstrap_theme.css b/src/apps/desktop/src/generated/bootstrap_theme.css
index ebd81937ec..80794639f6 100644
--- a/src/apps/desktop/src/generated/bootstrap_theme.css
+++ b/src/apps/desktop/src/generated/bootstrap_theme.css
@@ -60,8 +60,10 @@
     --openbitfun-color-field-background: #1c1c1f;
     --openbitfun-color-field-background-hover: rgba(255, 255, 255, 0.06);
     --openbitfun-color-field-border: rgba(255, 255, 255, 0.18);
+    --openbitfun-color-field-border-active: #858585;
     --openbitfun-color-field-border-focus: #858585;
     --openbitfun-color-field-border-hover: rgba(255, 255, 255, 0.24);
+    --openbitfun-color-field-placeholder: #858585;
     --openbitfun-color-focus-ring: #60a5fa;
     --openbitfun-color-identity-assistant-border: color-mix(in srgb, #ec4899 15%, transparent);
     --openbitfun-color-identity-assistant-content: #ec4899;
diff --git a/src/crates/contracts/product-domains/src/miniapp/generated/default_appearance_style.html b/src/crates/contracts/product-domains/src/miniapp/generated/default_appearance_style.html
index 1b9394556d..e3002891a2 100644
--- a/src/crates/contracts/product-domains/src/miniapp/generated/default_appearance_style.html
+++ b/src/crates/contracts/product-domains/src/miniapp/generated/default_appearance_style.html
@@ -64,7 +64,7 @@
     --openbitfun-focus-ring: #6a6a6a;
     --openbitfun-link: #2563eb;
     --openbitfun-field-bg: #ffffff;
-    --openbitfun-field-border: rgba(16, 26, 39, 0.15);
+    --openbitfun-field-border: rgba(0, 0, 0, 0.08);
     --openbitfun-field-border-focus: #858585;
     --openbitfun-scrollbar-thumb: rgba(0, 0, 0, 0.08);
     --openbitfun-scrollbar-thumb-hover: rgba(0, 0, 0, 0.10);
diff --git a/src/web-ui/src/infrastructure/appearance/builtins/appearancePresetOutput.test.ts b/src/web-ui/src/infrastructure/appearance/builtins/appearancePresetOutput.test.ts
index 411f185970..a23ce4a7ca 100644
--- a/src/web-ui/src/infrastructure/appearance/builtins/appearancePresetOutput.test.ts
+++ b/src/web-ui/src/infrastructure/appearance/builtins/appearancePresetOutput.test.ts
@@ -45,6 +45,27 @@ function statusContrast(content: string, tint: string, background: string): numb
 }
 
 describe('builtin appearance preset output', () => {
+  it('keeps published light field states in root and chrome while preserving named palettes', () => {
+    const settings = getBuiltinAppearance('openbitfun-light')?.renderers?.['theme-tokens']?.settings;
+    for (const tokens of [settings?.tokens, settings?.scopes?.chrome].filter(Boolean)) {
+      for (const [name, value] of Object.entries(themes.light)) {
+        if (name.startsWith('color.field.')) expect(tokens?.[themeCssVariables[name as ThemeTokenName]]).toBe(value);
+      }
+    }
+    expect(settings?.tokens['--openbitfun-color-field-border']).toBe('rgba(0, 0, 0, 0.08)');
+    expect(settings?.tokens['--openbitfun-color-field-border-hover']).toBe('rgba(0, 0, 0, 0.20)');
+    expect(settings?.tokens['--openbitfun-color-field-border-active']).toBe('rgba(0, 0, 0, 0.20)');
+    expect(settings?.tokens['--openbitfun-color-field-border-focus']).toBe(themes.light['color.field.borderFocus']);
+    expect(settings?.tokens['--openbitfun-color-field-placeholder']).toBe('rgba(0, 0, 0, 0.40)');
+    for (const palette of builtinAppearancePalettes) {
+      if (palette.id === 'openbitfun-light') continue;
+      const tokens = getBuiltinAppearanceThemeTokens(palette.id);
+      expect(tokens['--openbitfun-color-field-border']).toBe(palette.colors.border.base);
+      expect(tokens['--openbitfun-color-field-border-focus']).toBe(palette.colors.accent[500]);
+      expect(tokens['--openbitfun-color-field-border-active']).toBe(palette.colors.accent[500]);
+      expect(tokens['--openbitfun-color-field-placeholder']).toBe(palette.colors.text.muted);
+    }
+  });
   it('uses the public Button palette in default appearances without changing shared action colors', () => {
     for (const mode of ['light', 'dark'] as const) {
       const appearance = getBuiltinAppearance(`openbitfun-${mode}`);
diff --git a/src/web-ui/src/infrastructure/appearance/builtins/buildBuiltinAppearance.ts b/src/web-ui/src/infrastructure/appearance/builtins/buildBuiltinAppearance.ts
index 96b2f6886f..7ee70f7c76 100644
--- a/src/web-ui/src/infrastructure/appearance/builtins/buildBuiltinAppearance.ts
+++ b/src/web-ui/src/infrastructure/appearance/builtins/buildBuiltinAppearance.ts
@@ -76,6 +76,15 @@ function themeValuesToCssTokens(
       .map(([name, value]) => [themeCssVariables[name], String(value)]),
   ) as Record<AppearanceThemeTokenName, string>;
   if (palette.id === DEFAULT_LIGHT_APPEARANCE_ID || palette.id === DEFAULT_DARK_APPEARANCE_ID) {
+    if (palette.id === DEFAULT_LIGHT_APPEARANCE_ID) {
+      // Default light fields use the published neutral states in both root and
+      // chrome. Branded palettes and imported overrides retain their own colors.
+      for (const name of Object.keys(themes.light) as ThemeTokenName[]) {
+        if (name.startsWith('color.field.')) {
+          tokens[themeCssVariables[name] as AppearanceThemeTokenName] = String(themes.light[name]);
+        }
+      }
+    }
     return tokens;
   }
   // Branded presets retain their existing action palette; the default product
@@ -153,6 +162,8 @@ function createThemeTokenValues(palette: AppearancePalette): Record<ThemeTokenNa
     'color.field.border': colors.border.base,
     'color.field.borderHover': colors.border.medium,
     'color.field.borderFocus': colors.accent[500],
+    'color.field.borderActive': colors.accent[500],
+    'color.field.placeholder': colors.text.muted,
     'color.focus.ring': colors.accent[500],
     'color.status.info.content': colors.semantic.info,
     'color.status.info.surface': colors.semantic.infoBg,
@@ -236,6 +247,8 @@ function createChromeThemeTokens(
     'color.field.border': chrome.border.base,
     'color.field.borderHover': chrome.border.medium,
     'color.field.borderFocus': chrome.accent[500],
+    'color.field.borderActive': chrome.accent[500],
+    'color.field.placeholder': chrome.text.muted,
     'color.focus.ring': chrome.accent[500],
     'color.scrollbar.thumb': scrollbar.thumb,
     'color.scrollbar.thumbHover': scrollbar.thumbHover,
diff --git a/src/web-ui/src/infrastructure/appearance/builtins/composeAppearancePackage.test.ts b/src/web-ui/src/infrastructure/appearance/builtins/composeAppearancePackage.test.ts
index fac463c032..6ba3504858 100644
--- a/src/web-ui/src/infrastructure/appearance/builtins/composeAppearancePackage.test.ts
+++ b/src/web-ui/src/infrastructure/appearance/builtins/composeAppearancePackage.test.ts
@@ -4,6 +4,48 @@ import { APPEARANCE_THEME_TOKEN_NAMES } from './catalog';
 import { composeAppearancePackage } from './composeAppearancePackage';
 
 describe('composeAppearancePackage', () => {
+  it('preserves legacy field colors and explicit hint overrides across old-payload round trips', () => {
+    const original: AppearancePackage = {
+      schema: 'openbitfun.appearance', schemaVersion: 2,
+      id: 'example.legacy-fields', name: 'Legacy fields', version: '1.0.0', mode: 'light',
+      renderers: {
+        'theme-tokens': {
+          version: 1,
+          settings: {
+            tokens: {
+              '--openbitfun-color-field-border': '#123456',
+              '--openbitfun-color-field-border-focus': '#654321',
+              '--openbitfun-color-content-muted': '#778899',
+            },
+            scopes: { chrome: { '--openbitfun-color-content-muted': '#556677', '--openbitfun-color-field-border-focus': '#445566' } },
+          },
+        },
+      },
+    };
+    const payload = JSON.stringify(original);
+    const resolved = composeAppearancePackage(JSON.parse(payload));
+    const settings = resolved.renderers!['theme-tokens']!.settings;
+    expect(settings.tokens).toMatchObject({
+      '--openbitfun-color-field-border': '#123456',
+      '--openbitfun-color-field-border-focus': '#654321',
+      '--openbitfun-color-field-border-active': '#654321',
+      '--openbitfun-color-field-placeholder': '#778899',
+    });
+    expect(settings.scopes?.chrome?.['--openbitfun-color-field-placeholder']).toBe('#556677');
+    expect(settings.scopes?.chrome?.['--openbitfun-color-field-border-active']).toBe('#445566');
+    expect(composeAppearancePackage(JSON.parse(JSON.stringify(resolved))).renderers?.['theme-tokens']).toEqual(resolved.renderers?.['theme-tokens']);
+    expect(JSON.stringify(original)).toBe(payload);
+
+    original.renderers!['theme-tokens']!.settings.tokens['--openbitfun-color-field-placeholder'] = '#112233';
+    original.renderers!['theme-tokens']!.settings.tokens['--openbitfun-color-field-border-active'] = '#223344';
+    original.renderers!['theme-tokens']!.settings.scopes!.chrome!['--openbitfun-color-field-placeholder'] = '#334455';
+    original.renderers!['theme-tokens']!.settings.scopes!.chrome!['--openbitfun-color-field-border-active'] = '#556688';
+    const explicit = composeAppearancePackage(original).renderers!['theme-tokens']!.settings;
+    expect(explicit.tokens['--openbitfun-color-field-placeholder']).toBe('#112233');
+    expect(explicit.tokens['--openbitfun-color-field-border-active']).toBe('#223344');
+    expect(explicit.scopes?.chrome?.['--openbitfun-color-field-placeholder']).toBe('#334455');
+    expect(explicit.scopes?.chrome?.['--openbitfun-color-field-border-active']).toBe('#556688');
+  });
   it('keeps explicit legacy Button colors through a package round trip without requiring new tokens', () => {
     const original: AppearancePackage = {
       schema: 'openbitfun.appearance', schemaVersion: 2,
diff --git a/src/web-ui/src/infrastructure/appearance/builtins/composeAppearancePackage.ts b/src/web-ui/src/infrastructure/appearance/builtins/composeAppearancePackage.ts
index efdbd0eec5..935c02d9a9 100644
--- a/src/web-ui/src/infrastructure/appearance/builtins/composeAppearancePackage.ts
+++ b/src/web-ui/src/infrastructure/appearance/builtins/composeAppearancePackage.ts
@@ -13,6 +13,7 @@ import {
   getBuiltinAppearance,
 } from './catalog';
 import { withLegacyButtonTokens } from './buttonThemeCompatibility';
+import { withLegacyFieldTokens } from './fieldThemeCompatibility';
 
 const COMPOSITION_LAYERS = Symbol('openbitfun.appearance.composition-layers');
 
@@ -121,12 +122,12 @@ function mergeRenderers(
         ...override['theme-tokens'].settings,
         tokens: {
           ...(base?.['theme-tokens']?.settings.tokens ?? {}),
-          ...withLegacyButtonTokens(override['theme-tokens'].settings.tokens),
+          ...withLegacyFieldTokens(withLegacyButtonTokens(override['theme-tokens'].settings.tokens)),
         },
         scopes: {
           chrome: {
             ...(base?.['theme-tokens']?.settings.scopes?.chrome ?? {}),
-            ...withLegacyButtonTokens(override['theme-tokens'].settings.scopes?.chrome),
+            ...withLegacyFieldTokens(withLegacyButtonTokens(override['theme-tokens'].settings.scopes?.chrome)),
           },
         },
       },
diff --git a/src/web-ui/src/infrastructure/appearance/builtins/fieldThemeCompatibility.ts b/src/web-ui/src/infrastructure/appearance/builtins/fieldThemeCompatibility.ts
new file mode 100644
index 0000000000..fce11ae98b
--- /dev/null
+++ b/src/web-ui/src/infrastructure/appearance/builtins/fieldThemeCompatibility.ts
@@ -0,0 +1,18 @@
+import type { AppearanceThemeTokenName } from '../types';
+
+// Old packages used content.muted for hints and borderFocus for editing. Explicit field colors
+// take precedence; missing values continue to come from the selected base theme.
+export function withLegacyFieldTokens(
+  tokens: Partial<Record<AppearanceThemeTokenName, string>> | undefined,
+): Partial<Record<AppearanceThemeTokenName, string>> {
+  const result = { ...tokens };
+  const legacy = tokens?.['--openbitfun-color-content-muted'];
+  if (result['--openbitfun-color-field-placeholder'] === undefined && legacy !== undefined) {
+    result['--openbitfun-color-field-placeholder'] = legacy;
+  }
+  const legacyFocus = tokens?.['--openbitfun-color-field-border-focus'];
+  if (result['--openbitfun-color-field-border-active'] === undefined && legacyFocus !== undefined) {
+    result['--openbitfun-color-field-border-active'] = legacyFocus;
+  }
+  return result;
+}
diff --git a/src/web-ui/src/shared/ui/SearchField.test.tsx b/src/web-ui/src/shared/ui/SearchField.test.tsx
new file mode 100644
index 0000000000..9444710051
--- /dev/null
+++ b/src/web-ui/src/shared/ui/SearchField.test.tsx
@@ -0,0 +1,85 @@
+// @vitest-environment jsdom
+import React, { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { Icon, SearchField, type SearchFieldProps } from '@openbitfun/ui';
+
+globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+
+describe('public SearchField product integration', () => {
+  let host: HTMLDivElement;
+  let root: Root;
+  const clear = vi.fn();
+  const search = vi.fn();
+  const render = (props: Partial<SearchFieldProps> = {}) => act(() => root.render(
+    <SearchField
+      aria-label="Search sessions"
+      clearLabel="Clear search"
+      defaultValue="OpenBitFun"
+      leadingIcon={<Icon name="search" />}
+      onClear={clear}
+      onSearch={search}
+      shortcut="Ctrl K"
+      size="sm"
+      {...props}
+    />,
+  ));
+  const clearButton = () => host.querySelector<HTMLButtonElement>('button[aria-label="Clear search"]')!;
+
+  beforeEach(() => {
+    host = document.createElement('div');
+    document.body.append(host);
+    root = createRoot(host);
+    clear.mockClear();
+    search.mockClear();
+  });
+  afterEach(() => {
+    act(() => root.unmount());
+    host.remove();
+  });
+
+  it('keeps shortcut, trailing content, and clear action together without hiding the action', () => {
+    render({ trailing: <span role="status">1 / 5</span> });
+    expect(host.textContent).toContain('1 / 5Ctrl K');
+    expect(clearButton().closest('[aria-hidden="true"]')).toBeNull();
+    const iconWrapper = host.querySelector('[data-openbitfun-component="input"] > [data-openbitfun-part="leading"] > [data-openbitfun-part="icon"]');
+    expect(iconWrapper?.querySelector('[data-openbitfun-component="icon"][data-size="lg"]')).not.toBeNull();
+    act(() => clearButton().click());
+    expect(clear).toHaveBeenCalledTimes(1);
+  });
+
+  it.each([{ disabled: true }, { readOnly: true }])('blocks clearing an immutable field: %o', (props) => {
+    render(props);
+    const input = host.querySelector('input')!;
+    expect(input.disabled || input.readOnly).toBe(true);
+    expect(clearButton().disabled).toBe(true);
+    act(() => {
+      clearButton().click();
+      clearButton().dispatchEvent(new MouseEvent('click', { bubbles: true }));
+    });
+    expect(clear).not.toHaveBeenCalled();
+    expect(input.value).toBe('OpenBitFun');
+    render();
+    act(() => clearButton().click());
+    expect(clear).toHaveBeenCalledTimes(1);
+  });
+
+  it('preserves focused editing on clear and respects canceled or IME-owned Enter', () => {
+    const onKeyDown = vi.fn((event: React.KeyboardEvent<HTMLInputElement>) => event.preventDefault());
+    render({ onKeyDown });
+    const input = host.querySelector('input')!;
+    act(() => input.focus());
+    const mouseDown = new MouseEvent('mousedown', { bubbles: true, cancelable: true });
+    act(() => clearButton().dispatchEvent(mouseDown));
+    expect(mouseDown.defaultPrevented).toBe(true);
+    expect(document.activeElement).toBe(input);
+    act(() => input.dispatchEvent(new KeyboardEvent('keydown', { bubbles: true, cancelable: true, key: 'Enter' })));
+    expect(onKeyDown).toHaveBeenCalledTimes(1);
+    expect(search).not.toHaveBeenCalled();
+    render();
+    act(() => input.dispatchEvent(new KeyboardEvent('keydown', { bubbles: true, key: 'Enter', isComposing: true })));
+    expect(search).not.toHaveBeenCalled();
+    act(() => input.dispatchEvent(new KeyboardEvent('keydown', { bubbles: true, key: 'Enter' })));
+    expect(search).toHaveBeenCalledWith('OpenBitFun');
+  });
+});
diff --git a/src/web-ui/src/tools/generative-widget/appearancePayload.test.ts b/src/web-ui/src/tools/generative-widget/appearancePayload.test.ts
index 3aad9aad7f..7129b89d90 100644
--- a/src/web-ui/src/tools/generative-widget/appearancePayload.test.ts
+++ b/src/web-ui/src/tools/generative-widget/appearancePayload.test.ts
@@ -34,6 +34,12 @@ const BUTTON_THEME_VARIABLE_NAMES = [
   '--openbitfun-component-button-text-content-disabled',
   '--openbitfun-component-button-text-content-hover',
 ] as const;
+// Field editing borders and hints have dedicated semantics; preserve the shared
+// contract fingerprint while asserting these two additions by their exact names.
+const FIELD_STATE_THEME_VARIABLE_NAMES = [
+  '--openbitfun-color-field-border-active',
+  '--openbitfun-color-field-placeholder',
+] as const;
 const RETIRED_WIDGET_VARIABLE_NAMES = [
   '--background-primary',
   '--bg-primary',
@@ -77,8 +83,13 @@ describe('generated widget appearance payload contract', () => {
     expect(WIDGET_APPEARANCE_VAR_NAMES).toEqual(CANONICAL_THEME_VARIABLE_NAMES);
     expect(new Set(WIDGET_APPEARANCE_VAR_NAMES).size).toBe(WIDGET_APPEARANCE_VAR_NAMES.length);
     const buttonNames = WIDGET_APPEARANCE_VAR_NAMES.filter(name => name.startsWith('--openbitfun-component-button-'));
-    const sharedNames = WIDGET_APPEARANCE_VAR_NAMES.filter(name => !name.startsWith('--openbitfun-component-button-'));
+    const fieldStateNames = WIDGET_APPEARANCE_VAR_NAMES.filter(name => FIELD_STATE_THEME_VARIABLE_NAMES.some(fieldName => fieldName === name));
+    const sharedNames = WIDGET_APPEARANCE_VAR_NAMES.filter(name => (
+      !name.startsWith('--openbitfun-component-button-')
+      && !FIELD_STATE_THEME_VARIABLE_NAMES.some(fieldName => fieldName === name)
+    ));
     expect(buttonNames).toEqual(BUTTON_THEME_VARIABLE_NAMES);
+    expect(fieldStateNames).toEqual(FIELD_STATE_THEME_VARIABLE_NAMES);
     expect({
       count: sharedNames.length,
       hash: hashNames(sharedNames),
@@ -137,6 +148,8 @@ describe('generated widget appearance payload contract', () => {
       '--openbitfun-color-action-primary-pressed': '#202020',
       '--openbitfun-component-button-primary-background': '#303030',
       '--openbitfun-component-button-fill-background': 'rgba(0, 0, 0, 0.08)',
+      '--openbitfun-color-field-border-active': 'rgba(0, 0, 0, 0.20)',
+      '--openbitfun-color-field-placeholder': 'rgba(0, 0, 0, 0.40)',
       '--openbitfun-color-status-danger-surface': 'rgba(200, 0, 0, 0.12)',
       '--openbitfun-color-status-danger-border': '#303030',
       '--openbitfun-shadow-raised': '0 1px 2px #404040',