Radix UI デザインシステム
Radix UI プリミティブを使用して、完全なカスタマイズ制御とスタイルの制約なしに、プロダクション対応のアクセシブルなデザインシステムを構築します。
概要
Radix UI は、スタイルが適用されていないアクセシブルなコンポーネント(プリミティブ)を提供し、任意のデザインシステムに合わせてカスタマイズできます。このスキルは、アクセシビリティファーストの設計、テーマアーキテクチャ、およびコンポーザブルなパターンに焦点を当てて、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. 構成よりも合成
シンプルなプリミティブから複雑なコンポーネントを構築:
// プリミティブコンポーネントは自然に合成される
<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%;
}
// コンポーネント.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>
ドロップダウンメニュー
<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 キーでダイアログが閉じること
- 閉じたときにフォーカスがトリガーに戻ること
ドロップダウン固有:
- 矢印キーでアイテム間を移動できること
- タイプアヘッド検索が機能すること
- 最初/最後のアイテムのラッピング動作
- 選択状態が視覚的かつ 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.Trigger onKeyDown={(e) => e.preventDefault()}>
トラブルシューティング
コンポーネントがレンダリングされない
考えられる原因:
- 正しくインポートされていない:インポートが
@radix-ui/react-dialogからあることを確認 - Portal が欠落:
Dialog.Portalは必須。コンテンツは Portal 内になければレンダリングされない - プロバイダーが必要:
Tooltip.Providerは Tooltip のルートの祖先に必要
スタイルが適用されない
考えられる原因:
- CSS コンフリクト:セレクターの詳細度を確認。スタイルがオーバーライドされていないか
- テーマ変数が未定義:CSS 変数が適切に定義され、適用されていることを確認
- Tailwind クラスが有効でない:
tailwind.config.jsに適切なコンテンツパスが含まれているか確認
アクセシビリティの問題
考えられる原因:
Title欠落:Dialog.Titleは必須。ないとスクリーンリーダーがコンテンツを識別できない- フォーカス管理の問題:
onOpenChangeが適切にフォーカスをリセットしているか確認 - ARIA 属性の競合:カスタム ARIA 属性が Radix のデフォルトをオーバーライドしていないか確認
リソース
ライセンス
このスキルは MIT ライセンスの下で提供されています。