Radix UI 디자인 시스템
Radix UI 프리미티브를 사용하여 완전한 커스터마이징 제어와 스타일 독립성을 갖춘 프로덕션 준비, 접근 가능한 디자인 시스템을 구축합니다.
개요
Radix UI는 스타일이 지정되지 않은(unstyled), 접근 가능한 컴포넌트(프리미티브)를 제공하며, 어떤 디자인 시스템과도 일치하도록 커스터마이징할 수 있습니다. 이 스킬은 접근성 우선 디자인, 테마 아키텍처, 그리고 합성 가능한 패턴에 초점을 맞춰 Radix UI로 확장 가능한 컴포넌트 라이브러리를 구축하는 방법을 안내합니다.
주요 장점:
- 헤드리스 디자인: 기본값과 싸우지 않고 완전한 스타일 제어 가능
- 접근성 내장: WAI-ARIA 준수, 키보드 탐색, 스크린 리더 지원
- 합성 가능한 프리미티브: 간단한 구성 요소로 복잡한 컴포넌트 구축
- 프레임워크 독립적: React와 함께 작동하지만, 스타일은 어디서나 사용 가능
이 스킬을 사용해야 할 때
- 처음부터 맞춤 디자인 시스템을 만들 때
- 접근 가능한 UI 컴포넌트 라이브러리를 구축할 때
- 복잡한 대화형 컴포넌트(Dialog, Dropdown, Tabs 등)를 구현할 때
- 스타일드 컴포넌트 라이브러리에서 헤드리스 프리미티브로 마이그레이션할 때
- CSS 변수 또는 Tailwind를 사용한 테마 시스템을 설정할 때
- 컴포넌트 동작과 스타일링에 대한 완전한 제어가 필요할 때
- WCAG 2.1 AA/AAA 규정을 준수해야 하는 애플리케이션을 구축할 때
이 스킬을 사용하지 말아야 할 때
- 바로 사용 가능한 스타일이 지정된 컴포넌트가 필요할 때 (shadcn/ui, Mantine 등 사용)
- 상호작용이 없는 간단한 정적 페이지를 구축할 때
- 프로젝트가 React 16.8+를 사용하지 않을 때 (Radix는 훅을 필요로 함)
- React 이외의 프레임워크용 컴포넌트가 필요할 때
핵심 원칙
1. 접근성 우선
모든 Radix 프리미티브는 접근성을 기반으로 구축되었습니다:
- 키보드 탐색: 전체 키보드 지원 (Tab, 화살표 키, Enter, Escape)
- 스크린 리더: 적절한 ARIA 속성 및 라이브 리전
- 포커스 관리: 자동 포커스 트래핑 및 복원
- 비활성 상태: disabled 및 aria-disabled의 적절한 처리
규칙: 접근성 기능을 절대 재정의하지 마십시오. 향상시키되, 대체하지 마세요.
2. 헤드리스 아키텍처
Radix는 동작을 제공하고, 여러분은 외형을 제공합니다:
// ❌ 사전 스타일링된 컴포넌트와 싸우지 마세요
<Button className="override-everything" />
// ✅ Radix는 동작을 제공하고, 여러분이 스타일링을 추가합니다
<Dialog.Root>
<Dialog.Trigger className="your-button-styles" />
<Dialog.Content className="your-modal-styles" />
</Dialog.Root>
3. 구성(Composition)이 설정(Configuration)보다 우선
간단한 프리미티브로 복잡한 컴포넌트를 구축하세요:
// 프리미티브 컴포넌트는 자연스럽게 합성됩니다
<Tabs.Root>
<Tabs.List>
<Tabs.Trigger value="tab1">탭 1</Tabs.Trigger>
<Tabs.Trigger value="tab2">탭 2</Tabs.Trigger>
</Tabs.List>
<Tabs.Content value="tab1">내용 1</Tabs.Content>
<Tabs.Content value="tab2">내용 2</Tabs.Content>
</Tabs.Root>
시작하기
설치
# 개별 프리미티브 설치 (권장)
npm install @radix-ui/react-dialog @radix-ui/react-dropdown-menu
# 또는 한 번에 여러 개 설치
npm install @radix-ui/react-{dialog,dropdown-menu,tabs,tooltip}
# 스타일링용 (선택 사항이지만 일반적)
npm install clsx tailwind-merge class-variance-authority
기본 컴포넌트 패턴
모든 Radix 컴포넌트는 다음 패턴을 따릅니다:
import * as Dialog from '@radix-ui/react-dialog';
export function MyDialog() {
return (
<Dialog.Root>
{/* 다이얼로그 트리거 */}
<Dialog.Trigger asChild>
<button className="trigger-styles">열기</button>
</Dialog.Trigger>
{/* Portal은 DOM 계층 외부에 렌더링 */}
<Dialog.Portal>
{/* 오버레이 (배경) */}
<Dialog.Overlay className="overlay-styles" />
{/* 콘텐츠 (모달) */}
<Dialog.Content className="content-styles">
<Dialog.Title>제목</Dialog.Title>
<Dialog.Description>설명</Dialog.Description>
{/* 여기에 내용 */}
<Dialog.Close asChild>
<button>닫기</button>
</Dialog.Close>
</Dialog.Content>
</Dialog.Portal>
</Dialog.Root>
);
}
테마 전략
전략 1: CSS 변수 (프레임워크 독립적)
최적: 최대 이식성, SSR 친화적
/* globals.css */
:root {
--color-primary: 220 90% 56%;
--color-surface: 0 0% 100%;
--radius-base: 0.5rem;
--shadow-lg: 0 10px 15px -3px rgb(0 0 0 / 0.1);
}
[data-theme="dark"] {
--color-primary: 220 90% 66%;
--color-surface: 222 47% 11%;
}
// Component.tsx
<Dialog.Content
className="
bg-[hsl(var(--color-surface))]
rounded-[var(--radius-base)]
shadow-[var(--shadow-lg)]
"
/>
전략 2: Tailwind + CVA (Class Variance Authority)
최적: Tailwind 프로젝트, 변형이 많은 컴포넌트
// button.tsx
import { cva, type VariantProps } from 'class-variance-authority';
import { cn } from '@/lib/utils';
const buttonVariants = cva(
// 기본 스타일
"inline-flex items-center justify-center rounded-md font-medium transition-colors focus-visible:outline-none disabled:pointer-events-none disabled:opacity-50",
{
variants: {
variant: {
default: "bg-primary text-primary-foreground hover:bg-primary/90",
destructive: "bg-destructive text-destructive-foreground hover:bg-destructive/90",
outline: "border border-input bg-background hover:bg-accent",
ghost: "hover:bg-accent hover:text-accent-foreground",
},
size: {
default: "h-10 px-4 py-2",
sm: "h-9 rounded-md px-3",
lg: "h-11 rounded-md px-8",
icon: "h-10 w-10",
},
},
defaultVariants: {
variant: "default",
size: "default",
},
}
);
interface ButtonProps extends VariantProps<typeof buttonVariants> {
children: React.ReactNode;
}
export function Button({ variant, size, children }: ButtonProps) {
return (
<button className={cn(buttonVariants({ variant, size }))}>
{children}
</button>
);
}
전략 3: Stitches (CSS-in-JS)
최적: 런타임 테마, 스코프 스타일
import { styled } from '@stitches/react';
import * as Dialog from '@radix-ui/react-dialog';
const StyledContent = styled(Dialog.Content, {
backgroundColor: '$surface',
borderRadius: '$md',
padding: '$6',
variants: {
size: {
small: { width: '300px' },
medium: { width: '500px' },
large: { width: '700px' },
},
},
defaultVariants: {
size: 'medium',
},
});
컴포넌트 패턴
패턴 1: 컨텍스트가 있는 컴파운드 컴포넌트
사용 사례: 프리미티브 부분 간 상태 공유
// Select.tsx
import * as Select from '@radix-ui/react-select';
import { CheckIcon, ChevronDownIcon } from '@radix-ui/react-icons';
export function CustomSelect({ items, placeholder, onValueChange }) {
return (
<Select.Root onValueChange={onValueChange}>
<Select.Trigger className="select-trigger">
<Select.Value placeholder={placeholder} />
<Select.Icon>
<ChevronDownIcon />
</Select.Icon>
</Select.Trigger>
<Select.Portal>
<Select.Content className="select-content">
<Select.Viewport>
{items.map((item) => (
<Select.Item
key={item.value}
value={item.value}
className="select-item"
>
<Select.ItemText>{item.label}</Select.ItemText>
<Select.ItemIndicator>
<CheckIcon />
</Select.ItemIndicator>
</Select.Item>
))}
</Select.Viewport>
</Select.Content>
</Select.Portal>
</Select.Root>
);
}
패턴 2: asChild를 사용한 다형성 컴포넌트
사용 사례: 동작을 잃지 않고 다른 요소로 렌더링
// ✅ Next.js Link로 렌더링하지만 Radix 동작 유지
<Dialog.Trigger asChild>
<Link href="/settings">설정 열기</Link>
</Dialog.Trigger>
// ✅ 사용자 정의 컴포넌트로 렌더링
<DropdownMenu.Item asChild>
<YourCustomButton icon={<Icon />}>액션</YourCustomButton>
</DropdownMenu.Item>
asChild가 중요한 이유: 접근성 트리에서 중첩된 버튼/링크 문제를 방지합니다.
패턴 3: 제어 vs 비제어
// 비제어 (Radix가 상태 관리)
<Tabs.Root defaultValue="tab1">
<Tabs.Trigger value="tab1">탭 1</Tabs.Trigger>
</Tabs.Root>
// 제어 (개발자가 상태 관리)
const [activeTab, setActiveTab] = useState('tab1');
<Tabs.Root value={activeTab} onValueChange={setActiveTab}>
<Tabs.Trigger value="tab1">탭 1</Tabs.Trigger>
</Tabs.Root>
규칙: 외부 상태(URL, Redux 등)와 동기화해야 할 때는 제어 방식을 사용하세요.
패턴 4: Framer Motion을 사용한 애니메이션
import * as Dialog from '@radix-ui/react-dialog';
import { motion, AnimatePresence } from 'framer-motion';
export function AnimatedDialog({ open, onOpenChange }) {
return (
<Dialog.Root open={open} onOpenChange={onOpenChange}>
<Dialog.Portal forceMount>
<AnimatePresence>
{open && (
<>
<Dialog.Overlay asChild>
<motion.div
initial={{ opacity: 0 }}
animate={{ opacity: 1 }}
exit={{ opacity: 0 }}
className="dialog-overlay"
/>
</Dialog.Overlay>
<Dialog.Content asChild>
<motion.div
initial={{ opacity: 0, scale: 0.95 }}
animate={{ opacity: 1, scale: 1 }}
exit={{ opacity: 0, scale: 0.95 }}
className="dialog-content"
>
{/* 내용 */}
</motion.div>
</Dialog.Content>
</>
)}
</AnimatePresence>
</Dialog.Portal>
</Dialog.Root>
);
}
일반적인 프리미티브 참조
Dialog (모달)
<Dialog.Root> {/* 상태 컨테이너 */}
<Dialog.Trigger /> {/* 다이얼로그 열기 */}
<Dialog.Portal> {/* 포털에 렌더링 */}
<Dialog.Overlay /> {/* 배경 */}
<Dialog.Content> {/* 모달 내용 */}
<Dialog.Title /> {/* 접근성을 위해 필요 */}
<Dialog.Description /> {/* 접근성을 위해 필요 */}
<Dialog.Close /> {/* 다이얼로그 닫기 */}
</Dialog.Content>
</Dialog.Portal>
</Dialog.Root>
Dropdown Menu
<DropdownMenu.Root>
<DropdownMenu.Trigger />
<DropdownMenu.Portal>
<DropdownMenu.Content>
<DropdownMenu.Item />
<DropdownMenu.Separator />
<DropdownMenu.CheckboxItem />
<DropdownMenu.RadioGroup>
<DropdownMenu.RadioItem />
</DropdownMenu.RadioGroup>
<DropdownMenu.Sub> {/* 중첩 메뉴 */}
<DropdownMenu.SubTrigger />
<DropdownMenu.SubContent />
</DropdownMenu.Sub>
</DropdownMenu.Content>
</DropdownMenu.Portal>
</DropdownMenu.Root>
Tabs
<Tabs.Root defaultValue="tab1">
<Tabs.List>
<Tabs.Trigger value="tab1" />
<Tabs.Trigger value="tab2" />
</Tabs.List>
<Tabs.Content value="tab1" />
<Tabs.Content value="tab2" />
</Tabs.Root>
Tooltip
<Tooltip.Provider delayDuration={200}>
<Tooltip.Root>
<Tooltip.Trigger />
<Tooltip.Portal>
<Tooltip.Content side="top" align="center">
툴팁 텍스트
<Tooltip.Arrow />
</Tooltip.Content>
</Tooltip.Portal>
</Tooltip.Root>
</Tooltip.Provider>
Popover
<Popover.Root>
<Popover.Trigger />
<Popover.Portal>
<Popover.Content side="bottom" align="start">
내용
<Popover.Arrow />
<Popover.Close />
</Popover.Content>
</Popover.Portal>
</Popover.Root>
접근성 체크리스트
모든 컴포넌트는 다음을 가져야 합니다:
- 포커스 관리: 모든 대화형 요소에 가시적인 포커스 표시기
- 키보드 탐색: 전체 키보드 지원 (Tab, 화살표, Enter, Esc)
- ARIA 레이블: 스크린 리더를 위한 의미 있는 레이블
- 색상 대비: WCAG AA 최소 기준 (텍스트 4.5:1, UI 3:1)
- 오류 상태:
aria-invalid및aria-describedby를 사용한 명확한 오류 메시지 - 로딩 상태: 비동기 작업 중 적절한
aria-busy
Dialog 관련:
-
Dialog.Title이 있어야 함 (스크린 리더 필수) -
Dialog.Description이 컨텍스트를 제공해야 함 - 열려 있을 때 포커스가 모달 내부에 트래핑되어야 함
- Escape 키가 다이얼로그를 닫아야 함
- 닫힐 때 포커스가 트리거로 돌아와야 함
Dropdown 관련:
- 화살표 키로 항목 탐색 가능
- 타입어헤드 검색이 작동
- 첫 번째/마지막 항목 래핑 동작
- 선택된 상태가 시각적으로 및 ARIA로 표시
모범 사례
✅ 이렇게 하세요
-
래퍼 div를 피하려면 항상
asChild사용<Dialog.Trigger asChild> <button>열기</button> </Dialog.Trigger> -
의미 있는 HTML 제공
<Dialog.Content asChild> <article role="dialog" aria-labelledby="title"> {/* 내용 */} </article> </Dialog.Content> -
테마에 CSS 변수 사용
.dialog-content { background: hsl(var(--surface)); color: hsl(var(--on-surface)); } -
복잡한 컴포넌트를 위해 프리미티브 구성
function CommandPalette() { return ( <Dialog.Root> <Dialog.Content> <Combobox /> {/* Dialog 내부의 Radix Combobox */} </Dialog.Content> </Dialog.Root> ); }
❌ 이렇게 하지 마세요
-
접근성 부분을 건너뛰지 마세요
// ❌ Title과 Description 누락 <Dialog.Content> <div>내용</div> </Dialog.Content> -
프리미티브와 싸우지 마세요
// ❌ 내부 동작 재정의 <Dialog.Content onClick={(e) => e.stopPropagation()}> -
제어와 비제어를 혼용하지 마세요
// ❌ 일관성 없는 상태 관리 <Tabs.Root defaultValue="tab1" value={activeTab}> -
키보드 탐색을 무시하지 마세요
// ❌ 키보드 동작 비활성화 <DropdownMenu.Item onKeyDown={(e) => e.preventDefault()}> -
불필요한 DOM 요소를 추가하지 마세요
// ❌ 불필요한 래퍼 div <div className="menu-item"> <DropdownMenu.Item>항목</DropdownMenu.Item> </div>
Radix UI와 함께 사용하는 인기 라이브러리
| 라이브러리 | 목적 | 사용 시기 |
|---|---|---|
| shadcn/ui | 사전 스타일링된 컴포넌트 | 빠른 프로토타이핑, Radix 학습 |
| Tailwind CSS | 유틸리티 우선 스타일링 | 대규모 팀, 디자인 시스템 |
| Stitches | CSS-in-JS | 런타임 테마, 변형 |
| Framer Motion | 애니메이션 | 복잡한 모션 디자인 |
| React Hook Form | 폼 유효성 검사 | 복잡한 폼 |
| Zod | 스키마 유효성 검사 | 타입 안전한 폼 |
| React Aria | 추가 접근성 훅 | 고급 접근성 요구 사항 |
일반적인 문제
문제: "스타일이 적용되지 않습니다"
Radix는 스타일을 제공하지 않습니다. 모든 스타일을 직접 추가해야 합니다.
// ❌ 스타일 없음
<Dialog.Content>
// ✅ 스타일 추가
<Dialog.Content className="bg-white p-6 rounded-lg shadow-xl">
문제: "asChild prop이 작동하지 않습니다"
asChild를 사용하려면 전달된 자식이 단일 요소를 렌더링해야 합니다.
// ❌ 작동 안 함: 여러 요소
<Dialog.Trigger asChild>
<button>열기</button>
<span>또는</span>
</Dialog.Trigger>
// ✅ 작동: 단일 요소
<Dialog.Trigger asChild>
<button>열기</button>
</Dialog.Trigger>
문제: "서버 렌더링 오류"
Radix는 런타임에 useId()를 사용합니다. Next.js 13+ 또는 Remix에서 클라이언트 컴포넌트로 래핑하세요.
// app/components/Dialog.client.tsx
"use client";
import * as Dialog from '@radix-ui/react-dialog';
export function ClientDialog() {
return <Dialog.Root>...</Dialog.Root>;
}
고급: 사용자 정의 프리미티브 구축
Radix를 확장하여 사용자 정의 상호작용 패턴을 만드는 방법:
// Accordion.tsx
import * as Accordion from '@radix-ui/react-accordion';
import { ChevronDownIcon } from '@radix-ui/react-icons';
const AccordionTrigger = React.forwardRef(({ children, ...props }, forwardedRef) => (
<Accordion.Header>
<Accordion.Trigger
className="group flex w-full items-center justify-between px-4 py-2"
{...props}
ref={forwardedRef}
>
{children}
<ChevronDownIcon className="transition-transform group-data-[state=open]:rotate-180" />
</Accordion.Trigger>
</Accordion.Header>
));
const AccordionContent = React.forwardRef(({ children, ...props }, forwardedRef) => (
<Accordion.Content
className="data-[state=open]:animate-slideDown data-[state=closed]:animate-slideUp"
{...props}
ref={forwardedRef}
>
<div className="px-4 py-2">{children}</div>
</Accordion.Content>
));
export function MyAccordion() {
return (
<Accordion.Root type="single" collapsible>
<Accordion.Item value="item-1">
<AccordionTrigger>섹션 1</AccordionTrigger>
<AccordionContent>내용 1</AccordionContent>
</Accordion.Item>
</Accordion.Root>
);
}
리소스
- Radix UI 공식 문서
- Radix UI GitHub
- WAI-ARIA 작성 관행
- WCAG 2.1 지침
- shadcn/ui - Radix 기반 인기 컴포넌트 라이브러리
- Radix Themes - 공식 스타일링 솔루션 (실험적)
라이선스
이 스킬은 교육 목적으로 제공됩니다. Radix UI는 MIT 라이선스에 따라 제공됩니다.