better-loading-ux

<!-- Generated by scripts/agent-pipeline/sync-pipeline.mjs. Edit private/agent-pipeline/skills/*.md instead. -->

Output Language Contract

• ユーザーに見える説明・質問・選択肢は、自然で分かりやすい日本語で書く。
• 内部の変数名、hook 名、checkpoint 名、artifact 名は、ユーザー判断に必要な場合だけ短く示す。
• 確認が必要なときは、何を判断するのか、選ぶと何が起きるのか、推奨はどれかを明示する。
• 機械判定用の enum や file:line は残してよいが、説明文とは混ぜない。

Better Loading UX

就活Pass のローディング体験を、実装済みの UI 基盤に合わせて改善する。

判断基準

• 0.1 秒未満で終わる処理には、視覚的なローディング表示を出さない。
• 1 秒以内の短時間処理は、フリッカー防止を優先する。
• 1 秒から 10 秒程度の処理は、実画面と同じ寸法のスケルトンを使う。
• 10 秒を超え得る処理は、段階的な説明、再試行、完了通知、失敗通知を設計する。

既存基盤

• src/hooks/useDelayedLoadingFlag.ts: 会話系の短時間ローディング表示を 150ms 遅延 + 300ms 最小表示で制御する。
• src/components/ui/skeleton.tsx: スケルトンプリミティブ。shimmerDelayMs で兄弟要素の光り方をずらす。
• src/components/skeletons/: 画面別スケルトン。実コンテンツと同じ余白、列数、高さを保つ。
• src/app/**/loading.tsx: Next.js ルート遷移のローディング表示。追加の遅延フックは原則不要。
• src/app/globals.css: View Transition と reduced motion の共通スタイル。

過去の設計メモにある旧 hook 名を新規前提にしない。必要なら現行コードを確認し、既存の useDelayedLoadingFlag、画面固有 state、ProcessingSteps、通知処理を組み合わせる。

ワークフロー

1. 対象操作を即時、短時間、中時間、長時間に分類する。
2. 既存画面の skeleton、loading.tsx、処理中表示、通知を確認する。
3. スケルトンは実コンテンツと寸法を合わせ、レイアウト移動を起こさない。
4. 外部 I/O や AI 処理は、処理中、完了、失敗、再試行まで設計する。
5. アニメーションは prefers-reduced-motion に従う。
6. UI 変更後は対象 route の横スクロール、重なり、表示崩れを確認する。

実装パターン

短時間ローディング

import { useDelayedLoadingFlag } from "@/hooks/useDelayedLoadingFlag";

function ConversationPanel({ isLoading }: { isLoading: boolean }) {
  const showLoading = useDelayedLoadingFlag(isLoading);

  return showLoading ? <ConversationWorkspaceShellSkeleton /> : <ConversationContent />;
}

ルート遷移

import { ExampleSkeleton } from "@/components/skeletons/ExampleSkeleton";

export default function Loading() {
  return <ExampleSkeleton />;
}

長時間処理

• 既存の処理中コンポーネントや ProcessingSteps を優先して使う。
• 固定文だけの spinner で放置しない。
• タイムアウト、失敗通知、再試行導線を API の失敗処理と合わせる。

確認項目

• 0.1 秒未満で消えるローディング UI がない。
• skeleton と実コンテンツの高さ、幅、余白、グリッド数が一致している。
• CLS が増える差し替えになっていない。
• 10 秒超の可能性がある処理に、説明、失敗、再試行がある。
• prefers-reduced-motion 時に不要な動きが止まる。
• npm run lint:ui:guardrails と必要な route の npm run test:ui:review -- <route> を実行できる状態になっている。