moai-domain-uiux

クイックリファレンス

コア UI/UX 基盤 — デザインシステム（W3C DTCG 2025.10）、コンポーネントアーキテクチャ（React 19、Vue 3.5）、アクセシビリティ（WCAG 2.2）、アイコンライブラリ（20 万以上のアイコン）、テーマシステムを統合した、エンタープライズグレードの UI/UX 基盤です。

統合機能：

• デザインシステム：W3C DTCG 2025.10 トークン、Style Dictionary 4.0、Pencil MCP ワークフロー
• コンポーネントアーキテクチャ：Atomic Design、React 19、Vue 3.5、shadcn/ui、Radix UI プリミティブ
• アクセシビリティ：WCAG 2.2 AA/AAA 準拠、キーボードナビゲーション、スクリーンリーダー向け最適化
• アイコンライブラリ：10 以上のエコシステム（Lucide、React Icons 3 万 5 千以上、Tabler 5900 以上、Iconify 20 万以上、Hugeicons 2 万 7 千以上）
• テーマ設定：CSS 変数、ライト／ダークモード、テーマプロバイダー、ブランドのカスタマイズ

使用する場面：

• デザインシステムを基盤とする最新の UI コンポーネントライブラリの構築
• アクセシブルなエンタープライズグレードのユーザーインターフェイスの実装
• マルチプラットフォームプロジェクト向けのデザイントークンアーキテクチャのセットアップ
• バンドルサイズを最適化した包括的なアイコンシステムの統合
• ダークモードに対応したカスタマイズ可能なテーマシステムの作成

モジュール構成：

• コンポーネント：modules/component-architecture.md（Atomic Design、コンポーネントパターン、props API）
• デザインシステム：modules/design-system-tokens.md（DTCG トークン、Style Dictionary、Pencil MCP）
• アクセシビリティ：modules/accessibility-wcag.md（WCAG 2.2 準拠、テスト、ナビゲーション）
• アイコン：modules/icon-libraries.md（10 以上のライブラリ、選択ガイド、パフォーマンス最適化）
• テーマ設定：modules/theming-system.md（テーマシステム、CSS 変数、ブランドのカスタマイズ）
• Web インターフェイスガイドライン：modules/web-interface-guidelines.md（Vercel Labs による包括的な UI/UX 準拠、フロントエンド構成ルール）
• 例：examples.md（実践的な実装例）
• リファレンス：reference.md（外部ドキュメントへのリンク）

---

実装ガイド

基盤スタック

コアテクノロジー：

• Server Components と Concurrent Rendering を備えた React 19
• 完全な型安全性と改善された型推論を備えた TypeScript 5.9+
• CSS ファーストの設定、CSS 変数、ダークモードを備えた Tailwind CSS 4.x
• スタイルを持たないアクセシブルなプリミティブ向けの Radix UI
• デザイントークン仕様向けの W3C DTCG 2025.10
• トークン変換向けの Style Dictionary 4.0
• デザインからコードへの自動化向けの Pencil MCP
• コンポーネントドキュメント向けの Storybook 8.x

クイック判断ガイド：

デザイントークンには、DTCG 2025.10 と Style Dictionary 4.0 を使用する modules/design-system-tokens.md を参照してください。

コンポーネントパターンには、Atomic Design、React 19、shadcn/ui を使用する modules/component-architecture.md を参照してください。

アクセシビリティには、WCAG 2.2、jest-axe、キーボードナビゲーションを使用する modules/accessibility-wcag.md を参照してください。

アイコンには、Lucide、React Icons、Tabler、Iconify、Hugeicons を使用する modules/icon-libraries.md を参照してください。

Nova プリセットとデザインプリセットには、moai-design-tools スキルを使用してください（reference/pencil-renderer.md）。

テーマ設定には、CSS 変数と Theme Provider を使用する modules/theming-system.md を参照してください。

実践的な例には、React と Vue の実装を使用する examples.md を参照してください。

---

クイックスタートワークフロー

デザインシステムのセットアップ

ステップ 1：DTCG スキーマ URL を含む JSON ファイルを作成して、デザイントークンを初期化します。型を color、値を primary 500 とするカラー token を定義します。型を dimension、値を 1rem とする md を持つスペーシング token を定義します。

ステップ 2：パッケージをインストールしてビルドコマンドを実行し、Style Dictionary でトークンを変換します。

ステップ 3：tokens ディレクトリからカラーとスペーシングをインポートして、コンポーネントに統合します。

トークンアーキテクチャの詳細については、modules/design-system-tokens.md を参照してください。

コンポーネントライブラリのセットアップ

ステップ 1：init コマンドを実行して shadcn/ui を初期化し、button、form、dialog の各コンポーネントを追加します。

ステップ 2：Atomic Design の構造を設定し、Button、Input、Label コンポーネント用の atoms ディレクトリ、FormGroup、Card コンポーネント用の molecules ディレクトリ、DataTable、Modal コンポーネント用の organisms ディレクトリを作成します。

ステップ 3：インタラクティブ要素に aria-label 属性を追加して、アクセシビリティに配慮した実装を行います。

パターンと使用例については、modules/component-architecture.md を参照してください。

アイコンシステムの統合

ステップ 1：用途に基づいてアイコンライブラリを選択します。汎用用途には lucide-react、最大限の種類が必要な場合は iconify/react、ダッシュボードに最適化する場合は tabler/icons-react をインストールします。

ステップ 2：特定のアイコンをインポートし、サイズと色に className を適用して、型安全なアイコンを実装します。

ライブラリの比較と最適化については、modules/icon-libraries.md を参照してください。

テーマシステムのセットアップ

ステップ 1：root セレクターで CSS 変数を設定し、プライマリカラーと背景色を指定します。ダークモード用に、値を反転させた dark クラスを定義します。

ステップ 2：attribute に class、defaultTheme に system を設定し、アプリケーションを Theme Provider でラップして実装します。

テーマシステム全体については、modules/theming-system.md を参照してください。

---

主要な原則

デザイントークンを第一に：

• デザイン上の判断に関する信頼できる唯一の情報源
• blue-500 ではなく color.primary.500 形式のセマンティックな命名
• ライトモードとダークモードのマルチテーマ対応
• プラットフォームに依存しない変換

デフォルトでアクセシビリティに配慮：

• 最低限 WCAG 2.2 AA に準拠し、テキストコントラスト比は 4.5:1
• すべてのインタラクティブ要素でキーボード操作に対応
• スクリーンリーダー向けの ARIA 属性
• フォーカス管理と視認できるインジケーター

コンポーネントの構成：

• Atoms から Molecules、Organisms へと続く Atomic Design の階層
• 再利用可能な Props API
• コンポーネントを分けるのではなく、バリアントベースのスタイリング
• TypeScript による型安全性

パフォーマンスの最適化：

• すべてのアイコンではなく、特定のアイコンをインポートしてツリーシェイキングを行う
• 大きなコンポーネントの遅延読み込み
• コストの高いレンダリングに React.memo を使用
• バンドルサイズの監視

---

ベストプラクティス

必須のプラクティス：

すべての色、間隔、タイポグラフィの値には、デザイントークンのみを使用します。デザイントークンは信頼できる唯一の情報源となり、一貫したテーマ設定、マルチプラットフォーム対応、拡張可能なデザインシステムを実現します。値をハードコードすると、保守コストが増大し、テーマの切り替えにも支障をきたします。

アイコンのみのインタラクティブ要素には、すべて ARIA ラベルを付けます。テキストによる代替手段がなければ、スクリーンリーダーは視覚的なアイコンを解釈できません。ARIA ラベルがないと、WCAG 2.2 AA 準拠に違反します。

名前空間インポートではなく、アイコンを個別にインポートします。名前空間インポートではライブラリ全体がバンドルされ、ツリーシェイキングによる最適化の効果が失われます。アイコンライブラリごとに、バンドルサイズが 500KB～2MB 増加します。

すべてのコンポーネントをライトモードとダークモードの両方でテストします。テーマの切り替えは、色のコントラスト、読みやすさ、アクセシビリティへの準拠に影響します。

すべてのインタラクティブコンポーネントでキーボード操作を実装します。キーボードのみを使用するユーザーが必要とする Tab、Enter、Escape、Arrow キーの操作に対応します。

フォーカス可能な要素には、すべて視認できるフォーカスインジケーターを設けます。フォーカスインジケーターにより、操作とアクセシビリティのために、現在のキーボード位置がわかります。

インラインスタイルではなく、Tailwind のユーティリティクラスを使用します。Tailwind は、一貫した間隔のスケール、レスポンシブデザイン、最適なバンドルサイズを実現する自動パージを提供します。

すべての非同期処理にローディング状態を含めます。ローディング状態はデータ取得中にフィードバックを提供し、ユーザーの不安を防ぎます。

---

適切な連携先

スキル：

• moai-lang-typescript - TypeScript と JavaScript のベストプラクティス
• moai-foundation-core - TRUST 5 品質検証
• moai-library-nextra - ドキュメント生成
• moai-library-shadcn - shadcn/ui に特化したパターン

エージェント：

• code-frontend - フロントエンドコンポーネントの実装
• design-uiux - デザインシステムのアーキテクチャ
• mcp-pencil - Pencil MCP のデザインワークフロー
• core-quality - アクセシビリティと品質の検証

コマンド：

• /moai:2-run - DDD 実装サイクル
• /moai:3-sync - ドキュメント生成

---

リソース

モジュールの詳細なドキュメントについては、modules ディレクトリを参照してください。

実用的なコード例については、examples.md を参照してください。

外部ドキュメントへのリンクについては、reference.md を参照してください。

公式リソース：

• W3C DTCG: https://designtokens.org
• WCAG 2.2: https://www.w3.org/WAI/WCAG22/quickref/
• React 19: https://react.dev
• Tailwind CSS: https://tailwindcss.com
• Radix UI: https://www.radix-ui.com
• shadcn/ui: https://ui.shadcn.com
• Storybook: https://storybook.js.org
• Pencil: https://docs.pencil.dev
• Style Dictionary: https://styledictionary.com
• Lucide Icons: https://lucide.dev
• Iconify: https://iconify.design
• Vercel Web Interface Guidelines: https://github.com/vercel-labs/web-interface-guidelines

---

最終更新日：2026-03-11 ステータス：本番環境対応済み バージョン：3.0.0

よくある合理化

合理化	実情
「アクセシビリティはあれば望ましいもので、必須ではない」	多くの地域で、WCAG への準拠は法的要件です。また、アクセシビリティは中核となる品質要素であり、任意ではありません。
「ダークモードは色を反転するだけ」	単純な反転では、コントラスト比、画像の視認性、意味を持つ色の意味が損なわれます。ダークモードはデザイン上の取り組みです。
「デザインシステムは制約が多すぎるので、独自のスタイルが必要だ」	デザインシステムを迂回する独自スタイルは、一貫性を損ないます。システムを回避するのではなく、拡張してください。
「アイコンにはラベルは不要で、見ればわかる」	アイコンは文脈がなければ曖昧です。スクリーンリーダーはラベルのないアイコンを説明できません。必ず aria-label を追加してください。
「レスポンシブデザインは最後に対応すればよい」	後からレスポンシブ対応を行うと、レイアウトが崩れます。まず最小のビューポート向けにデザインし、その後で拡張してください。

危険信号

• インタラクティブ要素に視認可能なフォーカスインジケーターがない
• 通常のテキストのカラーコントラスト比が 4.5:1 未満
• aria-label または付随するテキストなしでアイコンを使用している
• ハードコードされた色や余白の値によってデザイントークンを迂回している
• 新しいコンポーネントにダークモード用のバリエーションが定義されていない
• 新しいレイアウトコンポーネントにレスポンシブブレークポイントがない

検証

• カラーコントラストが WCAG AA を満たしている（通常のテキストは 4.5:1、大きなテキストは 3:1）（コントラストチェックの出力を表示する）
• すべてのインタラクティブ要素に視認可能なフォーカスインジケーターがある
• アイコンにアクセシブルな名前がある（aria-label または視認可能な付随テキスト）
• 色、余白、タイポグラフィにデザイントークンを使用している（ハードコードされた値がない）
• コントラストの破綻や要素の非表示がなく、ダークモードが正しく表示される
• モバイル（320px）、タブレット（768px）、デスクトップ（1280px）の幅でレイアウトをテストしている