UI SDK de shadcn y Vercel: librería de comportamientos headless de accesibilidad para interfaces multiframeworkArtículo · digest del 18 de noviembre
UI SDK de shadcn y Vercel: librería de comportamientos headless de accesibilidad para interfaces multiframework
Artículo5 secciones≈ 10 min

UI SDK de shadcn y Vercel: librería de comportamientos headless de accesibilidad para interfaces multiframework

Librerías monolíticas como MUI o Ant Design meten al bundle entre 100 y más de 300 KB de código comprimido lleno de estilos y marcado rígido. En cambio, la lógica de comportamiento de cincuenta widgets, incluyendo foco, teclado, popups y arrastrar y soltar, pesa menos de 10 KB sin dependencias externas. En noviembre de 2026 apostaron por esto Vercel Labs, el creador de shadcn/ui (shadcn), Shu Ding y Guillermo Rauch al lanzar la beta de UI SDK bajo licencia Apache-2.0 en GitHub.

Como dijo shadcn en el anuncio recogido en JavaScript Weekly #811: «No necesitamos interfaces idénticas. Necesitamos comportamientos de interfaz idénticos». Veamos cómo funciona por dentro y qué costo tiene esta ligereza.

Por qué los equipos no quieren marcado ajeno, pero sí reglas de accesibilidad

En cualquier proyecto con sistema de diseño propio, el choque con los kits listos aparece enseguida. Instalas Chakra UI o MUI, a la semana llega el diseño de un menú fuera de lo común y empieza la pelea contra su CSS-in-JS y sus envoltorios.

Renunciar a la maquetación de terceros es fácil hasta que topas con el estándar WAI-ARIA. Este exige reglas estrictas de teclado y foco para navegar sin mouse y con lectores de pantalla.

Al abrir un menú, el foco debe entrar en él, Escape debe cerrarlo y al cerrar el cursor debe volver al botón que lo abrió. Las flechas recorren opciones sin hacer scroll en la página y Tab saca el foco hacia afuera al instante. Escribir esos manejadores onKeyDown a mano lleva tiempo, y los agentes de IA suelen olvidar trampas de foco o atributos aria-expanded al generar código.

Tu equipo necesita una máquina de estados probada para teclado y accesibilidad; los botones propios ya los tienes en tu sistema de diseño.

Comportamientos headless: cómo UI SDK separa la lógica de lo visual

Antes, la lógica se separaba de los estilos mediante componentes sin estilizar. El popular Radix UI entrega <Dialog.Root> y <Dialog.Trigger> sin CSS, pero vive atado a JSX y al Virtual DOM. La librería React Aria de Adobe cubre al detalle WAI-ARIA, pero enlaza hooks como useMenu con gestores de react-stately y funciona solo en React.

Los autores de UI SDK bajaron un piso más. El paquete @ui-sdk/core ofrece más de 50 primitivos: máquinas de estados puras sin vínculo con ningún framework. Entre ellas están createRovingFocus, createPopup, createSelection, createTypeahead, createFocusRecovery, createVirtualizer y createDragDrop.

Todo se instala con dos comandos: primero el núcleo y luego el adaptador de tu stack.

pnpm add @ui-sdk/core
pnpm add @ui-sdk/react # o @ui-sdk/web-components

El núcleo @ui-sdk/core está escrito en TypeScript puro en formato ESM con cero dependencias. Gracias al tree-shaking, un primitivo pesa entre 0.5 y 1.8 KB, y los más de 50 comportamientos juntos ocupan menos de 8 a 10 KB.

Pongamos en balanza costo y beneficio. Te quitas el peso de estilos ajenos y ganas control total sobre el DOM, pero el paquete no trae CSS, íconos ni animaciones: toda la parte visual corre por tu cuenta. Además está en beta (0.1.0-beta.1 y 0.1.0-beta.2), así que hasta la versión 1.0.0 las firmas pueden cambiar.

Roving focus, typeahead y popups nativos en un menú de ejemplo

Armemos un menú desplegable a medida para ver los primitivos en acción. Primero aclaremos dos términos: roving focus (foco itinerante) mantiene tabindex="0" solo en la opción activa y pone tabindex="-1" en las demás, para que Tab te saque de la lista al instante mientras navegas con flechas. El mecanismo typeahead salta al elemento buscado cuando tecleas rápido sus primeras letras y reinicia el búfer tras una pausa.

Definimos ambos comportamientos en menu-primitive.ts con 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);
        },
      }),
    };
  },
});

Aquí loop: true hace circular el recorrido con las flechas, mientras createTypeahead mantiene el búfer 500 ms y llama a focusItem. El método getItemProps devuelve solo tabIndex y onKeyDown sin imponer etiquetas. Conectemos este primitivo en el componente 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>
  );
}

El hook usePrimitive inyecta la lógica del foco directo en tu marcado <ul> y <li> con las clases que quieras.

Falta abrir el menú en el Top Layer del navegador (sin peleas de z-index), cerrarlo al hacer clic fuera (light dismiss) y devolver el foco al botón. Para ello, createPopup y createFocusRecovery trabajan sobre los nativos popover y <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());
}

Al abrirse, showPopover() sube el menú al Top Layer, el evento toggle detecta el cierre por clic externo o Escape, y focus.restore() regresa el foco al botón (en modales funciona igual con dialogEl.showModal() y el evento close). En la documentación advierten un detalle con las animaciones: el método nativo hidePopover() saca el elemento del Top Layer al instante y corta la transición CSS de salida, así que para animaciones suaves conviene usar keepMounted: true o esperar a transitionend.

Arquitectura multiframework: una sola capa de comportamiento para React, Vue, Svelte, Solid y Web Components

En productos grandes es normal tener el sitio principal en React, el panel de administración en Vue y widgets en Web Components. Con UI SDK no hace falta reescribir la lógica de accesibilidad para cada stack.

El núcleo enlaza los slots de definePrimitive mediante bind(element, part) directo al DOM, sin Virtual DOM. Registra oyentes con addEventListener y actualiza tabindex, aria-selected y aria-activedescendant vía setAttribute. Los paquetes @ui-sdk/react, @ui-sdk/vue, @ui-sdk/svelte, @ui-sdk/solid y @ui-sdk/web-components actúan como adaptadores delgados encima del núcleo compartido.

Veamos cómo corren los mismos primitivos en un Web Component puro sin frameworks.

// 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();
    });
  }
}

En connectedCallback registramos keydown una sola vez, y syncFocus actualiza tabindex y llama a el.focus() sin re-renderizados. Eso sí, los adaptadores no están igual de maduros: el paquete de React es el más probado hoy, mientras Svelte, Solid y Web Components siguen sumando pruebas.

Interfaces para la era de los agentes de IA

Los autores describen UI SDK como «el conjunto de instrucciones x86 para interfaces» pensado para agentes de programación. El archivo de especificación llms.txt incluido en el proyecto ayuda al modelo a armar componentes siguiendo un contrato claro en vez de improvisar manejadores frágiles.

Además de generar código, ofrece Agent Bridge mediante createAgent con los métodos snapshot(), act() y query(). El agente no necesita capturas de pantalla ni coordenadas: lee el árbol de estados y dispara acciones por código.

Esta capa no hace falta en todas partes: a un sitio sencillo le sobra con <button>, <details> y <dialog>, y un MVP rápido sale mejor con un kit visual completo. Pero si mantienes tu propio sistema de diseño en varios stacks o generas UI con IA, vale probar vercel-labs/ui, siempre fijando la versión beta en package.json hasta que llegue la 1.0.0.

Quiero un análisis detalladoLos votos ayudan a elegir qué analizar a fondo. Este material tiene 0 votos.
Fuentes · 10