From bc0d8fcf23fec0bfab10c6e44b4e97d0ad5eedd2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E6=B8=85=E5=87=A4?= <qingf622@outlook.com>
Date: Fri, 23 Oct 2026 22:25:27 +0800
Subject: [PATCH 1/4] =?UTF-8?q?feat(ui):=20Textarea=20=E5=A2=9E=E5=8A=A0?=
 =?UTF-8?q?=E5=8E=9F=E4=BD=8D=E7=BC=96=E8=BE=91=E4=B8=8E=E5=93=81=E7=89=8C?=
 =?UTF-8?q?=E8=89=B2=E5=BA=95=E9=80=89=E9=A1=B9=EF=BC=8C=E6=96=B0=E5=A2=9E?=
 =?UTF-8?q?=20InfoHint?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Textarea engage="hover"：悬停也显示激活边框，仅用于外观与原内容一致的原位编辑框
- Textarea surface="brand-tint" 与 --field-edge-brand-tint：画在品牌色底上的输入框，激活边框浅色为近黑、深色为 --brand
- InfoHint：只负责解释的 12px ⓘ，非按钮、可键盘聚焦，Tooltip 默认向上
- AGENTS.md 与 showcase 同步记录

Refs: MEMOH-222
---
 AGENTS.md                             | 23 ++++++++++++-
 showcase/specs/index.ts               |  2 ++
 showcase/specs/info-hint.ts           | 48 +++++++++++++++++++++++++++
 showcase/specs/textarea.ts            | 42 ++++++++++++++++++++---
 src/components/info-hint/InfoHint.vue | 44 ++++++++++++++++++++++++
 src/components/info-hint/index.ts     |  6 ++++
 src/components/textarea/Textarea.vue  | 15 +++++++++
 src/components/textarea/index.ts      |  7 ++++
 src/index.ts                          |  1 +
 src/style.css                         | 20 +++++++++++
 10 files changed, 203 insertions(+), 5 deletions(-)
 create mode 100644 showcase/specs/info-hint.ts
 create mode 100644 src/components/info-hint/InfoHint.vue
 create mode 100644 src/components/info-hint/index.ts

diff --git a/AGENTS.md b/AGENTS.md
index 1c15607..ae64a11 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -224,6 +224,16 @@ which silently leaves the SVG at its 24px intrinsic size.)
 of hand-rolling a hover on text. For an underlined inline link inside running
 prose use `variant="link"`; for a control-sized action use a normal `<Button>`.
 
+### "An ⓘ that only explains" = `<InfoHint text="…">`
+
+A glyph whose whole job is to reveal a short explanation is NOT an action, so it
+is not an icon `<Button>` (no hover chip, no pointer cursor) and not a
+hand-rolled span. `<InfoHint>` is a muted 12px Info glyph (the text rung of the
+icon ladder — it sits beside text-scale labels) that opens a Tooltip on hover or
+keyboard focus, upward by default (`side`). The text doubles as the glyph's
+accessible name. Tooltip rules still apply: supplementary information only, as
+it is unreachable on touch.
+
 ### "A card that DOES something / goes somewhere" = `<ActionCard>`
 
 The recurring need to offer an **entry point** — a card that, when clicked, takes
@@ -332,7 +342,8 @@ peers", not "one door to somewhere else".
   ramp (`--btn-primary` → `-hover` → `-active`); `variant="default"`/`"primary"`
   use it. Brand purple (`--brand`) is the SCARCE accent — it ships only via
   `<Button variant="brand">` (rare brand CTAs like chat Send) and a handful of
-  reserved tokens (`--sidebar-primary`, capability/event accents). Never make
+  reserved tokens (`--sidebar-primary`, capability/event accents, the dark
+  `--field-edge-brand-tint`). Never make
   purple a default surface or a large fill; the skeleton stays black/white/gray.
 - **Destructive is filled, not ghost.** `variant="destructive"` renders a solid
   `bg-destructive text-destructive-foreground` button — a filled red CTA. Never
@@ -368,6 +379,16 @@ peers", not "one door to somewhere else".
   hairline whose color swaps per state (never an outer ring):
   `--field-edge-rest` → `--field-edge-solid` (focus) / `--field-edge-engaged`
   (subtle) / `--destructive` (invalid).
+  - The one exception is opt-in: `<Textarea engage="hover">` also engages under
+    the pointer, with the same `--field-edge-solid`. It is for an in-place
+    editor that wears the exact look of the content it replaced (the chat
+    prompt edited inside its own bubble) — the edge is its only sign of being a
+    field. Forms and ordinary fields never use it.
+  - A Textarea painted on a brand-tinted surface (that same bubble) declares it
+    with `surface="brand-tint"`: its solid edge becomes `--field-edge-brand-tint`
+    — the neutral near-black in light (a brand edge muddies into a pale tint),
+    `--brand` in dark (the neutral gray sinks into a deep tint). Rest and
+    invalid are unchanged. Never pick an edge color per call site.
 - **Focus ring** is `--ring` via `focus-visible:ring-2 ring-ring/<alpha>` (or the
   segmented's 2px-track + 4px-ring inset). Keyboard focus only — not a resting
   border. Controls that keep DOM focus after a mouse action (Select trigger,
diff --git a/showcase/specs/index.ts b/showcase/specs/index.ts
index 102c9e3..c71b739 100644
--- a/showcase/specs/index.ts
+++ b/showcase/specs/index.ts
@@ -8,6 +8,7 @@ import { checkboxSpec } from './checkbox'
 import { dialogSpec } from './dialog'
 import { dropdownMenuSpec } from './dropdown-menu'
 import { fieldSpec } from './field'
+import { infoHintSpec } from './info-hint'
 import { inputSpec } from './input'
 import { inputGroupSpec } from './input-group'
 import { nativeSelectSpec } from './native-select'
@@ -51,5 +52,6 @@ export const componentSpecs: ComponentSpec[] = [
   popoverSpec,
   dropdownMenuSpec,
   tooltipSpec,
+  infoHintSpec,
   sonnerSpec,
 ]
diff --git a/showcase/specs/info-hint.ts b/showcase/specs/info-hint.ts
new file mode 100644
index 0000000..1803f44
--- /dev/null
+++ b/showcase/specs/info-hint.ts
@@ -0,0 +1,48 @@
+import type { ComponentSpec } from '../lib/spec'
+import { h } from 'vue'
+import { Button } from '#/components/button'
+import { InfoHint } from '#/components/info-hint'
+import { tooltipSideKeys } from '#/components/tooltip'
+
+export const infoHintSpec: ComponentSpec = {
+  id: 'info-hint',
+  name: 'InfoHint',
+  interactive: true,
+  description:
+    'A muted ⓘ glyph that only explains: hover or keyboard focus opens a short Tooltip. Not an action, so not a button.',
+  descriptionZh:
+    '只负责解释的灰色 ⓘ 图标：悬停或键盘聚焦时弹出简短的 Tooltip。它不是操作，所以不是按钮。',
+  controls: [
+    { kind: 'enum', key: 'side', label: 'Side', options: tooltipSideKeys, default: 'top', display: 'segmented' },
+    {
+      kind: 'string',
+      key: 'text',
+      label: 'Text',
+      default: 'Saving replaces this message and the reply after it.',
+    },
+  ],
+  examples: [
+    {
+      name: 'Beside an action row',
+      nameZh: '放在操作行旁边',
+      // Real placement: it explains what the buttons next to it will do,
+      // sitting at the text scale of their labels.
+      render: state => h('div', { class: 'flex items-center gap-1.5' }, [
+        h(InfoHint, { text: String(state.text), side: state.side as never }),
+        h(Button, { variant: 'ghost', tone: 'muted', size: 'sm' }, () => 'Cancel'),
+        h(Button, { variant: 'primary', size: 'sm' }, () => 'Save'),
+      ]),
+    },
+  ],
+  render: state => h(InfoHint, { text: String(state.text), side: state.side as never }),
+  usage: `InfoHint carries supplementary explanation only — like any Tooltip it is unreachable on touch, so nothing essential may live only inside it.
+
+- Use it when a glyph's whole job is to explain. If clicking should DO something, that is a Button.
+- The glyph is 12px (the icon ladder's text rung) and muted; do not resize or recolor it per call site.
+- The text is also the accessible name — write it as a full sentence.`,
+  usageZh: `InfoHint 只放补充说明——和所有 Tooltip 一样，触屏上看不到，所以关键信息绝不能只放在里面。
+
+- 图标的唯一作用是解释时用它；点了要执行操作的，应该用 Button。
+- 图标固定 12px（图标尺寸阶梯的文字档）、灰色；不要在调用处改尺寸或颜色。
+- 提示文字同时是无障碍名称，写成完整的一句话。`,
+}
diff --git a/showcase/specs/textarea.ts b/showcase/specs/textarea.ts
index a29ec24..74a71b5 100644
--- a/showcase/specs/textarea.ts
+++ b/showcase/specs/textarea.ts
@@ -1,6 +1,6 @@
 import type { ComponentSpec } from '../lib/spec'
 import { h } from 'vue'
-import { Textarea } from '#/components/textarea'
+import { Textarea, textareaEngageKeys, textareaSurfaceKeys } from '#/components/textarea'
 
 const SIZES = ['default', 'sm', 'lg'] as const
 
@@ -13,16 +13,50 @@ export const textareaSpec: ComponentSpec = {
     '多行文本输入，与 Input 共享 field-edge 契约：一条内嵌发丝线，聚焦时原位换色。',
   controls: [
     { kind: 'enum', key: 'size', label: 'Size', options: SIZES, default: 'default' },
+    {
+      kind: 'enum',
+      key: 'engage',
+      label: 'Engage on',
+      options: textareaEngageKeys,
+      default: 'focus',
+      display: 'segmented',
+    },
+    {
+      kind: 'enum',
+      key: 'surface',
+      label: 'Surface',
+      options: textareaSurfaceKeys,
+      default: 'plain',
+      display: 'segmented',
+    },
     { kind: 'string', key: 'placeholder', label: 'Placeholder', default: 'Tell the bot what to do…' },
     { kind: 'number', key: 'rows', label: 'Rows', default: 3, min: 2, max: 10 },
     { kind: 'boolean', key: 'disabled', label: 'Disabled', default: false },
   ],
-  render: state =>
-    h(Textarea, {
+  render: (state) => {
+    const field = h(Textarea, {
       size: state.size as never,
+      engage: state.engage as never,
+      surface: state.surface as never,
       placeholder: String(state.placeholder),
       rows: Number(state.rows),
       disabled: Boolean(state.disabled),
       class: 'w-80',
-    }),
+    })
+    // surface only picks the edge; the tint is the caller's, so paint one here
+    // to judge that edge against.
+    return state.surface === 'brand-tint'
+      ? h('div', { class: 'rounded-lg bg-brand-soft p-3' }, [field])
+      : field
+  },
+  usage: `Like every field, a Textarea engages on FOCUS only.
+
+- engage="hover" is the single exception: it also engages under the pointer, with the same edge as focus. Use it only for an in-place editor that looks exactly like the content it replaced (a chat prompt edited inside its own bubble), where the edge is the only sign of a field.
+- Forms, dialogs and composers keep the default "focus".
+- surface="brand-tint" declares that the field is painted on a brand-tinted fill. The solid edge then comes from --field-edge-brand-tint: near-black in light, the brand in dark. The fill stays the caller's.`,
+  usageZh: `和所有输入框一样，Textarea 只在聚焦时激活。
+
+- engage="hover" 是唯一的例外：鼠标悬停时也激活，边框与聚焦时相同。只用于和被替换内容长得一模一样的原位编辑框（例如在聊天气泡里直接编辑提问），这时边框是它唯一的输入框信号。
+- 表单、对话框和输入框组件保持默认的 "focus"。
+- surface="brand-tint" 表示输入框画在品牌色底上。此时激活边框取 --field-edge-brand-tint：浅色下是近黑，深色下是品牌色。底色仍由调用方负责。`,
 }
diff --git a/src/components/info-hint/InfoHint.vue b/src/components/info-hint/InfoHint.vue
new file mode 100644
index 0000000..341a0b7
--- /dev/null
+++ b/src/components/info-hint/InfoHint.vue
@@ -0,0 +1,44 @@
+<script setup lang="ts">
+import type { InfoHintSide } from '.'
+import { Info } from 'lucide-vue-next'
+import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from '../tooltip'
+
+const props = withDefaults(defineProps<{
+  // The explanation itself: shown in the tooltip and read as the glyph's
+  // accessible name.
+  text: string
+  side?: InfoHintSide
+}>(), {
+  side: 'top',
+})
+</script>
+
+<template>
+  <!-- An ⓘ that only explains — not an action, so not a <Button>: no hover
+       chip, no pointer cursor. The glyph takes the icon ladder's text rung
+       (12px) because it sits beside text-scale labels, and stays muted. It is
+       still a tab stop so keyboard users can open the hint; its focus ring is
+       the standard --ring recipe. The tooltip opens without delay: showing the
+       hint is the glyph's whole job. -->
+  <TooltipProvider :delay-duration="0">
+    <Tooltip>
+      <TooltipTrigger as-child>
+        <span
+          data-slot="info-hint"
+          tabindex="0"
+          role="img"
+          :aria-label="props.text"
+          class="inline-flex shrink-0 cursor-default rounded-full text-muted-foreground outline-none focus-visible:ring-2 focus-visible:ring-ring/30"
+        >
+          <Info
+            class="size-3"
+            aria-hidden="true"
+          />
+        </span>
+      </TooltipTrigger>
+      <TooltipContent :side="props.side">
+        {{ props.text }}
+      </TooltipContent>
+    </Tooltip>
+  </TooltipProvider>
+</template>
diff --git a/src/components/info-hint/index.ts b/src/components/info-hint/index.ts
new file mode 100644
index 0000000..f0f7a68
--- /dev/null
+++ b/src/components/info-hint/index.ts
@@ -0,0 +1,6 @@
+import type { tooltipSideKeys } from '../tooltip'
+
+export { default as InfoHint } from './InfoHint.vue'
+
+// The hint opens through Tooltip, so its sides are Tooltip's.
+export type InfoHintSide = typeof tooltipSideKeys[number]
diff --git a/src/components/textarea/Textarea.vue b/src/components/textarea/Textarea.vue
index 0c9929c..af40e58 100644
--- a/src/components/textarea/Textarea.vue
+++ b/src/components/textarea/Textarea.vue
@@ -1,5 +1,6 @@
 <script setup lang="ts">
 import type { HTMLAttributes } from 'vue'
+import type { TextareaEngage, TextareaSurface } from '.'
 import { useVModel } from '@vueuse/core'
 import { computed } from 'vue'
 import { cn } from '#/lib/utils'
@@ -9,8 +10,20 @@ const props = withDefaults(defineProps<{
   defaultValue?: string | number
   modelValue?: string | number
   size?: 'sm' | 'default' | 'lg'
+  // When the edge engages:
+  //  - 'focus' (default): focus only — the field contract for every form field
+  //  - 'hover': hover as well as focus, for an in-place editor that wears the
+  //    exact look of the content it replaced and so has no other sign of being
+  //    a field until the pointer is on it
+  engage?: TextareaEngage
+  // The surface the field is painted on, which picks the solid edge that reads
+  // against it: 'plain' (default) or 'brand-tint' (--field-edge-brand-tint).
+  // The fill itself stays the caller's.
+  surface?: TextareaSurface
 }>(), {
   size: 'default',
+  engage: 'focus',
+  surface: 'plain',
 })
 
 const emits = defineEmits<{
@@ -34,6 +47,8 @@ const sizeClass = computed(() => ({
     v-model="modelValue"
     data-slot="textarea"
     :data-size="props.size"
+    :data-engage="props.engage === 'hover' ? 'hover' : undefined"
+    :data-surface="props.surface === 'brand-tint' ? 'brand-tint' : undefined"
     :class="cn(
       'flex field-sizing-content w-full rounded-md tracking-[0.01em] text-foreground',
       sizeClass,
diff --git a/src/components/textarea/index.ts b/src/components/textarea/index.ts
index 6a7ab2a..c83d9eb 100644
--- a/src/components/textarea/index.ts
+++ b/src/components/textarea/index.ts
@@ -1 +1,8 @@
 export { default as Textarea } from './Textarea.vue'
+
+// Single sources of truth for the engage and surface axes (see Textarea.vue);
+// consumed by the showcase spec so its controls never hand-maintain the lists.
+export const textareaEngageKeys = ['focus', 'hover'] as const
+export type TextareaEngage = typeof textareaEngageKeys[number]
+export const textareaSurfaceKeys = ['plain', 'brand-tint'] as const
+export type TextareaSurface = typeof textareaSurfaceKeys[number]
diff --git a/src/index.ts b/src/index.ts
index 86bece8..3df22d4 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -31,6 +31,7 @@ export * from './components/field/index'
 export * from './components/form/index'
 export * from './components/form-dialog-shell/index'
 export * from './components/hover-card/index'
+export * from './components/info-hint/index'
 export * from './components/inline-loading-row/index'
 export * from './components/input/index'
 export * from './components/input-group/index'
diff --git a/src/style.css b/src/style.css
index b3653e6..8a8ca73 100644
--- a/src/style.css
+++ b/src/style.css
@@ -220,6 +220,19 @@
   [data-slot="input-otp-slot"][data-active="true"] {
     --field-edge: var(--field-edge-solid);
   }
+  /* The one hover exception: Textarea engage="hover" — an in-place editor that
+     wears the exact look of the content it replaced, so the edge is its only
+     sign of being a field and the pointer gets that sign before clicking in.
+     Same edge as focus; every other field stays focus-only. Invalid still wins. */
+  [data-slot="textarea"][data-engage="hover"]:hover:not(:disabled, [aria-invalid="true"]) {
+    --field-edge: var(--field-edge-solid);
+  }
+  /* Textarea surface="brand-tint" re-binds the solid edge on the element, so
+     every state that engages solid (focus, and hover under engage="hover")
+     picks it up; rest and invalid are untouched. */
+  [data-slot="textarea"][data-surface="brand-tint"] {
+    --field-edge-solid: var(--field-edge-brand-tint);
+  }
   /* SUBTLE: the faintest deepen of the hairline — search / low-chrome, and the
      tags field. The near-black solid edge is a strong, decided signal we reserve
      for single-line fields; on a big tag container it reads as a heavy box, so
@@ -1325,10 +1338,14 @@
        --field-edge-rest     light resting hairline (lighter than the button edge)
        --field-edge-engaged  SUBTLE focus — barely deeper than rest
        --field-edge-solid    SOLID focus — the edge turns near-black in place
+       --field-edge-brand-tint  SOLID on a brand-tinted surface (Textarea
+                             surface="brand-tint"); light keeps near-black, since
+                             a brand edge muddies into a pale tint
        --field-placeholder   soft hint color — lighter/greyer than muted text */
   --field-edge-rest: oklch(0 0 0 / 0.11);
   --field-edge-engaged: oklch(0 0 0 / 0.17);
   --field-edge-solid: oklch(0 0 0 / 0.78);
+  --field-edge-brand-tint: var(--field-edge-solid);
   --field-placeholder: oklch(0.66 0.004 95);
   /* ── Accent palette ────────────────────────────────────────────────────
      Unified hue ramps for colored surfaces (menu items, tags, status,
@@ -1732,6 +1749,9 @@
   --field-edge-rest: oklch(0.318 0 0);
   --field-edge-engaged: oklch(0.42 0 0);
   --field-edge-solid: oklch(0.60 0 0);
+  /* Dark: on a deep brand tint the solid gray sinks into the fill; the brand
+     itself is the edge that lifts off it. */
+  --field-edge-brand-tint: var(--brand);
   /* Dark: segmented control labels. The thumb chip is the primary "selected"
      signal, so idle text can be fully bright. idle ≈ foreground; hover pushes
      toward white; active also uses --foreground (same as idle, chip distinguishes). */

From 7e452bacc3e50ffce4d04153a6c83faad7d255f7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E6=B8=85=E5=87=A4?= <qingf622@outlook.com>
Date: Fri, 23 Oct 2026 22:45:15 +0800
Subject: [PATCH 2/4] =?UTF-8?q?docs(ui):=20=E5=9C=A8=E7=BB=84=E4=BB=B6?=
 =?UTF-8?q?=E5=BD=92=E5=B1=9E=E7=99=BB=E8=AE=B0=20InfoHint?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Refs: MEMOH-222
---
 skills/ui-owners/SKILL.md | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/skills/ui-owners/SKILL.md b/skills/ui-owners/SKILL.md
index ff82321..edb8a1a 100644
--- a/skills/ui-owners/SKILL.md
+++ b/skills/ui-owners/SKILL.md
@@ -238,6 +238,12 @@ i18n)、`width: 'fit' | 'full'`(fit 贴合代码,聊天用;full 撑满行,对话
 式的状态开关按钮用 —— 不要再用 min-w 魔法数定宽或手写叠格量宽(grid 轨道按最宽
 label 定尺寸、靠左锚定会单侧裁字,这些坑都已收进组件,见其头注)。
 
+**InfoHint**(`@felinic/ui` 原语,非 apps/web owner,顺带登记防重造)
+只负责解释的 ⓘ:12px(图标阶梯的文字档)、灰色,悬停或键盘聚焦弹出 Tooltip(默认向上)。
+它不是按钮,点了要执行操作的用 Button;和所有 Tooltip 一样触屏看不到,关键信息不能只放在
+里面。Props: `text`(同时是无障碍名称,写成完整句子)、`side?`。不要再手写 `Info` 图标 +
+TooltipTrigger,也不要在调用处改它的尺寸或颜色。
+
 **MetricReadout** · `settings/metric-readout.vue`
 One metric tile: caption label + tabular value (or a status dot + label). Props: `label`,
 `value`, `sub`, `framed` (default `true` — draws the tile box; `false` for a bare stat on
@@ -426,6 +432,7 @@ An error / warning / info notice?               → CalloutBanner (bare inside a
 A device-code "enter this code" moment?         → DeviceCodePanel
 Read-only code / a command to copy?             → CodePanel
 A label that swaps with state (Connect↔Cancel)? → LabelSwap (@felinic/ui)
+A ⓘ that only explains something nearby?       → InfoHint (@felinic/ui)
 The page frame itself?                          → PageShell
 A pane with nothing to show (loading/empty)?    → PanePlaceholder (centered fill)
 An in-flow loading row (spinner + text)?        → InlineLoadingRow

From 14eb576fd95c959f0052296e0bd835eeec9a687e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E6=B8=85=E5=87=A4?= <qingf622@outlook.com>
Date: Tue, 27 Oct 2026 21:31:54 -0700
Subject: [PATCH 3/4] =?UTF-8?q?feat(ui):=20Textarea=20=E4=BB=A5=20rest=3D"?=
 =?UTF-8?q?bare"=20=E5=8F=96=E4=BB=A3=E6=82=AC=E5=81=9C=E6=8F=8F=E8=BE=B9?=
 =?UTF-8?q?=EF=BC=8C=E5=8E=9F=E4=BD=8D=E7=BC=96=E8=BE=91=E6=9C=AA=E8=81=9A?=
 =?UTF-8?q?=E7=84=A6=E6=97=B6=E4=B8=8D=E6=98=BE=E7=A4=BA=E8=BE=B9=E6=A1=86?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 AGENTS.md                            |  9 ++++-----
 showcase/specs/textarea.ts           | 20 ++++++++++----------
 src/components/textarea/Textarea.vue | 17 ++++++++---------
 src/components/textarea/index.ts     |  6 +++---
 src/style.css                        | 14 ++++++--------
 5 files changed, 31 insertions(+), 35 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index ae64a11..461df60 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -379,11 +379,10 @@ peers", not "one door to somewhere else".
   hairline whose color swaps per state (never an outer ring):
   `--field-edge-rest` → `--field-edge-solid` (focus) / `--field-edge-engaged`
   (subtle) / `--destructive` (invalid).
-  - The one exception is opt-in: `<Textarea engage="hover">` also engages under
-    the pointer, with the same `--field-edge-solid`. It is for an in-place
-    editor that wears the exact look of the content it replaced (the chat
-    prompt edited inside its own bubble) — the edge is its only sign of being a
-    field. Forms and ordinary fields never use it.
+  - An in-place editor that must render exactly like the content it replaced
+    (the chat prompt edited inside its own bubble) drops the resting hairline
+    with `<Textarea rest="bare">`; focus and invalid still draw the edge. Forms
+    and ordinary fields keep the default `rest="edge"`.
   - A Textarea painted on a brand-tinted surface (that same bubble) declares it
     with `surface="brand-tint"`: its solid edge becomes `--field-edge-brand-tint`
     — the neutral near-black in light (a brand edge muddies into a pale tint),
diff --git a/showcase/specs/textarea.ts b/showcase/specs/textarea.ts
index 74a71b5..8bb7259 100644
--- a/showcase/specs/textarea.ts
+++ b/showcase/specs/textarea.ts
@@ -1,6 +1,6 @@
 import type { ComponentSpec } from '../lib/spec'
 import { h } from 'vue'
-import { Textarea, textareaEngageKeys, textareaSurfaceKeys } from '#/components/textarea'
+import { Textarea, textareaRestKeys, textareaSurfaceKeys } from '#/components/textarea'
 
 const SIZES = ['default', 'sm', 'lg'] as const
 
@@ -15,10 +15,10 @@ export const textareaSpec: ComponentSpec = {
     { kind: 'enum', key: 'size', label: 'Size', options: SIZES, default: 'default' },
     {
       kind: 'enum',
-      key: 'engage',
-      label: 'Engage on',
-      options: textareaEngageKeys,
-      default: 'focus',
+      key: 'rest',
+      label: 'At rest',
+      options: textareaRestKeys,
+      default: 'edge',
       display: 'segmented',
     },
     {
@@ -36,7 +36,7 @@ export const textareaSpec: ComponentSpec = {
   render: (state) => {
     const field = h(Textarea, {
       size: state.size as never,
-      engage: state.engage as never,
+      rest: state.rest as never,
       surface: state.surface as never,
       placeholder: String(state.placeholder),
       rows: Number(state.rows),
@@ -51,12 +51,12 @@ export const textareaSpec: ComponentSpec = {
   },
   usage: `Like every field, a Textarea engages on FOCUS only.
 
-- engage="hover" is the single exception: it also engages under the pointer, with the same edge as focus. Use it only for an in-place editor that looks exactly like the content it replaced (a chat prompt edited inside its own bubble), where the edge is the only sign of a field.
-- Forms, dialogs and composers keep the default "focus".
+- rest="bare" drops the resting hairline, so the field renders exactly like the content it replaced until it is focused. Use it only for an in-place editor (a chat prompt edited inside its own bubble).
+- Forms, dialogs and composers keep the default "edge".
 - surface="brand-tint" declares that the field is painted on a brand-tinted fill. The solid edge then comes from --field-edge-brand-tint: near-black in light, the brand in dark. The fill stays the caller's.`,
   usageZh: `和所有输入框一样，Textarea 只在聚焦时激活。
 
-- engage="hover" 是唯一的例外：鼠标悬停时也激活，边框与聚焦时相同。只用于和被替换内容长得一模一样的原位编辑框（例如在聊天气泡里直接编辑提问），这时边框是它唯一的输入框信号。
-- 表单、对话框和输入框组件保持默认的 "focus"。
+- rest="bare" 去掉未聚焦时的细边，聚焦前和被替换的内容渲染得完全一样。只用于原位编辑框（例如在聊天气泡里直接编辑提问）。
+- 表单、对话框和输入框组件保持默认的 "edge"。
 - surface="brand-tint" 表示输入框画在品牌色底上。此时激活边框取 --field-edge-brand-tint：浅色下是近黑，深色下是品牌色。底色仍由调用方负责。`,
 }
diff --git a/src/components/textarea/Textarea.vue b/src/components/textarea/Textarea.vue
index af40e58..8676370 100644
--- a/src/components/textarea/Textarea.vue
+++ b/src/components/textarea/Textarea.vue
@@ -1,6 +1,6 @@
 <script setup lang="ts">
 import type { HTMLAttributes } from 'vue'
-import type { TextareaEngage, TextareaSurface } from '.'
+import type { TextareaRest, TextareaSurface } from '.'
 import { useVModel } from '@vueuse/core'
 import { computed } from 'vue'
 import { cn } from '#/lib/utils'
@@ -10,19 +10,18 @@ const props = withDefaults(defineProps<{
   defaultValue?: string | number
   modelValue?: string | number
   size?: 'sm' | 'default' | 'lg'
-  // When the edge engages:
-  //  - 'focus' (default): focus only — the field contract for every form field
-  //  - 'hover': hover as well as focus, for an in-place editor that wears the
-  //    exact look of the content it replaced and so has no other sign of being
-  //    a field until the pointer is on it
-  engage?: TextareaEngage
+  // The edge while the field is not focused:
+  //  - 'edge' (default): the resting hairline every form field wears
+  //  - 'bare': no edge, so an in-place editor renders exactly like the content
+  //    it replaced until it is focused; focus and invalid still draw the edge
+  rest?: TextareaRest
   // The surface the field is painted on, which picks the solid edge that reads
   // against it: 'plain' (default) or 'brand-tint' (--field-edge-brand-tint).
   // The fill itself stays the caller's.
   surface?: TextareaSurface
 }>(), {
   size: 'default',
-  engage: 'focus',
+  rest: 'edge',
   surface: 'plain',
 })
 
@@ -47,7 +46,7 @@ const sizeClass = computed(() => ({
     v-model="modelValue"
     data-slot="textarea"
     :data-size="props.size"
-    :data-engage="props.engage === 'hover' ? 'hover' : undefined"
+    :data-rest="props.rest === 'bare' ? 'bare' : undefined"
     :data-surface="props.surface === 'brand-tint' ? 'brand-tint' : undefined"
     :class="cn(
       'flex field-sizing-content w-full rounded-md tracking-[0.01em] text-foreground',
diff --git a/src/components/textarea/index.ts b/src/components/textarea/index.ts
index c83d9eb..eefbdb8 100644
--- a/src/components/textarea/index.ts
+++ b/src/components/textarea/index.ts
@@ -1,8 +1,8 @@
 export { default as Textarea } from './Textarea.vue'
 
-// Single sources of truth for the engage and surface axes (see Textarea.vue);
+// Single sources of truth for the rest and surface axes (see Textarea.vue);
 // consumed by the showcase spec so its controls never hand-maintain the lists.
-export const textareaEngageKeys = ['focus', 'hover'] as const
-export type TextareaEngage = typeof textareaEngageKeys[number]
+export const textareaRestKeys = ['edge', 'bare'] as const
+export type TextareaRest = typeof textareaRestKeys[number]
 export const textareaSurfaceKeys = ['plain', 'brand-tint'] as const
 export type TextareaSurface = typeof textareaSurfaceKeys[number]
diff --git a/src/style.css b/src/style.css
index 8a8ca73..744f113 100644
--- a/src/style.css
+++ b/src/style.css
@@ -220,16 +220,14 @@
   [data-slot="input-otp-slot"][data-active="true"] {
     --field-edge: var(--field-edge-solid);
   }
-  /* The one hover exception: Textarea engage="hover" — an in-place editor that
-     wears the exact look of the content it replaced, so the edge is its only
-     sign of being a field and the pointer gets that sign before clicking in.
-     Same edge as focus; every other field stays focus-only. Invalid still wins. */
-  [data-slot="textarea"][data-engage="hover"]:hover:not(:disabled, [aria-invalid="true"]) {
-    --field-edge: var(--field-edge-solid);
+  /* Textarea rest="bare": no resting hairline, so an in-place editor renders
+     exactly like the content it replaced while unfocused. Only the rest color
+     is re-bound; focus and invalid still swap in their edges. */
+  [data-slot="textarea"][data-rest="bare"] {
+    --field-edge-rest: transparent;
   }
   /* Textarea surface="brand-tint" re-binds the solid edge on the element, so
-     every state that engages solid (focus, and hover under engage="hover")
-     picks it up; rest and invalid are untouched. */
+     focus picks it up; rest and invalid are untouched. */
   [data-slot="textarea"][data-surface="brand-tint"] {
     --field-edge-solid: var(--field-edge-brand-tint);
   }

From 637a3115121575abb504d15d859f384847bcba86 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E6=B8=85=E5=87=A4?= <qingf622@outlook.com>
Date: Tue, 27 Oct 2026 21:37:19 -0700
Subject: [PATCH 4/4] =?UTF-8?q?fix(ui):=20InfoHint=20=E6=94=AF=E6=8C=81?=
 =?UTF-8?q?=E8=A7=A6=E5=B1=8F=E8=BD=BB=E7=82=B9=E6=89=93=E5=BC=80=EF=BC=8C?=
 =?UTF-8?q?=E5=9B=BE=E6=A0=87=E6=94=B9=E4=B8=BA=2014px=20=E5=B9=B6?=
 =?UTF-8?q?=E6=89=A9=E5=A4=A7=E8=A7=A6=E6=8E=A7=E5=8C=BA=E5=9F=9F?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 AGENTS.md                             | 12 ++++----
 showcase/specs/info-hint.ts           | 12 ++++----
 skills/ui-owners/SKILL.md             |  6 ++--
 src/components/info-hint/InfoHint.vue | 41 +++++++++++++++++++++------
 4 files changed, 49 insertions(+), 22 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 461df60..06744c3 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -228,11 +228,13 @@ prose use `variant="link"`; for a control-sized action use a normal `<Button>`.
 
 A glyph whose whole job is to reveal a short explanation is NOT an action, so it
 is not an icon `<Button>` (no hover chip, no pointer cursor) and not a
-hand-rolled span. `<InfoHint>` is a muted 12px Info glyph (the text rung of the
-icon ladder — it sits beside text-scale labels) that opens a Tooltip on hover or
-keyboard focus, upward by default (`side`). The text doubles as the glyph's
-accessible name. Tooltip rules still apply: supplementary information only, as
-it is unreachable on touch.
+hand-rolled span. `<InfoHint>` is a muted 14px Info glyph that opens a Tooltip
+on hover, keyboard focus or a tap, upward by default (`side`). It sits one rung
+above the 12px text rung on purpose: a thin outline circle reads smaller than
+solid text of the same height, so it is sized to look level with the label
+beside it, not to match its cap height. Its hit area is widened to 26px for
+touch. The text doubles as the glyph's accessible name. Tooltip rules still
+apply: supplementary information only.
 
 ### "A card that DOES something / goes somewhere" = `<ActionCard>`
 
diff --git a/showcase/specs/info-hint.ts b/showcase/specs/info-hint.ts
index 1803f44..93fd046 100644
--- a/showcase/specs/info-hint.ts
+++ b/showcase/specs/info-hint.ts
@@ -9,9 +9,9 @@ export const infoHintSpec: ComponentSpec = {
   name: 'InfoHint',
   interactive: true,
   description:
-    'A muted ⓘ glyph that only explains: hover or keyboard focus opens a short Tooltip. Not an action, so not a button.',
+    'A muted ⓘ glyph that only explains: hover, keyboard focus or a tap opens a short Tooltip. Not an action, so not a button.',
   descriptionZh:
-    '只负责解释的灰色 ⓘ 图标：悬停或键盘聚焦时弹出简短的 Tooltip。它不是操作，所以不是按钮。',
+    '只负责解释的灰色 ⓘ 图标：悬停、键盘聚焦或轻点时弹出简短的 Tooltip。它不是操作，所以不是按钮。',
   controls: [
     { kind: 'enum', key: 'side', label: 'Side', options: tooltipSideKeys, default: 'top', display: 'segmented' },
     {
@@ -35,14 +35,14 @@ export const infoHintSpec: ComponentSpec = {
     },
   ],
   render: state => h(InfoHint, { text: String(state.text), side: state.side as never }),
-  usage: `InfoHint carries supplementary explanation only — like any Tooltip it is unreachable on touch, so nothing essential may live only inside it.
+  usage: `InfoHint carries supplementary explanation only — a reader has to go looking for it, so nothing essential may live only inside it.
 
 - Use it when a glyph's whole job is to explain. If clicking should DO something, that is a Button.
-- The glyph is 12px (the icon ladder's text rung) and muted; do not resize or recolor it per call site.
+- The glyph is 14px and muted — one rung above the text rung, because a thin outline circle looks smaller than text of the same height. Do not resize or recolor it per call site.
 - The text is also the accessible name — write it as a full sentence.`,
-  usageZh: `InfoHint 只放补充说明——和所有 Tooltip 一样，触屏上看不到，所以关键信息绝不能只放在里面。
+  usageZh: `InfoHint 只放补充说明——读者得主动去看才能看到，所以关键信息绝不能只放在里面。
 
 - 图标的唯一作用是解释时用它；点了要执行操作的，应该用 Button。
-- 图标固定 12px（图标尺寸阶梯的文字档）、灰色；不要在调用处改尺寸或颜色。
+- 图标固定 14px、灰色——比文字档高一档，因为细线圆圈在同样高度下看起来比文字小。不要在调用处改尺寸或颜色。
 - 提示文字同时是无障碍名称，写成完整的一句话。`,
 }
diff --git a/skills/ui-owners/SKILL.md b/skills/ui-owners/SKILL.md
index edb8a1a..9406647 100644
--- a/skills/ui-owners/SKILL.md
+++ b/skills/ui-owners/SKILL.md
@@ -239,9 +239,9 @@ i18n)、`width: 'fit' | 'full'`(fit 贴合代码,聊天用;full 撑满行,对话
 label 定尺寸、靠左锚定会单侧裁字,这些坑都已收进组件,见其头注)。
 
 **InfoHint**(`@felinic/ui` 原语,非 apps/web owner,顺带登记防重造)
-只负责解释的 ⓘ:12px(图标阶梯的文字档)、灰色,悬停或键盘聚焦弹出 Tooltip(默认向上)。
-它不是按钮,点了要执行操作的用 Button;和所有 Tooltip 一样触屏看不到,关键信息不能只放在
-里面。Props: `text`(同时是无障碍名称,写成完整句子)、`side?`。不要再手写 `Info` 图标 +
+只负责解释的 ⓘ:14px(比文字档高一档,细线圆圈同高时显小)、灰色,悬停、键盘聚焦或轻点
+弹出 Tooltip(默认向上)。它不是按钮,点了要执行操作的用 Button;读者得主动去看,关键信息
+不能只放在里面。Props: `text`(同时是无障碍名称,写成完整句子)、`side?`。不要再手写 `Info` 图标 +
 TooltipTrigger,也不要在调用处改它的尺寸或颜色。
 
 **MetricReadout** · `settings/metric-readout.vue`
diff --git a/src/components/info-hint/InfoHint.vue b/src/components/info-hint/InfoHint.vue
index 341a0b7..71340cd 100644
--- a/src/components/info-hint/InfoHint.vue
+++ b/src/components/info-hint/InfoHint.vue
@@ -1,6 +1,7 @@
 <script setup lang="ts">
 import type { InfoHintSide } from '.'
 import { Info } from 'lucide-vue-next'
+import { ref } from 'vue'
 import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from '../tooltip'
 
 const props = withDefaults(defineProps<{
@@ -11,27 +12,51 @@ const props = withDefaults(defineProps<{
 }>(), {
   side: 'top',
 })
+
+const open = ref(false)
+// The Tooltip opens on hover and keyboard focus but ignores touch (it skips
+// touch pointermove and closes on every trigger press), so a tap toggles it
+// here. pointerdown records how the following click was made; a mouse click
+// leaves the hover-driven state alone.
+let pointerType = ''
+function onPointerDown(event: PointerEvent) {
+  pointerType = event.pointerType
+}
+function onClick() {
+  if (pointerType === 'touch' || pointerType === 'pen') open.value = !open.value
+}
 </script>
 
 <template>
   <!-- An ⓘ that only explains — not an action, so not a <Button>: no hover
-       chip, no pointer cursor. The glyph takes the icon ladder's text rung
-       (12px) because it sits beside text-scale labels, and stays muted. It is
-       still a tab stop so keyboard users can open the hint; its focus ring is
-       the standard --ring recipe. The tooltip opens without delay: showing the
-       hint is the glyph's whole job. -->
+       chip, no pointer cursor. The glyph takes the icon ladder's 14px rung:
+       a thin, muted outline circle reads smaller than solid text of the same
+       height, so it sits one notch above the label's cap height to look level
+       with it. It is still a tab stop so keyboard users can open the hint; its
+       focus ring is the standard --ring recipe. The tooltip opens without
+       delay: showing the hint is the glyph's whole job. The trigger keeps the
+       tooltip open on press (disable-closing-trigger) so the tap toggle above
+       is the only thing a tap does; a tap elsewhere, blur or scroll closes it.
+       The ::after widens the hit area by 6px each side, to 26px — past the
+       24px minimum target — without moving the glyph; 6px is also the
+       action-row gap, so it never reaches into a neighbouring button. -->
   <TooltipProvider :delay-duration="0">
-    <Tooltip>
+    <Tooltip
+      v-model:open="open"
+      disable-closing-trigger
+    >
       <TooltipTrigger as-child>
         <span
           data-slot="info-hint"
           tabindex="0"
           role="img"
           :aria-label="props.text"
-          class="inline-flex shrink-0 cursor-default rounded-full text-muted-foreground outline-none focus-visible:ring-2 focus-visible:ring-ring/30"
+          class="relative inline-flex shrink-0 cursor-default rounded-full text-muted-foreground outline-none after:absolute after:-inset-1.5 after:content-[''] focus-visible:ring-2 focus-visible:ring-ring/30"
+          @pointerdown="onPointerDown"
+          @click="onClick"
         >
           <Info
-            class="size-3"
+            class="size-3.5"
             aria-hidden="true"
           />
         </span>