한눈에 익히는 Vercel UI SDK
2026년 11월 12일 Vercel Labs가 공개한 Vercel UI SDK(
vercel-labs/ui)는@ui-sdk/core의 50여 개 동작 프리미티브를 바탕으로,@ui-sdk/react/button,select,combobox같은 헤드리스 컴포넌트 파츠를 함께 제공하는 오픈소스 라이브러리다.일반 화면을 만들 때는
@ui-sdk/react/select처럼 이미 묶인 파츠를 조합해 바로 쓰고, 기존에 없는 커스텀 UI가 필요할 때만@ui-sdk/core의definePrimitive와createParts로 내려가 직접 조립한다.createAgent런타임 브리지를 함께 지원해, AI 에이전트가 스크린샷이나 전체 DOM을 읽는 대신 컴포넌트 상태를 직접 조회하고 조작할 수 있다.
기존 헤드리스 UI 라이브러리와 비교해 Vercel UI SDK가 다른 점은 계층이 둘로 열려 있다는 것이다. 위쪽에서는 @ui-sdk/react/button, @ui-sdk/react/select, @ui-sdk/react/combobox 같은 헤드리스 파츠를 제공하고, 아래쪽 @ui-sdk/core에서는 포커스, 팝업, 선택, 타이핑 검색 같은 동작 조각을 공개한다. 사람 개발자는 위쪽 파츠로 빠르게 조립하고, AI 에이전트나 특수 UI는 아래쪽 동작을 조합해 새 컴포넌트를 만든다.
definePrimitive, createParts 두 가지만 기억
커스텀 동작을 직접 만들거나 내부 구조를 이해할 때는 두 패키지만 보면 된다.
패키지 | 역할 |
|---|---|
|
|
|
|
표준 컴포넌트가 필요할 때는 @ui-sdk/react/button, @ui-sdk/react/select, @ui-sdk/react/combobox를 그대로 가져다 쓰면 된다. 설치 명령은 아래와 같다.
npm install @ui-sdk/react @ui-sdk/core예제 1. Button 만들기
@ui-sdk/react/button은 기본 <button type="button">에 비동기 중복 클릭 방지와 스크린 리더 안내를 더한다. onClick이 Promise를 반환하면 작업이 끝날 때까지 대기 상태(pending)를 유지해 추가 클릭을 막고, pendingAnnouncement로 스크린 리더 안내 문구도 지정할 수 있다.
"use client"
import { Button } from "@ui-sdk/react/button"
export function SaveButton() {
return (
<Button
onClick={() => new Promise((resolve) => setTimeout(resolve, 1500))}
pendingAnnouncement="저장 중"
className="rounded bg-black px-3 py-1.5 text-sm text-white"
>
저장
</Button>
)
}예제 2. Select 만들기
@ui-sdk/react/select는 내부적으로 createPopup, createSelection, createTypeahead 동작을 조합해 만든 파츠를 제공한다. 개발자는 Select, SelectLabel, SelectTrigger, SelectValue, SelectContent, SelectItem을 조합해 스타일만 입히면 된다.
import {
Select,
SelectContent,
SelectItem,
SelectLabel,
SelectTrigger,
SelectValue,
} from "@ui-sdk/react/select"
export function RoleSelect() {
return (
<Select placeholder="역할 선택">
<SelectLabel>권한</SelectLabel>
<SelectTrigger className="rounded border px-3 py-1.5 text-sm">
<SelectValue />
</SelectTrigger>
<SelectContent className="mt-1 rounded border bg-white p-1 shadow">
<SelectItem value="admin">Admin</SelectItem>
<SelectItem value="editor">Editor</SelectItem>
<SelectItem value="viewer">Viewer</SelectItem>
</SelectContent>
</Select>
)
}예제 3. 검색 가능한 Combobox 만들기
@ui-sdk/react/combobox는 Select와 같은 팝업, 선택, 방향키 이동 위에 ComboboxInput, ComboboxEmpty, ComboboxList를 더한 구조다. 사용자가 입력창에 글자를 치면 자동으로 목록을 걸러낸다.
"use client"
import {
Combobox,
ComboboxContent,
ComboboxEmpty,
ComboboxInput,
ComboboxItem,
ComboboxItemIndicator,
ComboboxLabel,
ComboboxList,
ComboboxTrigger,
} from "@ui-sdk/react/combobox"
import { CheckIcon, ChevronDownIcon } from "lucide-react"
const frameworks = [
{ value: "next", label: "Next.js" },
{ value: "sveltekit", label: "SvelteKit" },
{ value: "solidstart", label: "SolidStart" },
]
export function FrameworkCombobox() {
return (
<Combobox>
<ComboboxLabel>프레임워크</ComboboxLabel>
<div className="flex items-center gap-1">
<ComboboxInput placeholder="프레임워크 검색" />
<ComboboxTrigger aria-label="목록 열기">
<ChevronDownIcon aria-hidden="true" />
</ComboboxTrigger>
</div>
<ComboboxContent>
<ComboboxEmpty>검색 결과가 없습니다.</ComboboxEmpty>
<ComboboxList>
{frameworks.map((framework) => (
<ComboboxItem
key={framework.value}
value={framework.value}
label={framework.label}
>
{framework.label}
<ComboboxItemIndicator>
<CheckIcon aria-hidden="true" />
</ComboboxItemIndicator>
</ComboboxItem>
))}
</ComboboxList>
</ComboboxContent>
</Combobox>
)
}만약 여기에 없는 전혀 새로운 인터랙션이 필요하면, @ui-sdk/core의 definePrimitive로 상태와 슬롯을 정의하고 @ui-sdk/react/primitive의 createParts로 렌더링해 같은 방식으로 확장한다.
디자인 시스템 관점의 폴더 구조
표준 파츠와 커스텀 프리미티브를 함께 쓸 때는 역할을 네 층으로 분리하는 편이 관리하기 좋다.
src/
├── ui/ # 디자인 시스템 공통 계층
│ ├── primitives/ # @ui-sdk/core 기반 커스텀 동작 정의
│ ├── components/ # @ui-sdk/react/* 또는 createParts + 스타일 적용
│ └── tokens.css # 색상, 간격, 타이포그래피 디자인 토큰
│
├── features/ # 도메인 모듈 (비즈니스 로직 + ui/components 조합)
│ ├── project-env/
│ │ └── EnvSelector.tsx
│ └── task-assign/
│ └── AssigneeCombobox.tsx
│
└── routes/ # 페이지 (레이아웃, 데이터 로딩, features 배치)
└── settings.tsxui/primitives/에는 프레임워크 코드나 CSS 클래스를 넣지 않고 @ui-sdk/core만 둔다. ui/components/에서 스타일과 디자인 토큰을 입혀 내보내면, features/와 routes/는 @ui-sdk/core를 직접 만지지 않고 공통 컴포넌트만 가져다 쓰면 된다. 특정 화면에서만 쓰는 특수 동작이 필요하면 해당 features/ 폴더 안에 로컬 프리미티브를 먼저 두고, 두 곳 이상에서 재사용할 때 ui/primitives/로 옮긴다.
AI 에이전트 연동과 런타임 브리지
Vercel UI SDK는 npx skills add vercel-labs/ui --skill ui-sdk 명령으로 에이전트 스킬 문서를 붙여서 쓸 수 있다. 에이전트가 Select나 Combobox를 만들 때 접근성 속성을 빠뜨리지 않고 동작 조각을 조합하도록 안내한다.
런타임에서는 @ui-sdk/react/agent의 createAgent를 통해 에이전트가 컴포넌트와 직접 통신한다. 에이전트가 화면 스크린샷이나 전체 DOM 트리를 읽는 대신 snapshot, query, act 메서드로 컴포넌트 상태를 직접 읽고 동작을 실행한다. Vercel이 자체 공개한 설정 변경 벤치마크에서는 기존 브라우저 툴 방식보다 툴 호출 횟수가 69%(16회에서 5회), 읽은 텍스트 양이 83%(약 39.8k자에서 6.8k자), 작업 시간이 61%(41초에서 16초) 줄었다.
앞으로 남은 과제
현재 Public Beta 단계이며 스타일이 없는 헤드리스 라이브러리이므로 디자인 토큰과 CSS 스타일링은 팀에서 직접 입혀야 한다.
실제 팀에서 에이전트가
definePrimitive로 조립한 코드를 사람이 어떻게 유지보수할지 경험이 더 쌓여야 한다.
댓글