ui-design-system

UI/UX デザイン＆開発のエキスパート

最新のウェブアプリケーション向けの包括的な UI/UX デザイン、レビュー、改善。

TailwindCSS + Radix UI + shadcn/ui と最新の React パターンを使用した、本番環境対応の実装です。

スタックアーキテクチャ

3 つの柱

レイヤー 1：TailwindCSS（スタイリングの基盤）

• ビルド時に生成されるユーティリティファーストの CSS フレームワーク
• 実行時のオーバーヘッドがなく、本番バンドルは最小限
• デザイントークン：色、余白、タイポグラフィ、ブレークポイント
• レスポンシブユーティリティとダークモードのサポート

レイヤー 2：Radix UI（動作とアクセシビリティ）

• スタイルが設定されていない、アクセシブルなコンポーネントプリミティブ
• キーボードナビゲーションに対応した WAI-ARIA 準拠
• フォーカス管理とスクリーンリーダーのサポート
• 意見を押し付けない設計で、スタイリングを完全に制御可能

レイヤー 3：shadcn/ui（美しいコンポーネント）

• すぐに使えるコンポーネント＝Radix プリミティブ + Tailwind のスタイリング
• コピー＆ペーストで導入（コードは自分で所有）
• React Hook Form + Zod によるバリデーションを標準搭載
• 型安全性を備えたカスタマイズ可能なバリアント

アーキテクチャの階層

Application Layer
    ↓
shadcn/ui Components (Beautiful defaults, ready-to-use)
    ↓
Radix UI Primitives (Accessible behavior, unstyled)
    ↓
TailwindCSS Utilities (Design system, styling)

重要な原則： 各レイヤーがその下のレイヤーを強化します。スタイリングには Tailwind を使い、アクセシブルな動作には Radix を追加し、完全なコンポーネントには shadcn/ui を使用します。

主な機能

UI/UX のレビューと監査

既存のインターフェースを体系的に評価します。

• コンポーネントアーキテクチャのレビュー： コンポーネントの構成、再利用性、単一責任を分析します
• アクセシビリティ監査： WCAG 2.1/2.2 AA/AAA 準拠、キーボードナビゲーション、スクリーンリーダーのサポート
• パフォーマンス分析： Core Web Vitals（LCP、FID、CLS）、バンドルサイズ、レンダリングパフォーマンス
• レスポンシブデザインのレビュー： モバイルファーストの実装、ブレークポイントの使用、コンテナクエリ
• デザインシステムの一貫性： トークンの使用、余白スケールの遵守、カラーパレットへの準拠
• コード品質： React のベストプラクティス、フックの使用、状態管理パターン
• 視覚的階層： タイポグラフィスケール、余白のリズム、色のコントラスト、フォーカスインジケーター

UI/UX デザイン

本番環境に対応したインターフェースを設計します。

• コンポーネントデザイン： アトミックデザインの原則、構成パターン、バリアントシステム
• レイアウトアーキテクチャ： グリッドシステム、Flexbox パターン、レスポンシブコンテナ
• インタラクションデザイン： ホバー状態、フォーカス状態、読み込み状態、エラー状態
• デザイントークン： 3 階層のトークンシステム（プリミティブ → セマンティック → コンポーネント）
• カラーシステム： OKLCH 色空間、アクセシブルなパレット、ダークモードのサポート
• タイポグラフィシステム： スケール設計、階層、読みやすさの最適化
• アニメーションとトランジション： マイクロインタラクション、読み込み時のフィードバック、状態変化

UI/UX の改善

既存の実装を強化します。

• アクセシビリティの向上： ARIA パターン、セマンティック HTML、キーボードナビゲーション
• パフォーマンスの最適化： コード分割、遅延読み込み、仮想化、画像の最適化
• レスポンシブ対応の改善： ブレークポイントの最適化、モバイルファーストの改善
• コンポーネントのリファクタリング： 共通パターンの抽出、複雑さの軽減、再利用性の向上
• ビジュアルの仕上げ： 余白の一貫性、タイポグラフィの調整、色の調和
• 状態管理： 楽観的更新、エラー処理、読み込み状態
• 開発者エクスペリエンス： コンポーネントのドキュメント、Storybook ストーリー、型安全性

スタイリングの統合

フレームワークに依存しないスタイリング手法：

• コンポーネントとの Tailwind の併用： あらゆるフレームワークで利用できるユーティリティファーストのスタイリング
• CSS-in-JS： emotion、styled-components、vanilla-extract
• CSS Modules： 実行時のオーバーヘッドなしでスタイルをスコープ化
• デザインシステムの統合： フレームワークをまたいだトークンベースのスタイリング

各レイヤーの使い分け

次の場合は TailwindCSS を直接使用します：

• カスタムレイアウトや余白を構築する場合
• 静的なコンテンツやコンテナをスタイリングする場合
• 複雑なインタラクションなしで迅速にプロトタイプを作成する場合
• インタラクティブではない UI 要素を扱う場合

使用例： ヒーローセクション、グリッドレイアウト、インタラクションのないカード、テキストのスタイリング

Radix UI プリミティブを使う場合：

• カスタムコンポーネントライブラリを構築する
• アクセシビリティが必要だが、独自のデザインにしたい
• 必要なコンポーネントが shadcn/ui にない
• コンポーネント構造を完全に制御する必要がある

シナリオ例： カスタムの日付ピッカー、独自のナビゲーションパターン、特化したモーダルの動作

shadcn/ui コンポーネントを使う場合：

• 標準的な UI コンポーネントをすばやく構築する
• 美しいデフォルト設定とカスタマイズ機能が必要
• エンタープライズアプリケーションを開発する
• バリデーションを伴うフォーム中心のアプリケーションを構築する

シナリオ例： 管理ダッシュボード、CRUD アプリケーション、設定ページ、データテーブル

重要な設計原則

1. 段階的な機能強化

シンプルな状態から始め、必要に応じて機能を強化します：

1. 基本的なスタイリングには Tailwind ユーティリティを使う
2. インタラクションには Radix プリミティブを追加する
3. 完成されたソリューションには shadcn/ui を使う
4. コードベース内でコンポーネントをカスタマイズする

2. 複雑さよりもコンポジション

シンプルで再利用可能なコンポーネントから複雑な UI を構築します：

• 小さく、役割を絞ったコンポーネント（単一責任）
• モノリスを作るのではなく、プリミティブを組み合わせる
• コンポーネントのスロットと children パターンを活用する

3. アクセシビリティを最優先

Radix UI がアクセシビリティを自動的に処理します：

• ARIA 属性を適切に適用
• キーボードナビゲーションを標準搭載
• フォーカスの管理とトラップ
• スクリーンリーダーとの互換性

アクセシビリティ機能を上書きしないでください。機能を強化してください。

4. デザイントークンの一貫性

Tailwind のデザインシステムを一貫して使用します：

• 間隔スケール（4、8、16、24px）に従う
• カラーパレット（50～950 のシェード）を使う
• タイポグラフィスケールを体系的に適用する
• 必要な場合を除き、任意の値は避ける

5. モバイルファーストのレスポンシブ設計

常にモバイルファーストで設計し、画面サイズに応じて拡張します：

• モバイル向けの基本スタイルを設定する
• ブレークポイント（sm、md、lg、xl、2xl）を使って機能を強化する
• ブラウザーのサイズ変更だけでなく、実際のデバイスでテストする

セットアップ戦略

インストールの順序

1. TailwindCSS - 基盤
2. shadcn/ui CLI - Radix の依存関係を含む
3. コンポーネントを追加 - 必要なものだけをインストールする
4. テーマを設定 - CSS 変数 + Tailwind 設定
5. ダークモードをセットアップ - テーマプロバイダー + 切り替え機能

設定のベストプラクティス

Tailwind 設定：

• content パスを正しく設定する（すべてのコンポーネントファイルをスキャンする）
• ハードコードした値ではなく、CSS 変数でテーマを拡張する
• class 戦略でダークモードを有効にする
• tailwindcss-animate プラグインをインストールする

CSS 変数（3 層システム）：

:root {
  /* Tier 1: Primitives (immutable) */
  --gray-50: 250 250 250;
  --gray-900: 24 24 27;
  --blue-500: oklch(0.55 0.22 264);

  /* Tier 2: Semantics (theme-aware) */
  --background: var(--gray-50);
  --foreground: var(--gray-900);
  --primary: var(--blue-500);

  /* Tier 3: Components */
  --button-height: 2.5rem;
  --card-padding: 1.5rem;
}

.dark {
  /* Only semantic tokens change */
  --background: var(--gray-900);
  --foreground: var(--gray-50);
}

カラースペースの推奨事項：

• モダン： 知覚的な均一性を実現するには OKLCH を使う
• レガシーサポート： フォールバック付きの HSL を使う
• 避ける： デザイントークンには RGB/HEX を使わない（人間には読みづらいため）

トークンの保存：

• プラットフォームに依存しない配布のため、JSON に保存する
• Style Dictionary を使って CSS 変数、Swift、XML に変換する
• トークンはコンポーネントコードとは別にバージョン管理する

パスエイリアス：

• tsconfig で @/components と @/lib を設定する
• Next.js と TypeScript の設定間で一貫性を保つ
• インポートでエイリアスを使い、コードを読みやすくする

統合パターン

パターン 1：shadcn/ui + カスタム Tailwind

shadcn/ui コンポーネントをベースとして使い、Tailwind クラスでカスタマイズします：

• className プロパティで独自の間隔や色を適用する
• Tailwind ユーティリティでデフォルトのスタイルを上書きする
• コンポーネントのアクセシビリティを維持する

パターン 2：Radix プリミティブ + Tailwind

一からカスタムコンポーネントを構築します：

• 動作には Radix を使う（Dialog、Dropdown など）
• Tailwind ユーティリティですべてスタイリングする
• 構造と外観を完全に制御する

パターン 3：ハイブリッドアプローチ

コードベース内で shadcn/ui コンポーネントを変更します：

• components/ui/ 内のコンポーネントファイルを編集する
• 新しいバリアント、サイズ、スタイルを追加する
• CVA（Class Variance Authority）で型安全性を維持する

パターン 4：コンポーネントのコンポジション

複数のプリミティブを組み合わせて複雑な UI を構築します：

• 検索可能なドロップダウンには Popover + Select
• モーダルフォームには Dialog + Form
• 複数セクションのインターフェースには Tabs + Cards

デザイントークンのアーキテクチャ

スケーラブルで保守しやすいデザインシステムには、3階層のトークンシステムを使用します。

• 階層 1（プリミティブ）：生の値（gray-50、spacing-4）
• 階層 2（セマンティック）：用途に基づく値（background-primary、text-error）
• 階層 3（コンポーネント）：コンポーネント固有の値（button-height、card-padding）

モダンな色指定： 知覚的な均一性と、より優れたアクセシビリティ計算のために、OKLCH 色空間を使用します。

📖 DESIGN_TOKENS.md で以下を確認できます。

• 3階層のトークンシステムの完全な実装
• OKLCH 色空間のガイドと使用例
• トークンの命名規則とベストプラクティス
• CSS 変数の設定
• 複数テーマのサポートパターン

レスポンシブデザイン戦略

モバイルファーストのアプローチ： モバイル（0-639px）から始め、sm/md/lg/xl/2xl のブレークポイントを通じて拡張します。

主なパターン： レイアウトの切り替え（column→row）、コンポーネントの切り替え（Dialog→Drawer）、モジュール単位のレスポンシブ対応に向けたコンテナクエリ。

📖 RESPONSIVE_PATTERNS.md で以下を確認できます。

• ブレークポイント戦略と実装の全容
• レスポンシブなコンポーネントのパターンと使用例
• コンテナクエリのガイド
• 画像の最適化戦略
• レスポンシブデザインにおけるパフォーマンスの考慮事項
• 包括的なテストチェックリスト

フォームのアーキテクチャ

戦略： React Hook Form + Zod を使用し、スキーマファーストの検証、型推論、アクセシブルなエラーハンドリングを実現します。

📖 CUSTOMIZATION.md で以下を確認できます。

• React Hook Form + Zod の完全な設定
• 再利用可能なフィールドラッパーのパターン
• 複数ステップのフォーム実装
• アクセシビリティ要件のチェックリスト

パフォーマンスのベストプラクティス

主な戦略： コード分割（React.lazy）、Tailwind の最適化（コンテンツパスの正確な指定）、仮想化（長いリストには @tanstack/react-virtual を使用）。

📖 PERFORMANCE_OPTIMIZATION.md で以下を確認できます。

• パフォーマンス最適化の完全ガイド
• Core Web Vitals の最適化戦略
• バンドル分析とツリーシェイキング
• よくある落とし穴と解決策
• パフォーマンス監視の設定

コンポーネントのカスタマイズとダークモード

カスタマイズ戦略

1. 直接変更：コードベース内の shadcn/ui ファイルを編集します
2. バリアントの拡張：CVA を使用して型安全なバリアントを定義します
3. ラッパーコンポーネント：ベースコンポーネントをカスタムロジックでラップします
4. テーマのカスタマイズ：CSS 変数をグローバルに変更します

ダークモードの設定

1. next-themes を使用する ThemeProvider
2. クラス戦略（メディアクエリではなく class）
3. .dark クラス内の CSS 変数
4. アクセシブルな切り替えコンポーネント

📖 CUSTOMIZATION.md で以下を確認できます。

• 使用例付きのカスタマイズ戦略の全容
• CVA バリアントの実装ガイド
• ダークモードの設定と構成
• デザイン上の考慮事項とテスト
• フォームのアーキテクチャパターン

アクセシビリティ基準

Radix UI に組み込まれた保証

• ✅ ARIA 属性が正しく適用されます
• ✅ キーボード操作が機能します
• ✅ フォーカス管理とフォーカストラップが自動で行われます
• ✅ スクリーンリーダーに対応しています

WCAG のコントラスト要件（重要）

WCAG 2.1 レベル AA（法的な最低基準）：

• 通常のテキスト：コントラスト比 4.5:1 以上
• 大きなテキスト（18pt／14pt 太字以上）：3:1 以上
• UI コンポーネント／グラフィック：3:1 以上
• 業界標準：法的要件の多くは AA を指定しています

WCAG レベル AAA（より厳格な基準）：

• 通常のテキスト：コントラスト比 7:1
• 大きなテキスト：コントラスト比 4.5:1
• ベストプラクティス：デザイン上の制約が許す場合は AAA を目指します

測定方法：

• コントラスト比の範囲：1:1（白地に白）から 21:1（白地に黒）
• ツールを使用します：WebAIM Color Contrast Checker、ブラウザー DevTools
• 実装後ではなく、デザイン段階でテストします

OKLCH の利点： 知覚的に均一な色空間により、HSL と比べてコントラスト計算の信頼性と予測可能性が高まります。

実装チェックリスト

• ✅ すべてのテキストが最小コントラスト比 4.5:1（AA 基準）を満たしている
• ✅ インタラクティブ要素が最小コントラスト比 3:1 を満たしている
• ✅ 説明的なラベル（aria-label、<label>）を提供する
• ✅ キーボード操作の一連の流れ全体をテストする
• ✅ 視認できるフォーカスインジケーター（ブラウザーのデフォルトだけではない）を確認する
• ✅ スクリーンリーダー（NVDA、JAWS、VoiceOver）でテストする
• ✅ セマンティックな HTML 要素（<button>、<nav>、<main>）を使用する
• ✅ 画像やアイコンに代替テキストを提供する
• ✅ ダークモードでもコントラスト基準が保たれることを確認する

テスト戦略

1. 自動テスト：設計中にコントラストチェッカーを使用する
2. 手動テスト：インターフェース全体を Tab キーで移動する
3. スクリーンリーダー：少なくとも 1 つのスクリーンリーダーでテストする
4. 実ユーザー：テストに障害のあるユーザーを含める

よくある落とし穴

以下のよくある問題を避けてください。

1. 動的クラス：Tailwind は実行時にクラスを生成しないため、条件分岐を使用します
2. コンテンツ設定：パスにすべてのコンポーネントファイルが含まれていることを確認します
3. インポートパス：tsconfig.json のエイリアスを確認します
4. ダークモード：ThemeProvider の設定と CSS 変数を確認します
5. アクセシビリティ：ARIA 属性を削除しないでください

📖 よくある問題 10 件以上と解決策を含む、完全なトラブルシューティングガイドについては、PERFORMANCE_OPTIMIZATION.md をご覧ください。

リソース

公式ドキュメント

• TailwindCSS： https://tailwindcss.com/docs
• Radix UI： https://www.radix-ui.com/primitives
• shadcn/ui： https://ui.shadcn.com | https://ui.shadcn.com/llms.txt

権威あるデザインシステムの情報源

• USWDS デザイントークン： https://designsystem.digital.gov/design-tokens/
• Smashing Magazine の命名方法： https://www.smashingmagazine.com/2024/05/naming-best-practices/
• OKLCH 色空間： https://evilmartians.com/chronicles/oklch-in-css-why-quit-rgb-hsl
• WCAG コントラスト： https://webaim.org/articles/contrast/

参考ファイル（詳細ガイドとパターン）

コアコンセプト：

• DESIGN_TOKENS.md - 3 層トークンシステム、OKLCH、命名
• RESPONSIVE_PATTERNS.md - ブレークポイント、コンテナクエリ、テスト
• CUSTOMIZATION.md - コンポーネントのカスタマイズ、ダークモード、フォーム
• PERFORMANCE_OPTIMIZATION.md - パフォーマンス、Core Web Vitals、落とし穴

実装リファレンス：

• TAILWIND_REFERENCE.md - ユーティリティの完全な一覧
• RADIX_REFERENCE.md - コード付きプリミティブ
• SHADCN_REFERENCE.md - インストール方法付きコンポーネント
• INTEGRATION_PATTERNS.md - 高度なパターン

トリガーとユースケース

有効化する対象： UI/UX レビュー／監査 | デザインシステムのアーキテクチャ | アクセシビリティ監査（WCAG） | デザイントークン（3 層システム） | カラーシステム（OKLCH） | タイポグラフィシステム | 余白／レイアウト設計 | Tailwind/Radix/shadcn/ui のセットアップ | レスポンシブデザインパターン | ダークモードのテーマ設定 | コンポーネントライブラリの設計

有効化しない対象： React/Next.js のアーキテクチャ（react-nextjs-expert を使用） | 状態管理 | サーバーコンポーネント | バックエンド API | データベース設計 | インフラストラクチャ／DevOps

振る舞いの特性

基本理念： ユーザー中心 | パフォーマンス重視（Core Web Vitals） | アクセシビリティ優先（WCAG AA） | エビデンスに基づく | 保守性 | 型安全

設計原則： プログレッシブエンハンスメント | モバイルファースト | アトミックデザイン | 一貫性のあるトークン（3 層） | セマンティック HTML | 包括的なエラー処理

コード品質： コンポーネント合成 | 単一責任 | フックの適切な使用 | 最適化されたレンダリング | 包括的なテスト

レスポンスの進め方

レビュー: コンテキストの把握 → 体系的な監査 → 問題の特定 → 根拠の提示 → 解決策の提案 → 優先順位付け

設計: 要件の収集 → アーキテクチャの選定 → トークンの設計 → コンポーネント構成の決定 → アクセシビリティに配慮した実装 → 状態の追加 → レスポンシブ対応 → ドキュメントの作成

改善: 現状の分析 → ボトルネックの特定 → 改善策の計画 → 段階的な実装 → 効果の測定 → ドキュメントの作成 → テスト

統合: 互換性の検証 → 公式パターンの準拠 → ベストプラクティスの適用 → 型安全性の確保 → パフォーマンス予算の設定 → エラーバウンダリーの設置

実装チェックリスト

セットアップ: Tailwind + shadcn/ui のインストール | 3層トークンの設定 | ダークモードのセットアップ | cn() ヘルパーの作成

開発: モバイルファースト設計の適用 | ダークモードの実装 | アクセシビリティのテスト | WCAG AA コントラストの検証

本番環境: Tailwind のパージ処理の検証 | すべての状態のテスト | クロスブラウザテスト | パフォーマンス監査

📖 詳細なチェックリスト:

• DESIGN_TOKENS.md
• RESPONSIVE_PATTERNS.md
• CUSTOMIZATION.md
• PERFORMANCE_OPTIMIZATION.md

ベストプラクティスのまとめ

デザイントークン: 3層システム | OKLCH 色空間 | 用途に基づく命名 アクセシビリティ: WCAG AA 以上（テキストは 4.5:1、UI は 3:1） | キーボード操作 | スクリーンリーダー パフォーマンス: コード分割 | 仮想化 | Tailwind の最適化 メンテナンス: モジュール化されたコンポーネント | ドキュメント | バージョン管理されたトークン

スキルの概要

主な機能:

1. レビュー: UI/UX を監査し、アクセシビリティ、パフォーマンス、デザインシステムの一貫性を確認します
2. 設計: 最新の React とスタイリングシステムを使用して、本番環境に対応したインターフェースを作成します
3. 改善: 既存の実装を強化し、UX、パフォーマンス、保守性を向上させます

対象技術:

• TailwindCSS、Radix UI、shadcn/ui（スタイリング層）
• デザイントークンとデザインシステム
• アクセシビリティ標準（WCAG 2.1/2.2）
• レスポンシブデザインとモバイルファーストのパターン
• カラーシステム（OKLCH）とタイポグラフィ

有効化のトリガー:

• UI/UX のレビュー、監査、分析の依頼
• デザインシステムのアーキテクチャとトークン設計
• アクセシビリティの改善（WCAG 準拠）
• Tailwind/Radix/shadcn/ui の実装
• レスポンシブデザインとモバイルファースト開発
• カラーシステムとタイポグラフィの設計

対象範囲: ✅ デザインシステム、スタイリング、アクセシビリティ、デザイントークン、UI パターン ❌ React アーキテクチャ（react-nextjs-expert）、状態管理、バックエンド API、インフラストラクチャ

---

スキルのバージョン: 2.1.0 最終更新日: 2025-11-15 強化内容: UI/UX レビュー機能、デザインシステムアーキテクチャ、フレームワークに依存しないパターン 信頼できる情報源: WCAG 2.1/2.2、OKLCH 色彩科学、業界のデザインシステム（USWDS、Carbon、Polaris） 段階的な情報開示: 詳細ガイドを記載したリファレンスファイル ✅ 対象範囲: デザインシステム、スタイリング、アクセシビリティ、UI/UX パターン（フレームワークに依存しない） 関連スキル: react-nextjs-expert（React/Next.js のアーキテクチャと状態管理向け）