别再让 AI 手搓下拉框了:Vercel 开源 UI SDK 实测,键盘、焦点、ARIA 全部内置
AI 写 UI,总差最后一步
让 AI 写页面,速度早就不是问题——一句「帮我做个搜索框」,组件骨架十秒就出来了。但每次 review 到细节总会卡在同一批地方:弹层忘了 Esc 关闭、下拉列表没法用键盘导航、清空按钮一点焦点就丢了、屏幕阅读器读不出按钮状态。这最后 10% 的交互脏活,恰恰是 UI 工程里最难写、AI 最容易漏的部分。
Vercel 上月底在 GitHub 开源的 UI SDK(vercel-labs/ui)就是冲着这个问题去的:与其教 Agent 每次从头手搓,不如把「行为」本身做成库,让 Agent 只负责组装。README 里甚至直说了:「别担心,你不需要学会写这些。你的 Agent 会。而且我们把它们练得特别擅长。」我把这套库拉进沙盒实测了一圈,这篇文章把核心概念、实测结果和上手门槛一次讲清。
一、三周 5,000+ 星:给 Agent 用的「行为库」
先看基本面:2026 年 10 月 26 日开源,截至本文写作已有 5,285 星、172 个 fork,Apache-2.0 协议,TypeScript 编写。npm 端 11 月 12 日才发出第一个 beta,五天连发 6 版,最新 @ui-sdk/core 0.1.0-beta.6 是 11 月 16 日刚发的——迭代速度拉满。
它的定位是 headless 行为库:键盘导航、焦点、选择、消失、弹层、拖放,以及这些交互需要的全部 ARIA 属性,都做成可组装的积木。配五个框架适配器——React、Vue、Svelte、Solid 和 Web Components,同一份行为定义,五个框架渲染出同一个组件。现成组件也有 50 多个,从 Select、Dialog、Toast 到 Command、Tree、Image Cropper 都有。
和 Radix/shadcn 的区别一句话说清:Radix 是给人用的无头组件库,UI SDK 是给 Agent 用的行为库。它的文档分发、安装方式、API 设计,都是按「Agent 怎么消费」来优化的。
二、为 Agent 设计的三个证据
证据一:安装方式就是一段 prompt。官方 Quick Start 不是写给人看的教程,是让你直接粘给 Agent 的(React 版节选):
Set up ui-sdk in this React project. It needs React 19 or newer.
1. Install @ui-sdk/react and @ui-sdk/core with the project's package manager.
If a release-age policy blocks the install, stop and ask me instead
of changing it.
2. Add a note to AGENTS.md, creating it if needed: before using ui-sdk,
follow the ui-sdk skill if it's installed, and read
node_modules/@ui-sdk/react/docs/llms.txt.
3. If you support skills, run: npx skills@latest add vercel-labs/ui --skill ui-sdk注意这些细节:装 beta 包被版本策略拦住时「停下来问我,别自己改策略」;让 Agent 在 AGENTS.md 里留备忘,防止下个会话的 Agent 忘记规矩。这些坑位显然是被真实的 Agent 踩出来的。
证据二:文档随 npm 包发布。装完包,node_modules/@ui-sdk/react/docs/llms.txt 就是文档索引——Agent 不用联网搜文档,读本地文件,版本天然对齐。skill 文件里甚至明确教 Agent:「core.md 超过 300 KB,按标题搜索,别整个读」——连 Agent 的上下文预算都替你算好了。
证据三:官方 skill 一行装进 Agent。
npx skills@latest add vercel-labs/ui --skill ui-sdk不支持 skills 的 Agent 也不碍事,skill 文件就躺在 node_modules/@ui-sdk/core/skills/ui-sdk/SKILL.md,路径指过去就行。装完后对 Agent 说人话:
Use ui-sdk to build a five-star rating in React.
Arrow keys should move between stars and choose a rating.
Use our existing styles and test the keyboard behavior.它会自己读文档、挑行为、定义 primitive、渲染成你框架的组件,最后自己把键盘行为测一遍。
三、核心概念:一个 primitive = 状态 + API + 槽位
UI SDK 里一切组件的起点是 definePrimitive。拿官方教程里的静音按钮举例,完整代码就这么长:
import { definePrimitive } from "@ui-sdk/core"
const muteButton = definePrimitive({
name: "mute-button",
state: () => ({ muted: false }),
api: (context) => ({
toggle: () => context.store.set({ muted: !context.store.get().muted }),
}),
slots: (slot) => ({
root: slot({
attrs: (state) => ({
type: "button",
"aria-pressed": String(state.muted),
}),
press: ({ api }) => api.toggle(),
}),
}),
})- state:内部状态,muted 初始 false;
- api:改变状态的函数,这里只有 toggle;
- slots:槽位描述——root 槽位渲成一个原生 button,
aria-pressed跟着状态走,press 时调 toggle。
关键在 attrs 那几行:无障碍属性不是你手写的,是状态驱动、自动同步到 DOM 的。这就是「行为库」和「每次现场手搓」的本质区别。
四、五框架同构渲染:Web Components 版连打包器都不要
primitive 本身不渲染任何东西,渲染靠各框架的适配器。React 里用 createParts:
import { createParts } from "@ui-sdk/react/primitive"
import { muteButton } from "@/lib/mute-button"
const { Root: MuteButton } = createParts(muteButton, { root: "button" })
// 使用:<MuteButton>Mute</MuteButton>Vue、Svelte、Solid 的写法几乎一模一样,换个包名而已。Web Components 版本最省事,注册完直接写 HTML:
import { createParts, wrappedButton } from "@ui-sdk/web"
import { muteButton } from "@/lib/mute-button"
createParts(muteButton, {
root: { tag: "mute-button", target: wrappedButton },
})
// HTML 里直接用:
// <mute-button><button>Mute</button></mute-button>我在 Node 24 + jsdom 的沙盒里实跑了这个 Web Components 版本(core/web 均为 0.1.0-beta.6),注册、点击、状态翻转全部符合预期:
registered: true
初始 aria-pressed = "false",内层 button 自动挂上 data-slot="mute-button"
第一次点击 → aria-pressed = "true"
第二次点击 → aria-pressed = "false"
因为内核是原生 <button>,点击、Enter、Space 都会触发 press,屏幕阅读器从 aria-pressed 读状态——键盘和无障碍支持,一行代码没写就达标了。
样式完全留白,官方推荐用 data-slot 当钩子、状态属性当选择器,这份 CSS 五个框架通用:
[data-slot="mute-button"] {
border: 1px solid #e5e5e5;
border-radius: 0.5rem;
padding: 0.375rem 0.75rem;
&:focus-visible {
outline: 2px solid #a3a3a3;
outline-offset: 2px;
}
&[aria-pressed="true"] {
background: #171717;
color: white;
}
}五、行为组合实测:搜索框的「清空」按钮,三个脏活一次做完
行为库的真正价值在组合。官方 README 的 search-field 例子:清空按钮只在有内容时出现,点了清空,焦点要回到输入框而不是丢掉——这正是 AI 手搓最容易翻车的三件事。核心定义:
import { createFocusRecovery, definePrimitive } from "@ui-sdk/core"
const searchField = definePrimitive({
name: "search-field",
state: () => ({ value: "" }),
api: (context) => ({
set: (value) => context.store.set({ value }),
recovery: createFocusRecovery({
fallback: () => context.element("input"),
}),
}),
slots: (slot) => ({
input: slot({
attrs: (state) => ({ value: state.value }),
on: { input: (e, { api }) => api.set(e.target.value) },
}),
clear: slot({
present: (state) => state.value !== "",
attrs: () => ({ type: "button" }),
press: ({ api }) => api.set(""),
bind: (el, part) => part.api.recovery.bind(el, part),
}),
}),
})三个细节:present 做条件渲染,实现是自动加/移除 hidden 属性;createFocusRecovery 是内置行为,fallback 指向 input——按钮从 DOM 消失的瞬间把焦点接住、送回输入框;bind 把这个行为绑到 clear 槽位上。
同样在 jsdom 里实测,三个行为全部命中:
初始:清空按钮带 hidden 属性,不可见
输入 "hello":hidden 自动移除,type="button" 自动注入
点 Clear:value 清空、hidden 回来,activeElement 自动落回 input
条件渲染、属性响应、焦点恢复——一个 hidden 属性都没手写,全是状态驱动的。
六、更激进的玩法:WebMCP,让浏览器里的 Agent 直接操作你的组件
UI SDK 还带了 registerTools,通过浏览器的 document.modelContext API 暴露三个工具:snapshot(读组件树)、query(查询)、act(执行操作)。如果浏览器内置了 Agent,它可以真的「看见」并操作你页面上的组件——按按钮、填表单:
import { registerTools } from "@ui-sdk/react/agent"
import { agent } from "./agent"
const unregister = registerTools(agent, {
allow: (step) => step.action !== "press" || confirm(`Press ${step.args[0]}?`),
})
安全设计也想过了:allow 回调对每一步把关,上面例子里每次 press 都会找人确认;act 工具带 consequentialHint 标记,浏览器可据此在执行前询问人类;还可以给危险控件加 data-agent-confirm 属性,强制人工拍板。浏览器不支持 modelContext 时这段代码静默无效,不用自己做特性检测。
七、上手前要知道的四件事
- 还在 beta:受 Vercel beta terms 约束,GA 之前 API 可能变,生产项目建议先在边缘场景试水;
- 版本门槛不低:React 19+、Vue 3.5+、Svelte 5.33+、Solid 2(@solidjs/web 要 2.0.0-rc.14+),老项目得先升框架;
- 安装体积有感:@ui-sdk/core 装完约 7.9 MB——dist 全量组件目录占 6.9 MB,随包文档加 skill 约 1 MB;好在入口 index.js 只有 7 KB,按需 tree-shaking 后进包的代码很小;
- 行为目录够深:focus、lists、popups、selection、trees、drag-and-drop、motion、canvas、direct-manipulation、preferences 十类行为,50 多个现成组件覆盖不了的场景自己拼积木。
写在最后
UI SDK 赌的判断很明确:未来越来越多的 UI 会是 Agent 写的,那组件库的 API、文档分发、安装方式就该围绕 Agent 重新设计一遍。三周 5,000+ 星,说明这个判断踩中了风口。
对我这种天天让 AI 写页面的人来说,收益很实际:焦点管理、键盘导航、ARIA 这些「永远差最后一步」的脏活有库兜底之后,AI 生成的 UI 终于能直接见人了。仓库在 github.com/vercel-labs/ui,文档在 ui-sdk.dev/docs,感兴趣的先把那段安装 prompt 丢给自己的 Agent 试试。
以上内容为 GLM 5.3 Agent 整合定时发布。

