React UI パターン

コアの原則

1. 古いUIを表示しない - 実際にローディング中の時だけローディングスピナーを表示する
2. 常にエラーを表示する - ユーザーは何か失敗したことを知る必要がある
3. 楽観的更新 - UIを即座に反応させる
4. 段階的な情報開示 - 利用可能になったコンテンツから順に表示する
5. 段階的な機能低下 - データがないよりも部分的なデータの方が良い

ローディング状態パターン

ゴールデンルール

表示するデータがない場合のみローディングインジケーターを表示する。

// 正しい - データがない場合のみローディングを表示
const { data, loading, error } = useGetItemsQuery();

if (error) return <ErrorState error={error} onRetry={refetch} />;
if (loading && !data) return <LoadingState />;
if (!data?.items.length) return <EmptyState />;

return <ItemList items={data.items} />;

// 誤り - キャッシュされたデータがあるのにスピナーを表示する
if (loading) return <LoadingState />; // 再フェッチ時にちらつく!

ローディング状態の意思決定ツリー

エラーがあるか?
  → はい: 再試行オプション付きのエラー状態を表示
  → いいえ: 続行

ローディング中でデータがないか?
  → はい: ローディングインジケーター(スピナー/スケルトン)を表示
  → いいえ: 続行

データがあるか?
  → はい、アイテムあり: データを表示
  → はい、ただし空: 空状態を表示
  → いいえ: ローディング表示(フォールバック)

スケルトン vs スピナー

スケルトンを使用する場合	スピナーを使用する場合
コンテンツの形が既知	コンテンツの形が未知
リスト/カードレイアウト	モーダルアクション
初期ページロード	ボタン送信
コンテンツプレースホルダー	インライン操作

エラーハンドリングパターン

エラーハンドリングの階層

1. インラインエラー(フィールドレベル) → フォーム検証エラー
2. トースト通知 → 復旧可能なエラー、ユーザーが再試行可能
3. エラーバナー → ページレベルのエラー、データはまだ部分的に使用可能
4. フルエラー画面 → 復旧不可能、ユーザーアクションが必要

エラーを常に表示する

重大: エラーを静かに飲み込んではいけない。

// 正しい - エラーを常にユーザーに表示
const [createItem, { loading }] = useCreateItemMutation({
  onCompleted: () => {
    toast.success({ title: 'Item created' });
  },
  onError: (error) => {
    console.error('createItem failed:', error);
    toast.error({ title: 'Failed to create item' });
  },
});

// 誤り - エラーが静かにキャッチされ、ユーザーには何も見えない
const [createItem] = useCreateItemMutation({
  onError: (error) => {
    console.error(error); // ユーザーには何も表示されない!
  },
});

エラー状態コンポーネントパターン

interface ErrorStateProps {
  error: Error;
  onRetry?: () => void;
  title?: string;
}

const ErrorState = ({ error, onRetry, title }: ErrorStateProps) => (
  <div className="error-state">
    <Icon name="exclamation-circle" />
    <h3>{title ?? 'Something went wrong'}</h3>
    <p>{error.message}</p>
    {onRetry && (
      <Button onClick={onRetry}>Try Again</Button>
    )}
  </div>
);

ボタン状態パターン

ボタンのローディング状態

<Button
  onClick={handleSubmit}
  isLoading={isSubmitting}
  disabled={!isValid || isSubmitting}
>
  Submit
</Button>

非同期操作中に無効化する

重大: 非同期操作中は常にトリガーを無効化する。

// 正しい - ローディング中はボタンが無効化される
<Button
  disabled={isSubmitting}
  isLoading={isSubmitting}
  onClick={handleSubmit}
>
  Submit
</Button>

// 誤り - ユーザーが何度もタップできる
<Button onClick={handleSubmit}>
  {isSubmitting ? 'Submitting...' : 'Submit'}
</Button>

空状態

空状態の要件

すべてのリスト/コレクションは空状態を持つ必要がある:

// 誤り - 空状態がない
return <FlatList data={items} />;

// 正しい - 明示的な空状態
return (
  <FlatList
    data={items}
    ListEmptyComponent={<EmptyState />}
  />
);

コンテキストに応じた空状態

// 検索結果なし
<EmptyState
  icon="search"
  title="No results found"
  description="Try different search terms"
/>

// まだアイテムがないリスト
<EmptyState
  icon="plus-circle"
  title="No items yet"
  description="Create your first item"
  action={{ label: 'Create Item', onClick: handleCreate }}
/>

フォーム送信パターン

const MyForm = () => {
  const [submit, { loading }] = useSubmitMutation({
    onCompleted: handleSuccess,
    onError: handleError,
  });

  const handleSubmit = async () => {
    if (!isValid) {
      toast.error({ title: 'Please fix errors' });
      return;
    }
    await submit({ variables: { input: values } });
  };

  return (
    <form>
      <Input
        value={values.name}
        onChange={handleChange('name')}
        error={touched.name ? errors.name : undefined}
      />
      <Button
        type="submit"
        onClick={handleSubmit}
        disabled={!isValid || loading}
        isLoading={loading}
      >
        Submit
      </Button>
    </form>
  );
};

アンチパターン

ローディング状態

// 誤り - データが存在するのにスピナーを表示(ちらつきが発生)
if (loading) return <Spinner />;

// 正しい - データがない場合のみローディングを表示
if (loading && !data) return <Spinner />;

エラーハンドリング

// 誤り - エラーが飲み込まれる
try {
  await mutation();
} catch (e) {
  console.log(e); // ユーザーには何も見えない!
}

// 正しい - エラーを表示する
onError: (error) => {
  console.error('operation failed:', error);
  toast.error({ title: 'Operation failed' });
}

ボタン状態

// 誤り - 送信中はボタンが無効化されない
<Button onClick={submit}>Submit</Button>

// 正しい - 無効化されてローディングを表示
<Button onClick={submit} disabled={loading} isLoading={loading}>
  Submit
</Button>

チェックリスト

UIコンポーネントを完成させる前に:

UI状態:

• エラー状態が処理されて表示される
• ローディング状態がデータなしの場合のみ表示される
• コレクション用の空状態が提供されている
• 非同期操作中はボタンが無効化される
• 必要な場合はボタンがローディングインジケーターを表示する

データとミューテーション:

• ミューテーションにonErrorハンドラーがある
• すべてのユーザーアクションにフィードバック(トースト/ビジュアル)がある

他のスキルとの連携

• graphql-schema: 適切なエラーハンドリング付きのミューテーションパターンを使用する
• testing-patterns: すべてのUI状態(ローディング、エラー、空、成功)をテストする
• formik-patterns: フォーム送信パターンを適用する

使用時期

このスキルは概要に記載されたワークフローまたはアクションを実行するときに適用されます。

制限事項

• このスキルは上記で説明されたスコープと明確に一致するタスクの場合のみ使用してください。
• 出力を環境固有の検証、テスト、または専門家のレビューの代替として扱わないでください。
• 必要な入力、権限、安全境界、または成功基準が不明な場合は、立ち止まって説明を求めてください。