gluestack-ui-v5

Gluestack UI v5 のデザインパターン

このスキルでは、gluestack-ui v5（CSS ファースト設定を採用した Tailwind CSS v4）向けに、制約のある、明確な方針に基づくスタイリングパターンを適用します。これにより、選択に迷う負担を減らし、パフォーマンスを向上させ、一貫したテーマ設定を可能にし、解決策を標準的なパターンに限定します。スタイリングエンジンとして、NativeWind v5（Expo + RN CLI）と UniWind（Expo のみ）の両方をサポートします。

基本原則

1. React Native のプリミティブより Gluestack コンポーネントを優先 - Gluestack は RN をテーマ設定、アクセシビリティ、クロスプラットフォームでの一貫性に対応する形でラップします
2. className ユーティリティよりコンポーネントの props を優先 - 使用できる場合は、className ではなく組み込みの props（size、variant、space）を使用します
3. セマンティックトークンのみを使用し、例外は認めません - 汎用トークン（typography-*、neutral-*、gray-*）や番号付きカラー（red-500、blue-600）は絶対に使用しないでください。セマンティックトークン（text-foreground、bg-primary、border-border など）のみを、必要に応じてアルファ値と組み合わせて使用します
4. インラインスタイルより className を優先 - インラインスタイルは最適化と一貫性を損ないます
5. ピクセル値よりスペーシングスケールを優先 - 任意の値は、持続できない例外を生み出します
6. コピー＆ペーストの方針 - コンポーネントは依存関係としてインストールするのではなく、コードベースにコピーします
7. 組み合わせ可能なサブコンポーネント - 柔軟性を高めるために、複合コンポーネントパターンを使用します
8. 不要なコードを削除 - 未使用のパターンは AI を誤解させ、認知負荷を高めます

このスキルを使用する場面

• スタイル付きの新しいコンポーネントを作成する
• 既存のコンポーネントスタイルをレビューする
• デザインシステムに沿うようスタイルをリファクタリングする
• スタイルの不整合を修正する
• ダークモードへの対応を追加する
• コンポーネントにテーマを適用する
• gluestack-ui からコンポーネントをプロジェクトにコピーする

コンポーネントを使用する前に、必ず https://gluestack.io/ui/docs/components/${componentName}/ で最新の使用パターンを確認してください

サブスキルの構成

このスキルは、トークン効率を高めるため、専門分野ごとのサブスキルに分かれています。

1. gluestack-ui-v5:setup

用途： プロジェクトの初期設定、インストール、設定、コンポーネントの追加

対象項目：

• 公式 CLI の使用方法（npx gluestack-ui@latest init および npx gluestack-ui@latest add --all）
• Expo と React Native CLI 向けのプロジェクト初期化（NativeWind v5 の Web 対応待ちのため、Next.js のサポートは保留中）
• 依存関係の管理
• 設定ファイル（tailwind、metro、babel など）
• GluestackUIProvider のセットアップ
• 個別のコンポーネントの追加
• セットアップ時の問題のトラブルシューティング

次の場合に使用： 新規または既存のプロジェクトに gluestack-ui をセットアップする場合、CLI でコンポーネントを追加する場合、またはインストール時の問題をトラブルシューティングする場合

2. gluestack-ui-v5:creating-components

用途： コンポーネント作成の手順、テンプレート、レシピ

対象項目：

• コンポーネント作成のワークフロー
• すぐに使える6つのテンプレート（シンプル、バリアント、複合、フォーム、インタラクティブ、ローディング）
• よくあるコンポーネントのレシピ（プロフィールカード、バッジ、検索、リスト）
• ベストプラクティスのチェックリスト
• クイックスタートガイド

次の場合に使用： 新しいコンポーネントをゼロから作成する場合、またはコンポーネントのテンプレートが必要な場合

3. gluestack-ui-v5:components

用途： コンポーネントの使用方法、複合パターン、アイコン、プロバイダーのセットアップ

対象項目：

• React Native のプリミティブより Gluestack コンポーネントを優先する方法
• コンポーネントの props と className ユーティリティの使い分け
• 複合コンポーネントパターン（Input、Button、FormControl など）
• アイコン使用時の優先順位
• プロバイダーのセットアップ

次の場合に使用： コンポーネントの構造、props、組み合わせを扱う場合

4. gluestack-ui-v5:styling

用途： 色、スペーシング、ダークモード、バリアント、className

対象項目：

• セマンティックカラートークン
• スペーシングスケールの遵守
• CSS 変数を使用したダークモード
• tva を使用したバリアントベースのスタイリング
• className のマージ

次の場合に使用： コンポーネントのスタイリング、テーマ設定、色やスペーシングを扱う場合

5. gluestack-ui-v5:variants

用途： コンポーネント用のカスタムバリアントの作成、デザインシステムの拡張

対象：

• バリアントを作成するタイミングと方法
• バリアント管理での tva の使用
• 既存の Gluestack コンポーネントの拡張
• 親子間のバリアント関係
• 複雑な組み合わせに対応する複合バリアント
• 一般的なバリアントパターン（バッジ、アラート、カード）
• 繰り返し使用するスタイルをバリアントに変換

次の場合に呼び出します： コンポーネント用のカスタムバリアントを作成する場合、コンポーネントのスタイリングオプションを拡張する場合、または繰り返し使用するスタイルパターンを標準化する場合

6. gluestack-ui-v5:performance

用途： クロスプラットフォーム対応、パフォーマンス最適化、ベストプラクティス

対象：

• クロスプラットフォームレンダリング（Native と Web）
• TypeScript の使用
• コンポーネントのメモ化
• Reanimated によるアニメーション
• セーフエリアの処理
• リストでの FlatList の使用
• プラットフォーム固有のコード

次の場合に呼び出します： パフォーマンスを最適化する場合、クロスプラットフォーム互換性を確保する場合、または React Native のベストプラクティスに従う場合

7. gluestack-ui-v5:validation

用途： コードレビュー、アンチパターン、検証チェックリスト

対象：

• 完全な検証チェックリスト
• 避けるべきアンチパターン
• よくある間違い
• エスカレーションに関するガイダンス

次の場合に呼び出します： コードをレビューする場合、実装を検証する場合、またはアンチパターンを確認する場合

クイックリファレンス

解決の優先順位（優先度順）

1. コンポーネントの props - 組み込み props（size、variant、space）を使用します
2. className ユーティリティ - 既存の Tailwind/NativeWind クラスを使用します
3. Gluestack コンポーネントのバリアント - 組み込みのコンポーネントバリアントを使用します
4. CSS 変数（@theme inline） - Tailwind v4 は global.css のトークンをユーティリティクラスに自動的に解決します
5. tva（Tailwind Variant Authority） - 再利用可能なバリアントパターンを作成します
6. NativeWind interop - サードパーティコンポーネントで className を有効にします
7. インラインスタイル - 理由を文書化したうえで、どうしても必要な場合の最終手段としてのみ使用します

一般的なパターン

// Component usage with props
<VStack space="lg" className="p-4">
  <Heading size="xl" bold>Title</Heading>
  <Text size="md" className="text-muted-foreground">Description</Text>
</VStack>

// Button with compound components
<Button variant="outline" size="lg">
  <ButtonText>Click Me</ButtonText>
  <ButtonIcon as={ChevronRightIcon} />
</Button>

// Input with icon (InputIcon MUST be in InputSlot)
<Input>
  <InputSlot>
    <InputIcon as={MailIcon} className="text-muted-foreground" />
  </InputSlot>
  <InputField placeholder="Enter email" />
</Input>

// Semantic color tokens
<Box className="bg-primary text-primary-foreground">
  <Text className="text-foreground">Content</Text>
</Box>

主なルールのまとめ

1. React Native のプリミティブではなく、常に Gluestack コンポーネントを使用します
2. 利用できる場合は、className ではなくコンポーネントの props（space、size、variant）を使用します
3. 重要：色にはセマンティックトークンのみを使用します - typography-*、neutral-*、gray-*、slate-*、または番号付きの色（red-500、blue-600）は絶対に使用しないでください。セマンティックトークン（text-foreground、text-muted-foreground、bg-primary、bg-card、border-border など）のみを使用し、必要に応じてアルファ値（/70、/90）を指定してください
4. どうしても必要な場合を除き、インラインスタイルは使用しません
5. スペーシングスケール（0、0.5、1、2、3、4 など）に従い、任意の値は使用しません
6. 複合コンポーネントは必須です - ButtonText、InputSlot、FormControlLabel など
7. InputIcon は必ず InputSlot でラップします - これは重要です
8. 複数のスタイルを持つカスタムコンポーネントを作成する場合は、バリアントに tva を使用します
9. dark: プレフィックスを使用したダークモード - CSS 変数を使用します
10. クロスプラットフォーム互換性を確保します - React Native を直接インポートせず、Gluestack のラッパーを使用します

リファレンスドキュメント

重要：コンポーネントを使用する前に、必ず公式 v5 ドキュメントで使用方法とパターンを確認してください。

• コンポーネントドキュメント：https://gluestack.io/ui/docs/components/${componentName}/
• 完全なドキュメント：https://gluestack.io/ui/docs
• インポートパス：@/components/ui/${componentName}

サブスキルの使い方

特定のタスクに取り組む際は、詳細なガイダンスを得るために適切なサブスキルを呼び出してください。

• gluestack-ui のセットアップやコンポーネントの追加を行いますか？ → gluestack-ui-v5:setup を使用してください
• 新しいコンポーネントを作成しますか？ → gluestack-ui-v5:creating-components を使用してください
• コンポーネントの構造について質問がありますか？ → gluestack-ui-v5:components を使用してください
• スタイリングやテーマ設定について質問がありますか？ → gluestack-ui-v5:styling を使用してください
• コンポーネントのバリアントを作成または拡張しますか？ → gluestack-ui-v5:variants を使用してください
• パフォーマンスやクロスプラットフォームについて質問がありますか？ → gluestack-ui-v5:performance を使用してください
• コードの検証やレビューが必要ですか？ → gluestack-ui-v5:validation を使用してください

各サブスキルは、これらの基本原則との一貫性を保ちながら、それぞれの領域に特化した詳細なガイダンスを提供します。