UI SDK — библиотека поведений интерфейсов, спроектированная для агентов

· 7 мин чтения
ai-agents ui-design accessibility tools
📂 Исходный код на GitHub

Библиотека поведений интерфейсов для агентов: клавиатурная навигация, фокус, выделение, закрытие, попапы, drag-and-drop и нужная для них ARIA собраны в @ui-sdk/core, сверху есть адаптеры для React, Vue, Svelte, Solid и Web Components. Интерфейс можно открыть для агента через мост createAgent и WebMCP.

UI SDK — библиотека поведений интерфейсов, спроектированная для агентов

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 — как шаг с последствиями, по которому браузер может спросить человека перед выполнением.

Статус и ссылки

Репозиторий появился в конце октября 2026 года, библиотека в бете. Фреймворк, API и поведение компонентов могут поменяться до общего релиза, условия беты — стандартные для Vercel: https://vercel.com/docs/release-phases/public-beta-agreement

Источник: https://github.com/vercel-labs/ui