UI SDK — библиотека поведений интерфейсов, спроектированная для агентов
📂 Исходный код на GitHubБиблиотека поведений интерфейсов для агентов: клавиатурная навигация, фокус, выделение, закрытие, попапы, drag-and-drop и нужная для них ARIA собраны в @ui-sdk/core, сверху есть адаптеры для React, Vue, Svelte, Solid и Web Components. Интерфейс можно открыть для агента через мост createAgent и WebMCP.
Vercel Labs выпустила UI SDK — open-source библиотеку компонентов, которую авторы проектируют специально под разработку с AI-агентами. Ставка простая: интерфейс будет писать не человек, а агент. Значит, библиотека должна быть устроена так, чтобы агенту было удобно её читать и использовать. Всё нужное для доступности — клавиатурная навигация, фокус, выделение, закрытие, попапы, drag-and-drop и разметка ARIA — уже встроено в поведения из пакета @ui-sdk/core. Сверху есть адаптеры для React, Vue, Svelte, Solid и Web Components. Проект написан на TypeScript, распространяется по лицензии Apache-2.0, за первые недели собрал около 4,5 тысячи звёзд на GitHub. Сейчас библиотека в бете, документация живёт на ui-sdk.dev.
Компоненты собираются из поведений
Обычные UI-библиотеки дают готовые компоненты: кнопка, поле ввода, выпадающий список. UI SDK идёт другим путём. Базовая единица здесь — поведение: отдельный блок логики вроде обработки фокуса или закрытия по Escape. Из поведений собираются примитивы, а из примитивов — компоненты. Так клавиатурная навигация и ARIA появляются в любом компоненте автоматически, а не пишутся заново каждый раз.
Авторы прямо говорят в README: учиться писать такой код вручную не нужно. Это работа агента, и библиотека сделана так, чтобы агент справлялся с ней хорошо.
Примитив описывается функцией definePrimitive. Вот пример поля поиска из README — у него есть состояние, API и слоты:
import { createFocusRecovery, definePrimitive } from "@ui-sdk/core"
const searchField = definePrimitive({
name: "search-field",
state: () => ({ value: "" }),
api: (context) => ({
set: (value: string) => context.store.set({ value }),
recovery: createFocusRecovery({ fallback: () => context.element("input") }),
}),
slots: (slot) => ({
input: slot({
attrs: (state) => ({ value: state.value }),
on: {
input: (event, { api }) =>
api.set((event.target as HTMLInputElement).value),
},
}),
clear: slot({
present: (state) => state.value !== "",
attrs: () => ({ type: "button" }),
press: ({ api }) => api.set(""),
bind: (el, part) => part.api.recovery.bind(el, part),
}),
}),
})
export { searchField }
Готовый примитив рендерится в любом фреймворке через createParts. Названия частей совпадают во всех пяти адаптерах, поэтому разметка переносится между ними почти без изменений. Пример для React:
import { createParts } from "@ui-sdk/react/primitive"
import { searchField } from "./search-field"
const parts = createParts(searchField, { input: "input", clear: "button" })
const SearchField = parts.Root
const SearchFieldInput = parts.Input
const SearchFieldClear = parts.Clear
function Search() {
return (
<SearchField>
<SearchFieldInput placeholder="Search" />
<SearchFieldClear>Clear</SearchFieldClear>
</SearchField>
)
}
Точно так же примитив рендерится в Vue, Svelte, Solid и Web Components — меняется только импорт адаптера.
Пакеты и установка
Ядро и адаптеры публикуются как отдельные npm-пакеты:
| Пакет | Что внутри |
|---|---|
@ui-sdk/core |
Поведения, примитивы, логика ARIA |
@ui-sdk/react |
Адаптер для React |
@ui-sdk/vue |
Адаптер для Vue |
@ui-sdk/svelte |
Адаптер для Svelte |
@ui-sdk/solid |
Адаптер для Solid |
@ui-sdk/web |
Web Components |
Установка — два пакета: ядро и адаптер под ваш фреймворк.
npm install @ui-sdk/react @ui-sdk/core
Компоненты headless: они не рисуют стили сами. Если нужен готовый внешний вид, подключается @ui-sdk/core/web.css с оформлением по умолчанию.
Скилл для агента
Библиотеку ставит не только человек — её ставит агент. Команда подключения скилла выглядит так:
npx skills add vercel-labs/ui --skill ui-sdk
Скилл учит агента работать с библиотекой. Ключевые идеи из SKILL.md:
- Документация установленной версии лежит прямо в node_modules в формате Markdown. Точка входа — файл llms.txt внутри пакета адаптера. Онлайн-версия на ui-sdk.dev — запасной вариант: локальная всегда совпадает с версией в проекте.
- Дальше агент выбирает один из двух путей. Первый — собрать интерфейс из готовых компонентов библиотеки. Второй — построить недостающий компонент из поведений
@ui-sdk/core. Оба пути заканчиваются одинаково: интерфейс делают agent-ready и покрывают тестами. - Жёсткие правила против типовых ошибок. Не импортировать внутренности ядра. Давать каждому контролу имя через label-часть или aria-label. Стилизовать состояние через data-атрибуты вроде
data-open, а не инлайн-стили. И главное: не писатьrole="listbox"илиrole="dialog"вручную, если ui-sdk уже установлен — почти всегда это баг, потому что нужный компонент уже есть.
Правило про имена контролов стоит разобрать отдельно. По нему элементы ищут не только агенты, но и скринридеры. Ошибка в имени ломает доступность и для человека, и для агента сразу.
Ещё несколько правил из скилла:
- Контролы работают в двух режимах. Неконтролируемое состояние задаётся через
defaultValue. Управляемое — черезvalueплюс колбэкonValueChange, у которого в объекте details лежат причина изменения, источник и методcancel(). В Vue это v-model, в Svelte — bind:value, в Web Components — свойства и события. - Элементы списка ключуются по значению или id, но не по индексу.
- Структура разметки единая везде: корень и его части, вложенные так, как показывает страница компонента в документации. Заменить элемент части можно через render, отдельного пропа вроде as в библиотеке нет.
- Контраст цветов проверяется в настоящем браузере: jsdom не видит цвет. Тексту нужно соотношение 4,5 к 1 с фоном, а рамкам контролов, focus ring и заливкам состояний — 3 к 1.
Есть и сценарий без сборки. Страница без бандлера — например, артефакт внутри чата — ничего не устанавливает. Она подключает два тега: скрипт web.js и стили web.css с ui-sdk.dev. Документация для такого случая собрана в один файл web.md.
Тесты агент пишет сам. Скилл требует проверять работу с клавиатуры, фокус, ARIA, серверный рендеринг и поддержку письма справа налево. Направление письма компоненты читают со страницы, отдельный провайдер не нужен.
Финал у каждой задачи одинаковый. Сначала проверка типов: обычный tsc --noEmit не всегда видит монорепозиторий с project references, тогда нужен tsc -b. В Svelte это svelte-check, в Vue — vue-tsc. Потом тесты. Напоследок агент перечитывает комментарии в своём диффе и удаляет лишние: комментарий остаётся, только если без него код можно понять неправильно.
Интерфейс, открытый для агента
Вторая половина замысла — дать агенту работать с готовым приложением напрямую, без эмуляции мыши и клавиатуры. Для этого в библиотеке есть мост createAgent. Агент читает компоненты страницы через snapshot и вызывает их действия сам. Подробности — в разделе документации про агентов.
Приложение сохраняет контроль. Каждое изменение от агента приходит в колбэки вроде onValueChange, и по полю details.source со значением agent его можно отличить от действий человека. Вызов details.cancel() отклоняет изменение.
Для пометки опасных мест есть три data-атрибута:
data-agent-confirm— на действия, которые агент не должен выполнять сам: удалить проект, заплатить, отправить письмо. Значение атрибута — объяснение для человека, например «Удаляет проект и все его файлы».data-agent-secret— на поля, значение которых агент может заполнить, но не должен читать. Поля пароля, номера карты и одноразового кода считаются секретными без пометки.data-agent-hidden— на области, которые агент не должен видеть вовсе, например коды восстановления.
Свои примитивы тоже объявляют агентные действия — через ключ agent в definePrimitive:
agent: { actions: ["rate"] },
WebMCP: агент внутри браузера
UI SDK умеет открывать интерфейс и встроенному агенту браузера. Функция registerTools публикует три инструмента — snapshot, act и query — через браузерный API document.modelContext. Это механизм WebMCP: агент браузера видит компоненты приложения и может ими пользоваться.
Регистрация требует фильтра allow. Приложение отвечает за каждый шаг чужого агента и может отказать в нём. У инструментов есть подсказки для потребителя: snapshot и query помечены как read-only, act — как шаг с последствиями, по которому браузер может спросить человека перед выполнением.
Статус и ссылки
- Репозиторий: https://github.com/vercel-labs/ui
- Документация: https://ui-sdk.dev/docs
- Раздел про агентов: https://ui-sdk.dev/docs/agents
- Скилл ui-sdk: https://github.com/vercel-labs/ui/blob/main/packages/core/skills/ui-sdk/SKILL.md
- Баг-репорты: https://github.com/vercel-labs/ui/issues
- Правила вклада: https://github.com/vercel-labs/ui/blob/main/CONTRIBUTING.md
Репозиторий появился в конце октября 2026 года, библиотека в бете. Фреймворк, API и поведение компонентов могут поменяться до общего релиза, условия беты — стандартные для Vercel: https://vercel.com/docs/release-phases/public-beta-agreement
Источник: https://github.com/vercel-labs/ui