Radix UI 設計系統
使用 Radix UI 基本元件建立生產就緒、可存取的設計系統,擁有完整的客製化控制權且不帶任何風格意見。
概述
Radix UI 提供無樣式、可存取的元件(基本元件),您可以自訂它們以符合任何設計系統。此技能將引導您使用 Radix UI 建立可擴展的元件庫,重點關注無障礙優先設計、主題架構和可組合模式。
主要優勢:
- 天生無頭式設計:完全掌控樣式,無需對抗預設值
- 內建無障礙功能:符合 WAI-ARIA 標準、鍵盤導航、螢幕閱讀器支援
- 可組合的基本元件:從簡單的建構積木建立複雜的元件
- 框架無關:與 React 配合使用,但樣式可在任何地方運作
何時使用此技能
- 從頭開始建立自訂設計系統
- 建立可存取的 UI 元件庫
- 實作複雜的互動元件(對話框、下拉式選單、分頁標籤等)
- 從樣板化元件庫遷移到無樣式基本元件
- 使用 CSS 變數或 Tailwind 設定主題系統
- 需要完全控制元件的行為與樣式
- 建立需要符合 WCAG 2.1 AA/AAA 標準的應用程式
請勿使用此技能的情況
- 需要開箱即用的預先設計元件(請使用 shadcn/ui、Mantine 等)
- 建立沒有互動性的簡單靜態頁面
- 專案未使用 React 16.8 以上版本(Radix 需要 hooks)
- 需要非 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. 組合優於配置
從簡單的基本元件建立複雜的元件:
// 基本元件自然組合
<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:使用 Context 的複合元件
使用案例:在基本元件的各個部分之間共享狀態
// 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>
);
}
常用基本元件參考
對話框(Modal)
<Dialog.Root> {/* 狀態容器 */}
<Dialog.Trigger /> {/* 開啟對話框 */}
<Dialog.Portal> {/* 在 portal 中渲染 */}
<Dialog.Overlay /> {/* 背景 */}
<Dialog.Content> {/* 模態框內容 */}
<Dialog.Title /> {/* 無障礙功能必要 */}
<Dialog.Description /> {/* 無障礙功能必要 */}
<Dialog.Close /> {/* 關閉對話框 */}
</Dialog.Content>
</Dialog.Portal>
</Dialog.Root>
下拉式選單
<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.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.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.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.Title存在(螢幕閱讀器必要) -
Dialog.Description提供上下文 - 開啟時焦點限制在模態框內
- Escape 鍵關閉對話框
- 關閉時焦點回到觸發元件
下拉式選單專用:
- 方向鍵導航項目
- 輸入搜尋功能運作正常
- 第一個/最後一個項目循環行為
- 選中狀態以視覺和 ARIA 方式指示
最佳實踐
✅ 建議這麼做
-
始終使用
asChild以避免包裝 div<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 /> {/* 對話框內的 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.I
...
[截斷以利翻譯]