Монолитные библиотеки вроде MUI или Ant Design тащат в бандл 100–300+ КБ сжатого кода со стилями и жёсткой разметкой. При этом поведенческая начинка пятидесяти виджетов, включая фокус, клавиатуру, попапы и перетаскивание, весит меньше 10 КБ без внешних зависимостей. В ноябре 2026 года на это поставили Vercel Labs, создатель shadcn/ui (shadcn), Шу Динг и Гильермо Раух, выпустив бету UI SDK под лицензией Apache-2.0 на GitHub.
Как сказал shadcn в анонсе из JavaScript Weekly #811: «Нам не нужны одинаковые интерфейсы. Нам нужны одинаковые интерфейсные поведения». Разбираемся, как это устроено под капотом и чем за лёгкость придётся платить.
Почему разработчикам не нужна чужая разметка, но нужны правила доступности
В проекте со своей дизайн-системой конфликт с готовыми китами всплывает сразу. Подключаешь Chakra UI или MUI, а через неделю приносят макет нестандартного меню — и начинается война с чужим CSS-in-JS и обёртками.
Отказаться от чужой вёрстки легко, пока не упрёшься в стандарт WAI-ARIA. Он задаёт жёсткую механику клавиатуры и фокуса для навигации без мыши и экранных дикторов.
При открытии меню фокус переходит внутрь, Escape закрывает окно, а после закрытия курсор возвращается на кнопку вызова. Стрелки листают пункты без скролла страницы, а Tab сразу выводит фокус наружу. Писать эти обработчики onKeyDown вручную долго, а ИИ-агенты при генерации часто теряют ловушки фокуса и состояния aria-expanded.
Твоей команде нужна проверенная машина состояний для клавиатуры и доступности, а свои кнопки в дизайн-системе уже есть.
Headless-поведения: как UI SDK отделяет логику от визуала
Раньше логику от стилей отделяли через нестилизованные компоненты. Популярный Radix UI отдаёт <Dialog.Root> и <Dialog.Trigger> без CSS, но прибит к JSX и Virtual DOM. Библиотека React Aria от Adobe закрывает тонкости WAI-ARIA, но связывает хуки вроде useMenu с менеджерами react-stately и работает строго в React.
Авторы UI SDK спустились на этаж ниже. Пакет @ui-sdk/core отдаёт больше 50 примитивов — чистых конечных автоматов без привязки к фреймворку. Среди них createRovingFocus, createPopup, createSelection, createTypeahead, createFocusRecovery, createVirtualizer и createDragDrop.
Ставится всё двумя командами — сначала ядро, затем адаптер под стек.
pnpm add @ui-sdk/core
pnpm add @ui-sdk/react # или @ui-sdk/web-components
Ядро @ui-sdk/core написано на чистом TypeScript в формате ESM с нулём зависимостей. За счёт tree-shaking один примитив весит 0.5–1.8 КБ, а все 50+ поведений целиком занимают меньше 8–10 КБ.
Взвесим цену и выгоду. Ты сбрасываешь груз чужих стилей и получаешь полный контроль над DOM, но в пакете нет ни CSS, ни иконок, ни анимаций — весь визуал ты пишешь сам. Плюс идёт бета 0.1.0-beta.1 и 0.1.0-beta.2: до 1.0.0 сигнатуры привязок ещё могут меняться.
Roving focus, typeahead и нативные попапы на примере меню
Соберём кастомное выпадающее меню, чтобы увидеть примитивы в деле. Сначала переведём два термина: roving focus (блуждающий фокус) держит tabindex="0" только на активном пункте, а остальным ставит tabindex="-1", чтобы Tab сразу выпускал из списка при навигации стрелками. Механизм typeahead прыгает на нужный пункт при быстром наборе первых букв и сбрасывает буфер по паузе.
Опишем оба поведения в menu-primitive.ts через definePrimitive.
// menu-primitive.ts
import { definePrimitive, createRovingFocus, createTypeahead } from '@ui-sdk/core';
export const MenuPrimitive = definePrimitive({
setup() {
const rovingFocus = createRovingFocus({ orientation: 'vertical', loop: true });
const typeahead = createTypeahead({
onMatch: (index) => rovingFocus.focusItem(index),
timeout: 500,
});
return {
getItemProps: (index: number, label: string) => ({
tabIndex: rovingFocus.isFocused(index) ? 0 : -1,
onKeyDown: (e: React.KeyboardEvent) => {
rovingFocus.handleKeyDown(e.nativeEvent, index);
typeahead.handleKeyDown(e.nativeEvent, label);
},
}),
};
},
});
Здесь loop: true зацикливает проход стрелками, а createTypeahead держит буфер 500 мс и дёргает focusItem. Метод getItemProps отдаёт только tabIndex и onKeyDown без навязанных тегов. Подключим примитив в React-компонент DropdownMenu.tsx.
// DropdownMenu.tsx
import { usePrimitive } from '@ui-sdk/react';
import { MenuPrimitive } from './menu-primitive';
export function CustomDropdownMenu({ items }: { items: string[] }) {
const { getItemProps } = usePrimitive(MenuPrimitive);
return (
<ul role="menu" aria-label="Действия" className="custom-menu">
{items.map((item, i) => (
<li key={item} role="menuitem" className="custom-menu-item" {...getItemProps(i, item)}>{item}</li>
))}
</ul>
);
}
Хук usePrimitive пробрасывает логику фокуса прямо в твою разметку <ul> и <li> с любыми классами.
Дальше меню нужно открывать в браузерном Top Layer (без войн с z-index), закрывать по клику мимо (light dismiss) и возвращать фокус на кнопку. Для этого createPopup с createFocusRecovery работают поверх нативного popover и <dialog>.
// popup-integration.ts
import { createPopup, createFocusRecovery } from '@ui-sdk/core';
export function setupPopup(trigger: HTMLButtonElement, popupEl: HTMLElement, dialogEl: HTMLDialogElement) {
const focus = createFocusRecovery({ trigger });
const popup = createPopup({
useNativePopover: typeof popupEl.showPopover === 'function',
onOpenChange: (open) => {
trigger.setAttribute('aria-expanded', String(open));
open ? popupEl.showPopover?.() : (popupEl.hidePopover?.(), focus.restore());
},
});
popupEl.setAttribute('popover', 'auto');
popupEl.addEventListener('toggle', (e) => popup.setOpen((e as ToggleEvent).newState === 'open'));
trigger.addEventListener('click', () => popup.toggle());
dialogEl.addEventListener('close', () => trigger.focus());
}
При открытии showPopover() поднимает меню в Top Layer, событие toggle ловит закрытие по клику мимо или Escape, а focus.restore() возвращает фокус на кнопку (в модалках так же работает dialogEl.showModal() с событием close). В доках есть нюанс с анимацией: нативный hidePopover() сразу убирает элемент из Top Layer и рвёт CSS-выход, поэтому для плавности нужен флаг keepMounted: true или ожидание transitionend.
Мультифреймворковая архитектура: единый поведенческий слой для React, Vue, Svelte, Solid и Web Components
В крупных продуктах основной сайт крутится на React, админка на Vue, а виджеты собирают на Web Components. В UI SDK логику доступности не нужно переписывать под каждый стек.
Ядро связывает слоты definePrimitive через bind(element, part) напрямую с DOM без Virtual DOM. Слушатели вешаются через addEventListener, а tabindex, aria-selected и aria-activedescendant обновляются через setAttribute. Пакеты @ui-sdk/react, @ui-sdk/vue, @ui-sdk/svelte, @ui-sdk/solid и @ui-sdk/web-components служат тонкими адаптерами поверх общего ядра.
Посмотрим, как те же примитивы работают в чистом Web Component без фреймворков.
// custom-menu-element.ts
import { createRovingFocus, createTypeahead } from '@ui-sdk/core';
export class CustomMenuElement extends HTMLElement {
private roving = createRovingFocus({ orientation: 'vertical', loop: true });
private typeahead = createTypeahead({ onMatch: (i) => this.focusItem(i), timeout: 500 });
connectedCallback() {
this.setAttribute('role', 'menu');
const items = Array.from(this.querySelectorAll<HTMLElement>('[role="menuitem"]'));
items.forEach((el, i) => {
el.setAttribute('tabindex', i === 0 ? '0' : '-1');
el.addEventListener('keydown', (e) => {
this.roving.handleKeyDown(e, i);
this.typeahead.handleKeyDown(e, el.textContent?.trim() || '');
this.syncFocus(items);
});
});
}
private focusItem(i: number) {
this.roving.focusItem(i);
this.syncFocus(Array.from(this.querySelectorAll<HTMLElement>('[role="menuitem"]')));
}
private syncFocus(items: HTMLElement[]) {
items.forEach((el, i) => {
const active = this.roving.isFocused(i);
el.setAttribute('tabindex', active ? '0' : '-1');
if (active) el.focus();
});
}
}
В connectedCallback мы один раз вешаем keydown, а syncFocus обновляет tabindex и вызывает el.focus() без перерисовок. Правда, адаптеры созрели неравномерно: пакет для React сейчас самый обкатанный, а версии для Svelte, Solid и Web Components активно добирают тесты.
Интерфейсы для эпохи ИИ-агентов
Авторы называют UI SDK «набором инструкций x86 для интерфейсов» для кодинг-агентов. Файл спецификации llms.txt в поставке помогает модели собрать компонент по контракту вместо генерации хрупких обработчиков.
Кроме генерации кода, есть Agent Bridge через createAgent с методами snapshot(), act() и query(). Агенту не нужны скриншоты и координаты — он читает дерево состояний и вызывает действия программно.
Этот слой нужен не везде: простому сайту хватит <button>, <details> и <dialog>, а быстрый MVP проще собрать на готовом UI-ките. Для своей дизайн-системы на разных стеках или под ИИ-генерацию попробуй vercel-labs/ui — только зафиксируй бета-версию в package.json до 1.0.0.







