Headless UI Principles

概要

ヘッドレスUIは、ロジックとUIの表現を完全に分離するアーキテクチャパターン。 Radix UI、Headless UI、React Ariaなどを活用し、アクセシビリティを確保しながら完全なスタイル制御を実現する。

ワークフロー

Phase 1: 要件分析と設計方針決定

目的: ヘッドレスUI導入の適切性を判断し、アーキテクチャ方針を確定

アクション:

1. コンポーネントの機能要件を整理
2. アクセシビリティ要件（WCAGレベル）を確認
3. references/library-comparison.md でライブラリを比較選定
4. references/aria-patterns.md で必要なWAI-ARIAパターンを特定

Task: agents/analyze-requirements.md を参照

Phase 2: コンポーネント実装

目的: ヘッドレスUI原則に従ってコンポーネントを実装

アクション:

1. assets/headless-component-template.tsx を基にコンポーネント設計
2. assets/headless-hook-template.ts で状態管理ロジックを抽出
3. WAI-ARIAパターンに基づきロール・属性を設定
4. キーボード操作とフォーカス管理を実装

Task: agents/implement-component.md を参照

Phase 3: アクセシビリティ検証

目的: WCAG準拠を確認し、品質を保証

アクション:

1. scripts/check-a11y.mjs で自動検証
2. キーボード操作のみでのナビゲーション確認
3. スクリーンリーダーでの読み上げテスト
4. scripts/log_usage.mjs で使用記録

Task: agents/verify-accessibility.md を参照

Task仕様ナビ

詳細仕様: 各Taskの詳細は agents/ ディレクトリの対応ファイルを参照

ベストプラクティス

すべきこと

• ロジックと表現を完全に分離（カスタムフック/コンテキスト活用）
• WAI-ARIAパターンに準拠したロール・属性設定
• キーボード操作をすべての機能で実装
• フォーカスインジケータを常に可視化
• TypeScript型定義で型安全性を確保
• スタイルはAPI経由で完全に制御可能に

避けるべきこと

• ライブラリのデフォルトスタイルをそのまま使用
• 比較検討なしのライブラリ選定
• アクセシビリティの後付け実装
• キーボード操作不可の機能
• スクリーンリーダー未対応

リソース参照

references/（詳細知識）

scripts/（決定論的処理）

assets/（テンプレート）

変更履歴