UI コンポーネント

shadcn/ui と Radix Primitives を使用した、アクセス可能な UI コンポーネント ライブラリを構築するための包括的なパターン。CVA バリアント、OKLCH テーマ設定、cn() ユーティリティ、コンポーネント拡張、asChild コンポジション、ダイアログ/メニュー パターン、データ属性スタイリングをカバー。各カテゴリは rules/ フォルダの個別ルール ファイルを持ち、オンデマンドで読み込まれます。

クイック リファレンス

カテゴリ	ルール	影響度	用途
shadcn/ui	4	高	CVA バリアント、コンポーネント カスタマイズ、フォーム パターン、データ テーブル、v4 スタイル
Radix Primitives	3	高	ダイアログ、ポリモーフィック コンポジション、データ属性スタイリング
デザイン システム	5	高	W3C トークン、OKLCH テーマ設定、間隔スケール、タイポグラフィ、コンポーネント状態、アニメーション
デザイン システム コンポーネント	1	高	アトミック デザイン、CVA バリアント、アクセシビリティ、Storybook
フォーム	2	高	React Hook Form v7、Zod バリデーション、Server Actions
モダン CSS とツール	3	高	CSS カスケード レイヤー、Tailwind v4、Storybook CSF3
UX ファンデーション	4	高	ビジュアル階層、タイポグラフィ閾値、カラー システム、空の状態

合計: 7 カテゴリ中 22 のルール

クイック スタート

// cn() ユーティリティを使用した CVA バリアント システム
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',
  {
    variants: {
      variant: {
        default: 'bg-primary text-primary-foreground hover:bg-primary/90',
        destructive: 'bg-destructive text-destructive-foreground',
        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 px-3',
        lg: 'h-11 px-8',
      },
    },
    defaultVariants: { variant: 'default', size: 'default' },
  }
)

// asChild コンポジションを使用した Radix ダイアログ
import { Dialog } from 'radix-ui'

<Dialog.Root>
  <Dialog.Trigger asChild>
    <Button>Open</Button>
  </Dialog.Trigger>
  <Dialog.Portal>
    <Dialog.Overlay className="fixed inset-0 bg-black/50" />
    <Dialog.Content className="data-[state=open]:animate-in">
      <Dialog.Title>Title</Dialog.Title>
      <Dialog.Description>Description</Dialog.Description>
      <Dialog.Close>Close</Dialog.Close>
    </Dialog.Content>
  </Dialog.Portal>
</Dialog.Root>

shadcn/ui

CVA バリアント、cn() ユーティリティ、OKLCH テーマ設定を使用して構築された、美しくアクセス可能なコンポーネント。

ルール	ファイル	キー パターン
カスタマイズ	rules/shadcn-customization.md	CVA バリアント、cn() ユーティリティ、OKLCH テーマ設定、コンポーネント拡張
フォーム	rules/shadcn-forms.md	フォーム フィールド ラッパー、react-hook-form 統合、バリデーション
データ テーブル	rules/shadcn-data-table.md	TanStack Table 統合、列定義、ソート/フィルタリング
v4 スタイル	rules/shadcn-v4-styles.md	6 つのスタイル (Vega→Luma)、プリセット コード、スタイル検出、クラス マッピング

v4 スタイル システム

shadcn CLI v4 は 6 つのビジュアル スタイルを搭載。各スタイルは CSS 変数だけでなく、コンポーネント クラス名を書き直します。

スタイル	特徴	最適な用途
Vega	バランスの取れた半径、クリーンなライン	一般的な用途 (New York の後継)
Nova	コンパクトなパディング、削減されたマージン	密集したダッシュボード、管理パネル
Maia	ソフトでラウンド、広々とした間隔	消費者向け、フレンドリーなアプリ
Lyra	シャープ、ゼロ半径、モノスペース ペアリング	編集関連、デベロッパー ツール
Mira	極限までコンパクト、最小限のクローム	スプレッドシート、データ集約インターフェース
Luma	極限のラウンディング (rounded-4xl)、ソフト エレベーション (shadow-md + ring)、呼吸できるレイアウト	ポリッシュされたネイティブ アプリ風、macOS Tahoe インスパイア

ui.shadcn.com/create でビジュアル設定 → スタイル、テーマ、フォント、アイコンを選択 → 生成されたコマンドをコピー。ドキュメントでプリセット コードをハードコードしないでください — 特定のスタイル スナップショットに結びついており、ずれる可能性があります。

shadcn CLI v4 (2026 年 4 月) — 新しいコマンド

コマンド	目的
npx shadcn@latest apply <style>	公開スタイル (例: luma、nova、lyra) を現在のプロジェクトに適用 — 既存コンポーネントを再スキンしても再追加しない
npx shadcn@latest info	解決済みコンフィグを表示: レジストリ、スタイル、トークン、存在するコンポーネント、Tailwind バージョン
npx shadcn@latest skills	shadcn/skills レジストリをリスト表示 — Claude Code と Cursor 対応のスキル パック、CLI コマンドとエージェント ガイダンスをバンドル
npx shadcn@latest build	カスタム レジストリをビルド (既にドキュメント化) — apply とペアリングしてプライベート スタイルを配布

検出: components.json → "style" フィールドを読み込む (例: "radix-luma"、"base-nova")。旧 "new-york" と "default" スタイルは Vega に置き換えられました。

Radix Primitives

高品質デザイン システムを構築するための、スタイルなし、アクセス可能な React プリミティブ。

ルール	ファイル	キー パターン
ダイアログ	rules/radix-dialog.md	Dialog、AlertDialog、制御状態、アニメーション
コンポジション	rules/radix-composition.md	asChild、Slot、ネストされたトリガー、ポリモーフィック レンダリング
スタイリング	rules/radix-styling.md	データ属性、Tailwind 任意バリアント、フォーカス管理

キー判断事項

判断事項	推奨事項
カラー形式	知覚的に均一なテーマ設定のための OKLCH
クラス マージ	Tailwind コンフリクト用に常に cn() を使用
コンポーネント拡張	ソース ファイルを変更するのではなく、ラップして拡張
バリアント	型安全なマルチ軸バリアント用に CVA を使用
スタイリング アプローチ	データ属性 + Tailwind 任意バリアント
コンポジション	ラッパー div を避けるために asChild を使用
アニメーション	data-state セレクタ付き CSS のみ
フォーム コンポーネント	react-hook-form と組み合わせる

アンチパターン (禁止)

• shadcn ソースの変更: 生成されたファイルを編集するのではなく、ラップして拡張
• cn() をスキップ: 直接文字列連結は Tailwind クラス コンフリクトを引き起こす
• CVA の代わりにインライン スタイル: 型安全で再利用可能なバリアント用に CVA を使用
• ラッパー div: 余分な DOM 要素を避けるために asChild を使用
• Dialog.Title の欠落: すべてのダイアログはアクセス可能なタイトルを持つ必要がある
• 正の tabindex: tabindex > 0 を使用すると自然なタブ順序が中断される
• カラー のみの状態: データ属性 + 複数のインジケータを使用
• 手動フォーカス管理: Radix の組み込みフォーカス トラッピングを使用

詳細なドキュメント

リソース	説明
scripts/	テンプレート: CVA コンポーネント、拡張ボタン、ダイアログ、ドロップダウン
checklists/	shadcn セットアップ、アクセシビリティ監査チェックリスト
references/	CVA システム、OKLCH テーマ設定、cn() ユーティリティ、フォーカス管理

デザイン システム

デザイン トークン アーキテクチャ、間隔、タイポグラフィ、インタラクティブ コンポーネント状態。

ルール	ファイル	キー パターン
トークン アーキテクチャ	rules/design-system-tokens.md	W3C トークン、OKLCH カラー、Tailwind @theme
間隔スケール	rules/design-system-spacing.md	8px グリッド、Tailwind space-1 から space-12
タイポグラフィ スケール	rules/design-system-typography.md	フォント サイズ、ウェイト、行の高さ
コンポーネント状態	rules/design-system-states.md	ホバー、フォーカス、アクティブ、無効、読み込み中、アニメーション プリセット

デザイン システム コンポーネント

アトミック デザインとアクセシビリティを備えたコンポーネント アーキテクチャ パターン。

ルール	ファイル	キー パターン
コンポーネント アーキテクチャ	rules/design-system-components.md	アトミック デザイン、CVA バリアント、WCAG 2.1 AA、Storybook

フォーム

Zod バリデーションと React 19 Server Actions を備えた React Hook Form v7。

ルール	ファイル	キー パターン
React Hook Form	rules/forms-react-hook-form.md	useForm、フィールド配列、Controller、ウィザード、ファイル アップロード
Zod と Server Actions	rules/forms-validation-zod.md	Zod スキーマ、Server Actions、useActionState、非同期バリデーション

モダン CSS とツール

モダン CSS パターン、Tailwind v4、2026 年向けコンポーネント ドキュメント ツール。

ルール	ファイル	キー パターン
CSS カスケード レイヤー	rules/css-cascade-layers.md	@layer 順序、特異性フリー オーバーライド、サードパーティ分離
Tailwind v4	rules/tailwind-v4-patterns.md	CSS ファースト @theme、ネイティブ コンテナ クエリ、@max-* バリアント
Storybook ドキュメント	rules/storybook-component-docs.md	CSF3 ストーリー、play() インタラクション テスト、Chromatic ビジュアル レグレッション

UX ファンデーション

認知科学に基づく UI/UX 原則、本番品質インターフェースの具体的な数値閾値。

ルール	ファイル	キー パターン
ビジュアル階層	rules/visual-hierarchy.md	ボタン ティア、デ エンファシス、F/Z スキャン、Von Restorff、近接性、最大幅
タイポグラフィ閾値	rules/typography-thresholds.md	65ch 行長、1.4–1.6 行の高さ、rem ユニット、モジュール型スケール
カラー システム	rules/color-system.md	OKLCH 9 シェード スケール、セマンティック カテゴリー、純粋な黒なし、ブランド ティント ニュートラル
空の状態	rules/empty-states.md	スケルトン ファースト、アイコン + ヘッドライン + 説明 + CTA、原因固有のトーン

関連スキル

• ork:accessibility - WCAG コンプライアンスと React Aria パターン
• ork:testing-unit - コンポーネント テスト パターン