From 3e9f75888074868c9c988a375b166d1a4227e2e3 Mon Sep 17 00:00:00 2001
From: kev1n77 <fmy077@outlook.com>
Date: Tue, 8 Sep 2026 22:10:54 +0800
Subject: [PATCH 1/2] fix(ui): align field states and search affordances

Align light field borders and placeholder colors while preserving visible
keyboard focus contrast, named theme palettes, and legacy imported overrides.

Size search artwork through the existing Input slot, show shortcuts together
with clear actions, and prevent clearing disabled or read-only fields.
Keep all existing size tokens, size APIs, heights, and product size selections.

Update Design Lab state examples, DOM regression coverage and generated theme
projections. Validate with design-system:check, check:web, 48 product tests,
and 22 focused component tests.
---
 .../apps/design-lab/src/i18n/messages.ts      |  9 ++
 .../src/pages/ComponentDetailPage.tsx         | 59 +++++++------
 .../vite/component-detail-contract.test.mjs   | 10 ++-
 .../packages/theme-openbitfun/README.md       | 11 +++
 .../theme-openbitfun/src/dark.tokens.json     |  1 +
 .../src/high-contrast-dark.tokens.json        |  1 +
 .../src/high-contrast-light.tokens.json       |  1 +
 .../theme-openbitfun/src/light.tokens.json    |  5 +-
 design-system/packages/ui/README.md           |  4 +
 .../ui/src/components/Input/Input.meta.ts     |  5 +-
 .../ui/src/components/Input/Input.module.css  | 18 +++-
 .../SearchField/SearchField.meta.ts           |  4 +-
 .../SearchField/SearchField.module.css        | 16 ++++
 .../components/SearchField/SearchField.tsx    | 20 +++--
 .../ui/src/components/Select/Select.meta.ts   |  2 +
 .../src/components/Select/Select.module.css   |  5 +-
 .../packages/ui/tests/icon-slots.test.mjs     |  1 +
 .../packages/ui/tests/search-field.test.mjs   |  3 +-
 .../ui/generated/design-system.css            |  8 +-
 .../desktop/src/generated/bootstrap_theme.css |  1 +
 .../generated/default_appearance_style.html   |  2 +-
 .../builtins/appearancePresetOutput.test.ts   | 19 +++++
 .../builtins/buildBuiltinAppearance.ts        | 11 +++
 .../builtins/composeAppearancePackage.test.ts | 36 ++++++++
 .../builtins/composeAppearancePackage.ts      |  5 +-
 .../builtins/fieldThemeCompatibility.ts       | 14 +++
 src/web-ui/src/shared/ui/SearchField.test.tsx | 85 +++++++++++++++++++
 27 files changed, 306 insertions(+), 50 deletions(-)
 create mode 100644 src/web-ui/src/infrastructure/appearance/builtins/fieldThemeCompatibility.ts
 create mode 100644 src/web-ui/src/shared/ui/SearchField.test.tsx

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/vite/component-detail-contract.test.mjs b/design-system/apps/design-lab/vite/component-detail-contract.test.mjs
index ccb3768dc4..59db2b8b13 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,16 @@ 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"\}/);
 });
 
 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..a8f3314d30 100644
--- a/design-system/packages/theme-openbitfun/README.md
+++ b/design-system/packages/theme-openbitfun/README.md
@@ -28,6 +28,17 @@ 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 ordinary focus-within borders. Keyboard-visible
+focus retains the existing 3:1 contrast border in every mode; a browser may also
+show this stronger indicator when focusing an editable input with a pointer.
+`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.
+
 `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..2e87ec6b90 100644
--- a/design-system/packages/theme-openbitfun/src/dark.tokens.json
+++ b/design-system/packages/theme-openbitfun/src/dark.tokens.json
@@ -175,6 +175,7 @@
       }
     },
     "field": {
+      "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..0f4a43c036 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,7 @@
       }
     },
     "field": {
+      "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..83acd5f4e4 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,7 @@
       }
     },
     "field": {
+      "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..7e3148579e 100644
--- a/design-system/packages/theme-openbitfun/src/light.tokens.json
+++ b/design-system/packages/theme-openbitfun/src/light.tokens.json
@@ -175,10 +175,11 @@
       }
     },
     "field": {
+      "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..e791779e57 100644
--- a/design-system/packages/ui/src/components/Input/Input.meta.ts
+++ b/design-system/packages/ui/src/components/Input/Input.meta.ts
@@ -12,16 +12,19 @@ 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",
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..cc18b86a68 100644
--- a/design-system/packages/ui/src/components/Input/Input.module.css
+++ b/design-system/packages/ui/src/components/Input/Input.module.css
@@ -29,6 +29,11 @@
   }
 
   .field:focus-within {
+    border-color: var(--openbitfun-color-field-border-hover);
+    box-shadow: none;
+  }
+
+  .field:has(:focus-visible) {
     border-color: var(--openbitfun-color-field-border-focus);
     box-shadow: none;
   }
@@ -47,6 +52,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 +80,7 @@
   }
 
   .input::placeholder {
-    color: var(--openbitfun-color-content-muted);
+    color: var(--openbitfun-color-field-placeholder);
     opacity: 1;
   }
 
@@ -85,16 +94,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);
@@ -113,7 +124,8 @@
       border-color: ButtonText;
     }
 
-    .field:focus-within {
+    .field:focus-within,
+    .field:has(:focus-visible) {
       border-color: Highlight;
     }
   }
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..6faed4e674 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,6 +32,7 @@ export const searchFieldMeta = {
     "color.border.subtle",
     "color.border.default",
     "color.field.background",
+    "color.field.placeholder",
     "color.field.backgroundHover",
     "color.field.border",
     "color.field.borderHover",
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/search-field.test.mjs b/design-system/packages/ui/tests/search-field.test.mjs
index ed8bd0dcac..ece6720931 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-hover\)/);
+  assert.match(inputStyles, /\.field:has\(:focus-visible\)\s*\{[^}]*border-color: var\(--openbitfun-color-field-border-focus\)/);
   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..d043458fde 100644
--- a/src/apps/data-migrator/ui/generated/design-system.css
+++ b/src/apps/data-migrator/ui/generated/design-system.css
@@ -724,9 +724,10 @@
     --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-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;
@@ -872,6 +873,7 @@
     --openbitfun-color-field-border: rgba(255, 255, 255, 0.18);
     --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;
@@ -988,6 +990,7 @@
     --openbitfun-color-field-border: #3b3b3b;
     --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;
@@ -1047,6 +1050,7 @@
     --openbitfun-color-field-border: #b5b5b5;
     --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..31a1f8ee65 100644
--- a/src/apps/desktop/src/generated/bootstrap_theme.css
+++ b/src/apps/desktop/src/generated/bootstrap_theme.css
@@ -62,6 +62,7 @@
     --openbitfun-color-field-border: rgba(255, 255, 255, 0.18);
     --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..31ec091dfa 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,25 @@ 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-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-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..15865451a1 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,7 @@ 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.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 +246,7 @@ function createChromeThemeTokens(
     'color.field.border': chrome.border.base,
     'color.field.borderHover': chrome.border.medium,
     'color.field.borderFocus': 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..2b3890ea76 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,42 @@ 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' } },
+          },
+        },
+      },
+    };
+    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-placeholder': '#778899',
+    });
+    expect(settings.scopes?.chrome?.['--openbitfun-color-field-placeholder']).toBe('#556677');
+    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.scopes!.chrome!['--openbitfun-color-field-placeholder'] = '#334455';
+    const explicit = composeAppearancePackage(original).renderers!['theme-tokens']!.settings;
+    expect(explicit.tokens['--openbitfun-color-field-placeholder']).toBe('#112233');
+    expect(explicit.scopes?.chrome?.['--openbitfun-color-field-placeholder']).toBe('#334455');
+  });
   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..f6b159d314
--- /dev/null
+++ b/src/web-ui/src/infrastructure/appearance/builtins/fieldThemeCompatibility.ts
@@ -0,0 +1,14 @@
+import type { AppearanceThemeTokenName } from '../types';
+
+// Old packages colored field hints through content.muted. 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;
+  }
+  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');
+  });
+});

From 447a41aeb1021fef19546586388b748f3238db28 Mon Sep 17 00:00:00 2001
From: kev1n77 <fmy077@outlook.com>
Date: Tue, 8 Sep 2026 22:51:35 +0800
Subject: [PATCH 2/2] fix(ui): match text field active borders to design

Use the dedicated field editing color for Input and SearchField so native
focus-visible heuristics do not replace the light 20% border with dark gray.
Remove Design Lab's additional focus shadow and keep the existing 1px border
and all control geometry unchanged.

Preserve dark and high-contrast focus colors and inherit explicit legacy
Appearance focus overrides unless an editing color is supplied. Keep the
stronger generic focus contract available to its other control consumers.

Update theme projections and regression checks. Validation: design-system:check,
check:web, and 21 focused product tests.
---
 design-system/apps/design-lab/src/styles.css      |  9 ++-------
 .../vite/component-detail-contract.test.mjs       |  8 ++++++++
 design-system/packages/theme-openbitfun/README.md | 13 ++++++++++---
 .../theme-openbitfun/src/dark.tokens.json         |  1 +
 .../src/high-contrast-dark.tokens.json            |  1 +
 .../src/high-contrast-light.tokens.json           |  1 +
 .../theme-openbitfun/src/light.tokens.json        |  1 +
 .../ui/src/components/Input/Input.meta.ts         |  2 +-
 .../ui/src/components/Input/Input.module.css      | 10 ++--------
 .../components/SearchField/SearchField.meta.ts    |  1 +
 design-system/packages/ui/tests/input.test.mjs    |  2 +-
 .../packages/ui/tests/search-field.test.mjs       |  4 ++--
 .../data-migrator/ui/generated/design-system.css  |  4 ++++
 .../desktop/src/generated/bootstrap_theme.css     |  1 +
 .../builtins/appearancePresetOutput.test.ts       |  2 ++
 .../appearance/builtins/buildBuiltinAppearance.ts |  2 ++
 .../builtins/composeAppearancePackage.test.ts     |  8 +++++++-
 .../builtins/fieldThemeCompatibility.ts           |  6 +++++-
 .../generative-widget/appearancePayload.test.ts   | 15 ++++++++++++++-
 19 files changed, 66 insertions(+), 25 deletions(-)

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 59db2b8b13..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
@@ -429,6 +429,14 @@ test("Input, KeyHint, and SearchField previews expose composable slot and state
   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 a8f3314d30..29f6a9d2a6 100644
--- a/design-system/packages/theme-openbitfun/README.md
+++ b/design-system/packages/theme-openbitfun/README.md
@@ -29,15 +29,22 @@ 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 ordinary focus-within borders. Keyboard-visible
-focus retains the existing 3:1 contrast border in every mode; a browser may also
-show this stronger indicator when focusing an editable input with a pointer.
+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
diff --git a/design-system/packages/theme-openbitfun/src/dark.tokens.json b/design-system/packages/theme-openbitfun/src/dark.tokens.json
index 2e87ec6b90..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,7 @@
       }
     },
     "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)" },
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 0f4a43c036..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,7 @@
       }
     },
     "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}" },
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 83acd5f4e4..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,7 @@
       }
     },
     "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}" },
diff --git a/design-system/packages/theme-openbitfun/src/light.tokens.json b/design-system/packages/theme-openbitfun/src/light.tokens.json
index 7e3148579e..62f525e3fc 100644
--- a/design-system/packages/theme-openbitfun/src/light.tokens.json
+++ b/design-system/packages/theme-openbitfun/src/light.tokens.json
@@ -175,6 +175,7 @@
       }
     },
     "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}" },
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 e791779e57..8462fa2743 100644
--- a/design-system/packages/ui/src/components/Input/Input.meta.ts
+++ b/design-system/packages/ui/src/components/Input/Input.meta.ts
@@ -28,7 +28,7 @@ export const inputMeta = {
     "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 cc18b86a68..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,12 +29,7 @@
   }
 
   .field:focus-within {
-    border-color: var(--openbitfun-color-field-border-hover);
-    box-shadow: none;
-  }
-
-  .field:has(:focus-visible) {
-    border-color: var(--openbitfun-color-field-border-focus);
+    border-color: var(--openbitfun-color-field-border-active);
     box-shadow: none;
   }
 
@@ -124,8 +119,7 @@
       border-color: ButtonText;
     }
 
-    .field:focus-within,
-    .field:has(:focus-visible) {
+    .field:focus-within {
       border-color: Highlight;
     }
   }
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 6faed4e674..d923f05a60 100644
--- a/design-system/packages/ui/src/components/SearchField/SearchField.meta.ts
+++ b/design-system/packages/ui/src/components/SearchField/SearchField.meta.ts
@@ -36,6 +36,7 @@ export const searchFieldMeta = {
     "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/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 ece6720931..240aa57722 100644
--- a/design-system/packages/ui/tests/search-field.test.mjs
+++ b/design-system/packages/ui/tests/search-field.test.mjs
@@ -162,8 +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-hover\)/);
-  assert.match(inputStyles, /\.field:has\(:focus-visible\)\s*\{[^}]*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 d043458fde..54da7f2e68 100644
--- a/src/apps/data-migrator/ui/generated/design-system.css
+++ b/src/apps/data-migrator/ui/generated/design-system.css
@@ -725,6 +725,7 @@
     --openbitfun-color-field-background: #ffffff;
     --openbitfun-color-field-background-hover: #ffffff;
     --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(0, 0, 0, 0.20);
     --openbitfun-color-field-placeholder: rgba(0, 0, 0, 0.40);
@@ -871,6 +872,7 @@
     --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;
@@ -988,6 +990,7 @@
     --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;
@@ -1048,6 +1051,7 @@
     --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;
diff --git a/src/apps/desktop/src/generated/bootstrap_theme.css b/src/apps/desktop/src/generated/bootstrap_theme.css
index 31a1f8ee65..80794639f6 100644
--- a/src/apps/desktop/src/generated/bootstrap_theme.css
+++ b/src/apps/desktop/src/generated/bootstrap_theme.css
@@ -60,6 +60,7 @@
     --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;
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 31ec091dfa..a23ce4a7ca 100644
--- a/src/web-ui/src/infrastructure/appearance/builtins/appearancePresetOutput.test.ts
+++ b/src/web-ui/src/infrastructure/appearance/builtins/appearancePresetOutput.test.ts
@@ -54,6 +54,7 @@ describe('builtin appearance preset output', () => {
     }
     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) {
@@ -61,6 +62,7 @@ describe('builtin appearance preset output', () => {
       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);
     }
   });
diff --git a/src/web-ui/src/infrastructure/appearance/builtins/buildBuiltinAppearance.ts b/src/web-ui/src/infrastructure/appearance/builtins/buildBuiltinAppearance.ts
index 15865451a1..7ee70f7c76 100644
--- a/src/web-ui/src/infrastructure/appearance/builtins/buildBuiltinAppearance.ts
+++ b/src/web-ui/src/infrastructure/appearance/builtins/buildBuiltinAppearance.ts
@@ -162,6 +162,7 @@ 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,
@@ -246,6 +247,7 @@ 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,
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 2b3890ea76..6ba3504858 100644
--- a/src/web-ui/src/infrastructure/appearance/builtins/composeAppearancePackage.test.ts
+++ b/src/web-ui/src/infrastructure/appearance/builtins/composeAppearancePackage.test.ts
@@ -17,7 +17,7 @@ describe('composeAppearancePackage', () => {
               '--openbitfun-color-field-border-focus': '#654321',
               '--openbitfun-color-content-muted': '#778899',
             },
-            scopes: { chrome: { '--openbitfun-color-content-muted': '#556677' } },
+            scopes: { chrome: { '--openbitfun-color-content-muted': '#556677', '--openbitfun-color-field-border-focus': '#445566' } },
           },
         },
       },
@@ -28,17 +28,23 @@ describe('composeAppearancePackage', () => {
     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 = {
diff --git a/src/web-ui/src/infrastructure/appearance/builtins/fieldThemeCompatibility.ts b/src/web-ui/src/infrastructure/appearance/builtins/fieldThemeCompatibility.ts
index f6b159d314..fce11ae98b 100644
--- a/src/web-ui/src/infrastructure/appearance/builtins/fieldThemeCompatibility.ts
+++ b/src/web-ui/src/infrastructure/appearance/builtins/fieldThemeCompatibility.ts
@@ -1,6 +1,6 @@
 import type { AppearanceThemeTokenName } from '../types';
 
-// Old packages colored field hints through content.muted. Explicit field colors
+// 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,
@@ -10,5 +10,9 @@ export function withLegacyFieldTokens(
   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/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',