UI SDK от shadcn и Vercel: библиотека headless-поведений доступности для мультифреймворковых интерфейсовСтатья · дайджест за 18 ноября
UI SDK от shadcn и Vercel: библиотека headless-поведений доступности для мультифреймворковых интерфейсов
Статья5 разделов≈ 8 мин

UI SDK от shadcn и Vercel: библиотека headless-поведений доступности для мультифреймворковых интерфейсов

Монолитные библиотеки вроде 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.

Хочу подробный разборГолоса помогают выбрать, что разобрать подробно. За этот материал 0 голосов.
Источники · 10