iter(g237): 新增 kbd 键盘按键标记，键帽样式支持单键与组合键（74 组件）

.ua/index.json

@@ -1,6 +1,6 @@
 {
   "$schema": "ui-arch-registry-index/0.1",
-  "generatedAt": "2026-10-26T13:28:41.290Z",
+  "generatedAt": "2026-10-26T13:30:37.089Z",
   "repoRoot": ".",
   "packages": [
     {
@@ -216,7 +216,8 @@
           "timePicker(props)：时间选择，时 / 分两列弹层，value 信号双向绑定 HH:mm，分钟可配步长，Esc 收起",
           "pinInput(props)：验证码输入，N 格单字符数字输入，输入自动进格、退格回删、方向键移格、粘贴自动分发，value 信号双向绑定，mask 可密文显示",
           "copyButton(props)：复制按钮，点击把 text 写入剪贴板并短暂显示已复制，text 可传函数取实时值，clipboard API 不可用时降级 execCommand",
-          "countdown(props)：倒计时，秒级递减到 0 自动停表并触发 onFinish，缺省 mm:ss 展示，返回句柄 start/stop/reset"
+          "countdown(props)：倒计时，秒级递减到 0 自动停表并触发 onFinish，缺省 mm:ss 展示，返回句柄 start/stop/reset",
+          "kbd(props)：键盘按键标记，键帽样式展示单个按键或组合键（多键以 + 连接），用于快捷键提示"
         ],
         "keyTypes": [
           "ButtonProps",
@@ -3975,6 +3976,25 @@
               "归零自动停表并触发 onFinish；之后 start() 会重开一轮，reset() 复位到总时长",
               "format 自定义展示：如只显示秒 (s) => `${s}s`，或带上小时位"
             ]
+          },
+          {
+            "id": "kbd",
+            "title": "键盘按键 Kbd",
+            "demo": "sec-kbd",
+            "props": [
+              {
+                "n": "keys",
+                "t": "string | string[]",
+                "r": 1,
+                "d": "按键内容：单键字符串或多键组合数组（组合以 + 连接展示）"
+              }
+            ],
+            "example": "kbd({ keys: 'Esc' })、kbd({ keys: ['Ctrl', 'K'] })",
+            "steps": [
+              "传字符串展示单键帽：kbd({ keys: \"Esc\" })，适合文档里说明单个按键",
+              "传数组展示组合键：kbd({ keys: [\"Ctrl\", \"K\"] })，键帽之间以弱化的 + 连接（+ 对读屏隐藏）",
+              "常与提示文案混排：行内 baseline 对齐，键帽底边加厚一线出立体感"
+            ]
           }
         ]
       },

AGENTS.md

@@ -21,7 +21,7 @@
 
 - `packages/core/table-core`（@ui-arch/table-core）：Headless 表格逻辑内核
 - `packages/core/frame`（@ui-arch/frame）：signal + hyperscript 微框架
-- `packages/skin/ui`（@ui-arch/ui）：73 个 DOM 组件（表单 / 反馈 / 浮层 / 导航 / 表格），样式只消费令牌
+- `packages/skin/ui`（@ui-arch/ui）：74 个 DOM 组件（表单 / 反馈 / 浮层 / 导航 / 表格），样式只消费令牌
 - `packages/design/tokens`（@ui-arch/tokens）：设计令牌
 - `packages/tools/cli`（@ui-arch/cli）：`ua` 命令行 + MCP 注册表服务（private）
 - `apps/demo`（@ui-arch/demo）：交互演示，产物 apps/demo/dist/demo.html

ARCHITECTURE.md

@@ -34,7 +34,7 @@ ui-arch-mvp/
 │   │   ├── table-core/       # 表格状态内核
 │   │   └── frame/            # 信号 + hyperscript 微框架
 │   ├── skin/                 # 皮肤层（DOM 组件，可发布）
-│   │   └── ui/               # 73 个组件 + ui.css
+│   │   └── ui/               # 74 个组件 + ui.css
 │   ├── design/               # 资产层（可发布）
 │   │   └── tokens/           # --ua-* 设计令牌
 │   └── tools/                # 工程层（private，不发布）

README.md

@@ -12,13 +12,13 @@ npm run docs            # 生成人类文档站 apps/docs/index.html + Agent 全
 npm run changelog       # 依据 git 提交史重写 CHANGELOG.md（发版前跑；changelog:check 可查漂移）
 ```
 
-## 组件（共 73 个）
+## 组件（共 74 个）
 
 <!-- ua:components -->
-accordion · affix · alert · anchor · autoComplete · avatar · avatarGroup · backTop · badge · breadcrumb · button · calendar · carousel · card · cascader · checkbox · checkboxGroup · colorPicker · commandPalette · copyButton · countdown · dataTable · datePicker · descriptions · divider · drawer · empty · floatButton · form · grid · image · inputNumber · link · list · menu · modal · mentions · multiSelect · notification · pagination · pinInput · popover · popconfirm · progress · radioGroup · rate · result · segmented · select · skeleton · slider · space · spinner · splitter · statistic · stepper · switchButton · tabs · tag · textField · textarea · timeline · timePicker · toast · tooltip · tour · transfer · tree · treeSelect · typography · upload · virtualList · watermark
+accordion · affix · alert · anchor · autoComplete · avatar · avatarGroup · backTop · badge · breadcrumb · button · calendar · carousel · card · cascader · checkbox · checkboxGroup · colorPicker · commandPalette · copyButton · countdown · kbd · dataTable · datePicker · descriptions · divider · drawer · empty · floatButton · form · grid · image · inputNumber · link · list · menu · modal · mentions · multiSelect · notification · pagination · pinInput · popover · popconfirm · progress · radioGroup · rate · result · segmented · select · skeleton · slider · space · spinner · splitter · statistic · stepper · switchButton · tabs · tag · textField · textarea · timeline · timePicker · toast · tooltip · tour · transfer · tree · treeSelect · typography · upload · virtualList · watermark
 <!-- /ua:components -->
 
-分组：表单（button / copyButton / textField / inputNumber / textarea / checkbox / checkboxGroup / colorPicker / switchButton / select / mentions / multiSelect / radioGroup / slider / rate / autoComplete / datePicker / timePicker / pinInput / segmented / upload / form + formItem / transfer / cascader）、反馈（alert / toast / notification / result / spinner / progress / skeleton / badge / empty / statistic / countdown）、浮层（tooltip / popover / popconfirm / modal / drawer / menu / commandPalette）、导航（tabs / breadcrumb / pagination / accordion / stepper / tree / treeSelect / anchor）、数据展示（dataTable / descriptions / card / list / timeline / tag / avatar / avatarGroup / image / carousel / calendar / typography / virtualList）、其他（floatButton / grid / link / space / divider / splitter / backTop / affix / tour / watermark）。
+分组：表单（button / copyButton / textField / inputNumber / textarea / checkbox / checkboxGroup / colorPicker / switchButton / select / mentions / multiSelect / radioGroup / slider / rate / autoComplete / datePicker / timePicker / pinInput / segmented / upload / form + formItem / transfer / cascader）、反馈（alert / toast / notification / result / spinner / progress / skeleton / badge / empty / statistic / countdown）、浮层（tooltip / popover / popconfirm / modal / drawer / menu / commandPalette）、导航（tabs / breadcrumb / pagination / accordion / stepper / tree / treeSelect / anchor）、数据展示（dataTable / descriptions / card / list / kbd / timeline / tag / avatar / avatarGroup / image / carousel / calendar / typography / virtualList）、其他（floatButton / grid / link / space / divider / splitter / backTop / affix / tour / watermark）。
 
 ## 可访问性约定
 
@@ -32,7 +32,7 @@ accordion · affix · alert · anchor · autoComplete · avatar · avatarGroup
 |---|---|
 | `packages/core/frame` | @ui-arch/frame：signal / computed / effect + hyperscript（无虚拟 DOM） |
 | `packages/core/table-core` | @ui-arch/table-core：headless 表格（filter → sort → paginate 派生管线） |
-| `packages/skin/ui` | @ui-arch/ui：73 个 DOM 组件 + ui.css（只消费 `--ua-*` 令牌） |
+| `packages/skin/ui` | @ui-arch/ui：74 个 DOM 组件 + ui.css（只消费 `--ua-*` 令牌） |
 | `packages/design/tokens` | @ui-arch/tokens：设计令牌（暗色只换值不换名） |
 | `packages/tools/cli` | @ui-arch/cli：`ua` 命令行与 stdio MCP server |
 | `apps/demo` | 交互演示（esbuild 打包成单文件） |

apps/demo/main.ts

@@ -30,6 +30,7 @@ import {
   copyButton,
   countdown,
   dataTable,
+  kbd,
   datePicker,
   transfer,
   descriptions,
@@ -1121,6 +1122,19 @@ const content = h(
       h('span', { class: 'out' }, '第二个示例初始暂停，点按钮重开'),
     ),
   ),
+  section(
+    'sec-kbd',
+    '键盘按键',
+    'kbd：键帽样式展示按键提示，单键直传字符串，组合键传数组以 + 连接（+ 对读屏隐藏）。',
+    h(
+      'div',
+      { class: 'row' },
+      kbd({ keys: 'Esc' }),
+      kbd({ keys: ['Ctrl', 'K'] }),
+      kbd({ keys: ['Shift', 'Enter'] }),
+      h('span', { class: 'out' }, '按 ', kbd({ keys: ['Ctrl', 'K'] }), ' 唤起演示页命令面板'),
+    ),
+  ),
   section(
     'sec-affix',
     '固钉',

llms-full.txt

@@ -1,6 +1,6 @@
 # @ui-arch 组件库 Agent 文档（无图形版）
 
-> 自动生成于 2026-10-26T13:28:41.290Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。
+> 自动生成于 2026-10-26T13:30:37.089Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。
 > 组件 = 普通函数，传 props 返回 DOM；状态用 signal 双向绑定：读 signal() 写 signal(v)。
 
 ## 快速上手
@@ -2097,6 +2097,26 @@ const cd = countdown({ seconds: 60, onFinish: () => console.log('结束') }); //
 
 现场演示：apps/docs/demo.html#sec-countdown
 
+### kbd — 键盘按键 Kbd
+
+参数：
+
+- keys（必填）：string | string[] —— 按键内容：单键字符串或多键组合数组（组合以 + 连接展示）
+
+示例：
+
+```
+kbd({ keys: 'Esc' })、kbd({ keys: ['Ctrl', 'K'] })
+```
+
+手把手：
+
+1. 传字符串展示单键帽：kbd({ keys: "Esc" })，适合文档里说明单个按键
+2. 传数组展示组合键：kbd({ keys: ["Ctrl", "K"] })，键帽之间以弱化的 + 连接（+ 对读屏隐藏）
+3. 常与提示文案混排：行内 baseline 对齐，键帽底边加厚一线出立体感
+
+现场演示：apps/docs/demo.html#sec-kbd
+
 API 速览：
 
 - button(props)：按钮，variant = primary | ghost | danger，disabled 支持布尔或信号禁用；type 缺省 button（表单内不隐式提交）
@@ -2174,6 +2194,7 @@ API 速览：
 - pinInput(props)：验证码输入，N 格单字符数字输入，输入自动进格、退格回删、方向键移格、粘贴自动分发，value 信号双向绑定，mask 可密文显示
 - copyButton(props)：复制按钮，点击把 text 写入剪贴板并短暂显示已复制，text 可传函数取实时值，clipboard API 不可用时降级 execCommand
 - countdown(props)：倒计时，秒级递减到 0 自动停表并触发 onFinish，缺省 mm:ss 展示，返回句柄 start/stop/reset
+- kbd(props)：键盘按键标记，键帽样式展示单个按键或组合键（多键以 + 连接），用于快捷键提示
 
 一行用法：
 

llms.txt

@@ -122,6 +122,7 @@
   - pinInput(props)：验证码输入，N 格单字符数字输入，输入自动进格、退格回删、方向键移格、粘贴自动分发，value 信号双向绑定，mask 可密文显示
   - copyButton(props)：复制按钮，点击把 text 写入剪贴板并短暂显示已复制，text 可传函数取实时值，clipboard API 不可用时降级 execCommand
   - countdown(props)：倒计时，秒级递减到 0 自动停表并触发 onFinish，缺省 mm:ss 展示，返回句柄 start/stop/reset
+  - kbd(props)：键盘按键标记，键帽样式展示单个按键或组合键（多键以 + 连接），用于快捷键提示
 - 用法: `const checked = signal(false); checkbox({ label: '同意', checked }); const open = signal(false); modal({ title: '确认', open }, '内容')`
 - 约定: 皮肤不持有业务状态，一律委托 headless 内核或调用方信号
 - 约定: 表单类组件统一约定：*Props.value/checked/active 为 Signal 双向绑定，onChange/onInput 为回调

packages/skin/ui/src/index.ts

@@ -73,3 +73,4 @@ export { timePicker } from './timePicker.js';
 export { pinInput } from './pinInput.js';
 export { copyButton } from './copyButton.js';
 export { countdown } from './countdown.js';
+export { kbd } from './kbd.js';

packages/skin/ui/src/kbd.ts

@@ -0,0 +1,10 @@
+import { h } from '@ui-arch/frame';
+import type { KbdProps } from './types.js';
+
+/*** 键盘按键标记：键帽样式展示单个按键或组合键（多键以 + 连接），用于快捷键提示 ***/
+export function kbd(props: KbdProps): HTMLElement {
+  const keys = Array.isArray(props.keys) ? props.keys : [props.keys]; // 统一成数组：单键 / 组合键同一渲染路径
+  const parts: (Node | null)[] = keys.map((k, i) => (i > 0 ? h('span', { class: 'ua-kbd-sep', 'aria-hidden': 'true' }, '+') : null)); // 分隔符占位
+  keys.forEach((k, i) => parts[i * 2 + 1] = h('kbd', { class: 'ua-kbd-key' }, k)); // 键帽交错插入：sep, key, sep, key…
+  return h('span', { class: 'ua-kbd' }, ...parts);
+}

packages/skin/ui/src/types.ts

@@ -281,6 +281,11 @@ export interface CountdownHandle {
   reset: () => void;    // 复位到总时长并停表
 }
 
+/*** 键盘按键入参 ***/
+export interface KbdProps {
+  keys: string | string[]; // 按键内容：单键字符串或多键组合数组（组合以 + 连接展示）
+}
+
 /*** 空状态入参 ***/
 export interface EmptyProps {
   title?: string;       // 主标题；缺省不渲染

packages/skin/ui/ua.manifest.json

@@ -87,7 +87,8 @@
       "timePicker(props)：时间选择，时 / 分两列弹层，value 信号双向绑定 HH:mm，分钟可配步长，Esc 收起",
       "pinInput(props)：验证码输入，N 格单字符数字输入，输入自动进格、退格回删、方向键移格、粘贴自动分发，value 信号双向绑定，mask 可密文显示",
       "copyButton(props)：复制按钮，点击把 text 写入剪贴板并短暂显示已复制，text 可传函数取实时值，clipboard API 不可用时降级 execCommand",
-      "countdown(props)：倒计时，秒级递减到 0 自动停表并触发 onFinish，缺省 mm:ss 展示，返回句柄 start/stop/reset"
+      "countdown(props)：倒计时，秒级递减到 0 自动停表并触发 onFinish，缺省 mm:ss 展示，返回句柄 start/stop/reset",
+      "kbd(props)：键盘按键标记，键帽样式展示单个按键或组合键（多键以 + 连接），用于快捷键提示"
     ],
     "keyTypes": [
       "ButtonProps",
@@ -3846,6 +3847,25 @@
           "归零自动停表并触发 onFinish；之后 start() 会重开一轮，reset() 复位到总时长",
           "format 自定义展示：如只显示秒 (s) => `${s}s`，或带上小时位"
         ]
+      },
+      {
+        "id": "kbd",
+        "title": "键盘按键 Kbd",
+        "demo": "sec-kbd",
+        "props": [
+          {
+            "n": "keys",
+            "t": "string | string[]",
+            "r": 1,
+            "d": "按键内容：单键字符串或多键组合数组（组合以 + 连接展示）"
+          }
+        ],
+        "example": "kbd({ keys: 'Esc' })、kbd({ keys: ['Ctrl', 'K'] })",
+        "steps": [
+          "传字符串展示单键帽：kbd({ keys: \"Esc\" })，适合文档里说明单个按键",
+          "传数组展示组合键：kbd({ keys: [\"Ctrl\", \"K\"] })，键帽之间以弱化的 + 连接（+ 对读屏隐藏）",
+          "常与提示文案混排：行内 baseline 对齐，键帽底边加厚一线出立体感"
+        ]
       }
     ]
   }

packages/skin/ui/ui.css

@@ -5202,3 +5202,30 @@ h5.ua-type-title { font-size: var(--ua-font-size-md); }
 .ua-countdown {
   font-variant-numeric: tabular-nums; /* 数字等宽：秒跳不抖动 */
 }
+
+/* ---- 键盘按键标记（kbd） ---- */
+.ua-kbd {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--ua-space-05);
+  vertical-align: middle;
+}
+.ua-kbd-key {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-width: var(--ua-control-h-sm);
+  height: var(--ua-control-h-sm);
+  padding: 0 var(--ua-space-15);
+  border: 1px solid var(--ua-color-border);
+  border-bottom-width: 2px; /* 底边加厚一线：键帽立体感 */
+  border-radius: var(--ua-radius-sm);
+  background: var(--ua-color-surface);
+  color: var(--ua-color-text);
+  font-size: var(--ua-font-size-sm);
+  line-height: var(--ua-leading-none);
+}
+.ua-kbd-sep {
+  color: var(--ua-color-text-muted);
+  font-size: var(--ua-font-size-xs);
+}