gluestack-ui-v4

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

このスキルでは、gluestack-ui v4 の制約に基づく明確なスタイリングパターンを適用します。これにより、選択に伴う負担を軽減し、パフォーマンスを向上させ、一貫したテーマ設定を可能にするとともに、解決策を標準パターンに限定します。

基本原則

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://v4.gluestack.io/ui/docs/components/${componentName}/ で最新の使用パターンを確認してください

サブスキルの構成

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

1. gluestack-ui-v4:setup

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

対象内容：

• 公式 CLI の使用（npx gluestack-ui@alpha init -y と npx gluestack-ui@alpha add --all -y）
• Expo、React Native CLI、Next.js 向けのプロジェクト初期化
• 依存関係の管理
• 設定ファイル（tailwind、metro、babel など）
• GluestackUIProvider のセットアップ
• 個別コンポーネントの追加
• セットアップに関する問題のトラブルシューティング

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

2. gluestack-ui-v4:creating-components

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

対象内容：

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

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

3. gluestack-ui-v4:components

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

対象内容：

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

次の場合に呼び出します： コンポーネントの構造、props、合成を扱うとき

4. gluestack-ui-v4:styling

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

対象内容：

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

次の場合に呼び出します： コンポーネントのスタイリング、テーマ設定、または色やスペーシングを扱うとき

5. gluestack-ui-v4:variants

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

対象内容：

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

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

6. gluestack-ui-v4:performance

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

対象内容：

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

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

7. gluestack-ui-v4:validation

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

対象内容：

• 完全な検証チェックリスト
• 避けるべきアンチパターン
• よくある間違い
• エスカレーションの指針

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

クイックリファレンス

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

1. コンポーネントの props - 組み込みの props（size、variant、space）を使用します
2. className ユーティリティ - 既存の Tailwind/NativeWind クラスを使用します
3. Gluestack コンポーネントのバリアント - 組み込みのコンポーネントバリアントを使用します
4. tva（Tailwind Variant Authority） - 再利用可能なバリアントパターンを作成します
5. NativeWind interop - サードパーティ製コンポーネントで className を有効にします
6. インラインスタイル - 文書化された正当な理由がある場合に限り、最終手段として使用します

一般的なパターン

// 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 のラッパーを使用します

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

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

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

サブスキルの使用方法

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

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

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