From 1fa849de257c3ee748eeb09c4273ad99afa5cefa Mon Sep 17 00:00:00 2001
From: Ronald Roy <gsdwig@gmail.com>
Date: Sat, 24 Jan 2026 21:22:34 -0800
Subject: [PATCH] fix: Add skeleton loading states and entrance animations to
 HomeView widgets

Widgets now show skeleton placeholders during load instead of popping into
existence when data arrives. Changes include:

- HomeView: Track loading states for goals, activity, and inspiration
- InspirationCard: Optional quote prop, skeleton when loading or no data
- GoalsCard: Loading skeleton with shimmer animation
- SpacedRepetitionWidget: Show loading spinner immediately, idle state for
  no cards due, distinguish API errors from empty results
- RecentActivity: Loading skeleton, staggered entrance animation (50ms delay)

All animations respect prefers-reduced-motion. Tests updated accordingly.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 frontend/src/components/home/GoalsCard.css    |  82 ++++++++++++++
 frontend/src/components/home/GoalsCard.tsx    |  28 ++++-
 frontend/src/components/home/HomeView.tsx     |  96 +++++++++-------
 .../src/components/home/InspirationCard.css   |  20 ++++
 .../src/components/home/InspirationCard.tsx   |  11 +-
 .../src/components/home/RecentActivity.css    | 103 ++++++++++++++++++
 .../src/components/home/RecentActivity.tsx    |  57 +++++++++-
 .../home/SpacedRepetitionWidget.css           |  49 +++++++++
 .../home/SpacedRepetitionWidget.tsx           |  58 ++++++++--
 .../home/__tests__/HomeView.test.tsx          |   5 +-
 .../__tests__/SpacedRepetitionWidget.test.tsx |   8 +-
 11 files changed, 450 insertions(+), 67 deletions(-)

diff --git a/frontend/src/components/home/GoalsCard.css b/frontend/src/components/home/GoalsCard.css
index 27fcd414..7155a52d 100644
--- a/frontend/src/components/home/GoalsCard.css
+++ b/frontend/src/components/home/GoalsCard.css
@@ -153,3 +153,85 @@
     backdrop-filter: blur(4px);
   }
 }
+
+/* Loading skeleton */
+.goals-card--loading {
+  cursor: default;
+  pointer-events: none;
+}
+
+.goals-card__skeleton {
+  display: flex;
+  flex-direction: column;
+  gap: var(--spacing-sm);
+}
+
+.goals-card__skeleton-header {
+  width: 40%;
+  height: 0.9em;
+  background: linear-gradient(
+    90deg,
+    var(--color-surface) 25%,
+    var(--glass-border) 50%,
+    var(--color-surface) 75%
+  );
+  background-size: 200% 100%;
+  border-radius: var(--radius-sm);
+  animation: goals-shimmer 1.5s infinite;
+}
+
+.goals-card__skeleton-line {
+  width: 100%;
+  height: 0.9em;
+  background: linear-gradient(
+    90deg,
+    var(--color-surface) 25%,
+    var(--glass-border) 50%,
+    var(--color-surface) 75%
+  );
+  background-size: 200% 100%;
+  border-radius: var(--radius-sm);
+  animation: goals-shimmer 1.5s infinite;
+}
+
+.goals-card__skeleton-line--short {
+  width: 70%;
+}
+
+@keyframes goals-shimmer {
+  0% {
+    background-position: 200% 0;
+  }
+  100% {
+    background-position: -200% 0;
+  }
+}
+
+/* Entrance animation */
+@keyframes goals-enter {
+  from {
+    opacity: 0;
+    transform: scale(0.98);
+  }
+  to {
+    opacity: 1;
+    transform: scale(1);
+  }
+}
+
+.goals-card--enter {
+  animation: goals-enter 0.2s ease backwards;
+}
+
+/* Reduced motion preference */
+@media (prefers-reduced-motion: reduce) {
+  .goals-card__skeleton-header,
+  .goals-card__skeleton-line {
+    animation: none;
+    background: var(--glass-border);
+  }
+
+  .goals-card--enter {
+    animation: none;
+  }
+}
diff --git a/frontend/src/components/home/GoalsCard.tsx b/frontend/src/components/home/GoalsCard.tsx
index b49ce793..cced4aaa 100644
--- a/frontend/src/components/home/GoalsCard.tsx
+++ b/frontend/src/components/home/GoalsCard.tsx
@@ -11,6 +11,14 @@ import remarkGfm from "remark-gfm";
 import { useSession } from "../../contexts/SessionContext";
 import "./GoalsCard.css";
 
+/**
+ * Props for GoalsCard component.
+ */
+export interface GoalsCardProps {
+  /** Whether goals are still loading */
+  isLoading?: boolean;
+}
+
 /**
  * GoalsCard displays goals.md content as rendered markdown.
  *
@@ -19,7 +27,7 @@ import "./GoalsCard.css";
  * - Returns null if no goals file exists in the vault
  * - Clicking the card triggers /review-goals command
  */
-export function GoalsCard(): React.ReactNode {
+export function GoalsCard({ isLoading = false }: GoalsCardProps): React.ReactNode {
   const { goals, setDiscussionPrefill, setMode } = useSession();
 
   const handleClick = useCallback(() => {
@@ -27,7 +35,21 @@ export function GoalsCard(): React.ReactNode {
     setMode("discussion");
   }, [setDiscussionPrefill, setMode]);
 
-  // Don't render if no goals content
+  // Show skeleton during load
+  if (isLoading) {
+    return (
+      <div className="goals-card goals-card--loading" aria-label="Goals loading">
+        <div className="goals-card__skeleton">
+          <div className="goals-card__skeleton-header" />
+          <div className="goals-card__skeleton-line" />
+          <div className="goals-card__skeleton-line goals-card__skeleton-line--short" />
+          <div className="goals-card__skeleton-line" />
+        </div>
+      </div>
+    );
+  }
+
+  // Don't render if no goals content (vault might not have goalsPath)
   if (!goals) {
     return null;
   }
@@ -35,7 +57,7 @@ export function GoalsCard(): React.ReactNode {
   return (
     <button
       type="button"
-      className="goals-card"
+      className="goals-card goals-card--enter"
       onClick={handleClick}
       aria-label="Review goals"
     >
diff --git a/frontend/src/components/home/HomeView.tsx b/frontend/src/components/home/HomeView.tsx
index 5159ec0c..42b11a83 100644
--- a/frontend/src/components/home/HomeView.tsx
+++ b/frontend/src/components/home/HomeView.tsx
@@ -124,8 +124,12 @@ export function HomeView(): React.ReactNode {
   const { getGoals, getInspiration } = useHome(vault?.id);
   const { deleteSession } = useSessions(vault?.id);
 
-  // Inspiration state
+  // Loading states
   const [inspirationLoading, setInspirationLoading] = useState(true);
+  const [goalsLoading, setGoalsLoading] = useState(true);
+  const [activityLoading, setActivityLoading] = useState(true);
+
+  // Inspiration state
   const [inspirationContextual, setInspirationContextual] =
     useState<InspirationItem | null>(null);
   const [inspirationQuote, setInspirationQuote] =
@@ -154,38 +158,58 @@ export function HomeView(): React.ReactNode {
     const vaultId = vault.id;
     console.log(`[HomeView] Loading data for vault: ${vaultId}`);
 
+    // Reset loading states for new vault
+    setActivityLoading(true);
+    setGoalsLoading(true);
+    setInspirationLoading(true);
+
     // Load recent activity
-    getRecentActivity().then((activity) => {
-      console.log(`[HomeView] Recent activity loaded:`, activity);
-      if (activity) {
-        setRecentNotes(activity.captures);
-        setRecentDiscussions(activity.discussions);
-      }
-    }).catch((err) => console.error(`[HomeView] Failed to load activity:`, err));
+    getRecentActivity()
+      .then((activity) => {
+        console.log(`[HomeView] Recent activity loaded:`, activity);
+        if (activity) {
+          setRecentNotes(activity.captures);
+          setRecentDiscussions(activity.discussions);
+        }
+        setActivityLoading(false);
+      })
+      .catch((err) => {
+        console.error(`[HomeView] Failed to load activity:`, err);
+        setActivityLoading(false);
+      });
 
     // Load goals (only if vault has goalsPath)
     if (vault.goalsPath) {
-      getGoals().then((content) => {
-        console.log(`[HomeView] Goals loaded:`, content?.slice(0, 50));
-        if (content !== null) {
-          setGoals(content);
-        }
-      }).catch((err) => console.error(`[HomeView] Failed to load goals:`, err));
+      getGoals()
+        .then((content) => {
+          console.log(`[HomeView] Goals loaded:`, content?.slice(0, 50));
+          if (content !== null) {
+            setGoals(content);
+          }
+          setGoalsLoading(false);
+        })
+        .catch((err) => {
+          console.error(`[HomeView] Failed to load goals:`, err);
+          setGoalsLoading(false);
+        });
+    } else {
+      setGoalsLoading(false);
     }
 
     // Load inspiration
-    setInspirationLoading(true);
-    getInspiration().then((result) => {
-      console.log(`[HomeView] Inspiration loaded:`, result);
-      if (result) {
-        setInspirationContextual(result.contextual);
-        setInspirationQuote(result.quote);
-      }
-      setInspirationLoading(false);
-    }).catch((err) => {
-      console.error(`[HomeView] Failed to load inspiration:`, err);
-      setInspirationLoading(false);
-    });
+    getInspiration()
+      .then((result) => {
+        console.log(`[HomeView] Inspiration loaded:`, result);
+        if (result) {
+          setInspirationContextual(result.contextual);
+          setInspirationQuote(result.quote);
+        }
+        setInspirationLoading(false);
+      })
+      .catch((err) => {
+        console.error(`[HomeView] Failed to load inspiration:`, err);
+        setInspirationLoading(false);
+      });
   }, [vault?.id, getRecentActivity, getGoals, getInspiration, setRecentNotes, setRecentDiscussions, setGoals]);
 
   // Determine which debrief buttons to show (single Date for consistency)
@@ -234,23 +258,21 @@ export function HomeView(): React.ReactNode {
         )}
       </section>
 
-      {/* Inspiration */}
-      {inspirationQuote && (
-        <InspirationCard
-          contextual={inspirationContextual}
-          quote={inspirationQuote}
-          isLoading={inspirationLoading}
-        />
-      )}
+      {/* Inspiration - always rendered, shows skeleton when loading */}
+      <InspirationCard
+        contextual={inspirationContextual}
+        quote={inspirationQuote}
+        isLoading={inspirationLoading}
+      />
 
-      {/* Spaced Repetition - renders null internally when no cards due */}
+      {/* Spaced Repetition - shows idle state when no cards due */}
       <SpacedRepetitionWidget vaultId={vault?.id} />
 
       {/* Goals */}
-      <GoalsCard />
+      <GoalsCard isLoading={goalsLoading} />
 
       {/* Recent Activity */}
-      <RecentActivity onDeleteSession={handleDeleteSession} />
+      <RecentActivity isLoading={activityLoading} onDeleteSession={handleDeleteSession} />
 
       {/* Health Issues */}
       <HealthPanel />
diff --git a/frontend/src/components/home/InspirationCard.css b/frontend/src/components/home/InspirationCard.css
index 53ff96f4..cabc6a47 100644
--- a/frontend/src/components/home/InspirationCard.css
+++ b/frontend/src/components/home/InspirationCard.css
@@ -156,6 +156,22 @@
   }
 }
 
+/* Entrance animation */
+@keyframes inspiration-enter {
+  from {
+    opacity: 0;
+    transform: scale(0.98);
+  }
+  to {
+    opacity: 1;
+    transform: scale(1);
+  }
+}
+
+.inspiration-card__item--enter {
+  animation: inspiration-enter 0.2s ease backwards;
+}
+
 /* Fallback for browsers without backdrop-filter */
 @supports not (backdrop-filter: blur(10px)) {
   .inspiration-card__item {
@@ -172,6 +188,10 @@
     animation: none;
     background: var(--glass-border);
   }
+
+  .inspiration-card__item--enter {
+    animation: none;
+  }
 }
 
 /* Touch device adjustments */
diff --git a/frontend/src/components/home/InspirationCard.tsx b/frontend/src/components/home/InspirationCard.tsx
index 8c24640c..6fff0e91 100644
--- a/frontend/src/components/home/InspirationCard.tsx
+++ b/frontend/src/components/home/InspirationCard.tsx
@@ -16,8 +16,8 @@ import "./InspirationCard.css";
 export interface InspirationCardProps {
   /** Contextual prompt (null if not available or on weekends) */
   contextual: InspirationItem | null;
-  /** Inspirational quote (always present) */
-  quote: InspirationItem;
+  /** Inspirational quote (null during loading or if unavailable) */
+  quote: InspirationItem | null;
   /** Whether data is still loading */
   isLoading?: boolean;
 }
@@ -44,7 +44,8 @@ export function InspirationCard({
     [setDiscussionPrefill, setMode]
   );
 
-  if (isLoading) {
+  // Show skeleton if loading or no quote available
+  if (isLoading || !quote) {
     return (
       <section className="inspiration-card inspiration-card--loading" aria-label="Inspiration">
         <div className="inspiration-card__skeleton">
@@ -59,7 +60,7 @@ export function InspirationCard({
     <section className="inspiration-card" aria-label="Inspiration">
       <button
         type="button"
-        className="inspiration-card__item inspiration-card__quote"
+        className="inspiration-card__item inspiration-card__quote inspiration-card__item--enter"
         onClick={() => handleClick(quote.text)}
         aria-label="Use this quote for discussion"
       >
@@ -74,7 +75,7 @@ export function InspirationCard({
       {contextual && (
         <button
           type="button"
-          className="inspiration-card__item inspiration-card__prompt"
+          className="inspiration-card__item inspiration-card__prompt inspiration-card__item--enter"
           onClick={() => handleClick(contextual.text)}
           aria-label="Use this prompt for discussion"
         >
diff --git a/frontend/src/components/home/RecentActivity.css b/frontend/src/components/home/RecentActivity.css
index 2c0e27d0..c6d319db 100644
--- a/frontend/src/components/home/RecentActivity.css
+++ b/frontend/src/components/home/RecentActivity.css
@@ -266,3 +266,106 @@
     padding: var(--spacing-sm) var(--spacing-md);
   }
 }
+
+/* ==============================================
+   Skeleton Loading State
+   ============================================== */
+
+.recent-activity__card--skeleton {
+  pointer-events: none;
+}
+
+.recent-activity__skeleton-text {
+  width: 100%;
+  height: 2.4em;
+  background: linear-gradient(
+    90deg,
+    var(--color-surface) 25%,
+    var(--glass-border) 50%,
+    var(--color-surface) 75%
+  );
+  background-size: 200% 100%;
+  border-radius: var(--radius-sm);
+  animation: activity-shimmer 1.5s infinite;
+  margin-bottom: var(--spacing-sm);
+}
+
+.recent-activity__skeleton-footer {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+}
+
+.recent-activity__skeleton-meta {
+  width: 80px;
+  height: 1em;
+  background: linear-gradient(
+    90deg,
+    var(--color-surface) 25%,
+    var(--glass-border) 50%,
+    var(--color-surface) 75%
+  );
+  background-size: 200% 100%;
+  border-radius: var(--radius-sm);
+  animation: activity-shimmer 1.5s infinite;
+}
+
+.recent-activity__skeleton-action {
+  width: 50px;
+  height: 1.5em;
+  background: linear-gradient(
+    90deg,
+    var(--color-surface) 25%,
+    var(--glass-border) 50%,
+    var(--color-surface) 75%
+  );
+  background-size: 200% 100%;
+  border-radius: var(--radius-md);
+  animation: activity-shimmer 1.5s infinite;
+}
+
+@keyframes activity-shimmer {
+  0% {
+    background-position: 200% 0;
+  }
+  100% {
+    background-position: -200% 0;
+  }
+}
+
+/* ==============================================
+   Entrance Animation
+   ============================================== */
+
+@keyframes recent-activity-enter {
+  from {
+    opacity: 0;
+    transform: translateY(8px);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+.recent-activity__card--enter {
+  animation: recent-activity-enter 0.25s ease backwards;
+  /* animationDelay set via inline style for staggering */
+}
+
+/* ==============================================
+   Reduced Motion Preference
+   ============================================== */
+
+@media (prefers-reduced-motion: reduce) {
+  .recent-activity__skeleton-text,
+  .recent-activity__skeleton-meta,
+  .recent-activity__skeleton-action {
+    animation: none;
+    background: var(--glass-border);
+  }
+
+  .recent-activity__card--enter {
+    animation: none;
+  }
+}
diff --git a/frontend/src/components/home/RecentActivity.tsx b/frontend/src/components/home/RecentActivity.tsx
index 83ce6525..8db63096 100644
--- a/frontend/src/components/home/RecentActivity.tsx
+++ b/frontend/src/components/home/RecentActivity.tsx
@@ -45,6 +45,8 @@ function formatRelativeDate(dateStr: string): string {
  * Props for RecentActivity component.
  */
 export interface RecentActivityProps {
+  /** Whether activity data is still loading */
+  isLoading?: boolean;
   /** Callback when user wants to resume a discussion */
   onResumeDiscussion?: (sessionId: string) => void;
   /** Callback when user wants to view a capture in browse mode */
@@ -63,6 +65,7 @@ export interface RecentActivityProps {
  * - Handling session_deleted response and calling removeDiscussion
  */
 export function RecentActivity({
+  isLoading = false,
   onResumeDiscussion,
   onViewCapture,
   onDeleteSession,
@@ -132,6 +135,24 @@ export function RecentActivity({
   const hasCaptures = recentNotes.length > 0;
   const hasDiscussions = recentDiscussions.length > 0;
 
+  // Show skeleton during load
+  if (isLoading) {
+    return (
+      <section className="recent-activity" aria-label="Recent activity loading">
+        <div className="recent-activity__section">
+          <h3 className="recent-activity__section-title">
+            <span className="recent-activity__heading">Recent</span>
+          </h3>
+          <div className="recent-activity__list">
+            <SkeletonCard />
+            <SkeletonCard />
+          </div>
+        </div>
+      </section>
+    );
+  }
+
+  // Don't render if no activity
   if (!hasCaptures && !hasDiscussions) {
     return null;
   }
@@ -145,10 +166,11 @@ export function RecentActivity({
             <span className="recent-activity__heading">Recent: Captures</span>
           </h3>
           <div className="recent-activity__list">
-            {recentNotes.map((note) => (
+            {recentNotes.map((note, index) => (
               <CaptureCard
                 key={note.id}
                 note={note}
+                animationDelay={index * 50}
                 onView={() => handleViewCapture(note.date)}
               />
             ))}
@@ -162,11 +184,12 @@ export function RecentActivity({
             <span className="recent-activity__heading">Recent: Discussions</span>
           </h3>
           <div className="recent-activity__list">
-            {recentDiscussions.map((discussion) => (
+            {recentDiscussions.map((discussion, index) => (
               <DiscussionCard
                 key={discussion.sessionId}
                 discussion={discussion}
                 isActive={discussion.sessionId === sessionId}
+                animationDelay={index * 50}
                 onResume={() => handleResumeDiscussion(discussion.sessionId)}
                 onDelete={() => handleDeleteClick(discussion.sessionId)}
               />
@@ -187,20 +210,39 @@ export function RecentActivity({
   );
 }
 
+/**
+ * Skeleton card for loading state.
+ */
+function SkeletonCard(): React.ReactNode {
+  return (
+    <article className="recent-activity__card recent-activity__card--skeleton">
+      <div className="recent-activity__skeleton-text" />
+      <div className="recent-activity__skeleton-footer">
+        <div className="recent-activity__skeleton-meta" />
+        <div className="recent-activity__skeleton-action" />
+      </div>
+    </article>
+  );
+}
+
 /**
  * Card for displaying a recent capture.
  */
 interface CaptureCardProps {
   note: RecentNoteEntry;
+  animationDelay?: number;
   onView: () => void;
 }
 
-function CaptureCard({ note, onView }: CaptureCardProps): React.ReactNode {
+function CaptureCard({ note, animationDelay = 0, onView }: CaptureCardProps): React.ReactNode {
   const relativeDate = formatRelativeDate(note.date);
   const showDate = relativeDate !== "Today";
 
   return (
-    <article className="recent-activity__card recent-activity__card--capture">
+    <article
+      className="recent-activity__card recent-activity__card--capture recent-activity__card--enter"
+      style={{ animationDelay: `${animationDelay}ms` }}
+    >
       <p className="recent-activity__text">{note.text}</p>
       <div className="recent-activity__footer">
         <div className="recent-activity__meta">
@@ -228,6 +270,7 @@ function CaptureCard({ note, onView }: CaptureCardProps): React.ReactNode {
 interface DiscussionCardProps {
   discussion: RecentDiscussionEntry;
   isActive: boolean;
+  animationDelay?: number;
   onResume: () => void;
   onDelete: () => void;
 }
@@ -235,6 +278,7 @@ interface DiscussionCardProps {
 function DiscussionCard({
   discussion,
   isActive,
+  animationDelay = 0,
   onResume,
   onDelete,
 }: DiscussionCardProps): React.ReactNode {
@@ -242,7 +286,10 @@ function DiscussionCard({
   const showDate = relativeDate !== "Today";
 
   return (
-    <article className="recent-activity__card recent-activity__card--discussion">
+    <article
+      className="recent-activity__card recent-activity__card--discussion recent-activity__card--enter"
+      style={{ animationDelay: `${animationDelay}ms` }}
+    >
       <p className="recent-activity__text">{discussion.preview}</p>
       <div className="recent-activity__footer">
         <div className="recent-activity__meta">
diff --git a/frontend/src/components/home/SpacedRepetitionWidget.css b/frontend/src/components/home/SpacedRepetitionWidget.css
index 6dadb279..8d6dd465 100644
--- a/frontend/src/components/home/SpacedRepetitionWidget.css
+++ b/frontend/src/components/home/SpacedRepetitionWidget.css
@@ -103,6 +103,45 @@
   }
 }
 
+/* ==============================================
+   Idle State (No Cards Due)
+   ============================================== */
+
+.spaced-repetition-widget__idle {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: var(--spacing-md);
+  color: var(--color-text-secondary);
+  font-size: var(--font-size-sm);
+}
+
+.spaced-repetition-widget__idle-message {
+  opacity: 0.8;
+}
+
+/* ==============================================
+   Entrance Animation
+   ============================================== */
+
+@keyframes widget-content-enter {
+  from {
+    opacity: 0;
+    transform: translateY(4px);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+.spaced-repetition-widget__question,
+.spaced-repetition-widget__answer,
+.spaced-repetition-widget__complete,
+.spaced-repetition-widget__idle {
+  animation: widget-content-enter 0.2s ease backwards;
+}
+
 /* ==============================================
    Error State
    ============================================== */
@@ -558,3 +597,13 @@
     background-color: var(--color-surface);
   }
 }
+
+/* Reduced motion preference for entrance animations */
+@media (prefers-reduced-motion: reduce) {
+  .spaced-repetition-widget__question,
+  .spaced-repetition-widget__answer,
+  .spaced-repetition-widget__complete,
+  .spaced-repetition-widget__idle {
+    animation: none;
+  }
+}
diff --git a/frontend/src/components/home/SpacedRepetitionWidget.tsx b/frontend/src/components/home/SpacedRepetitionWidget.tsx
index a92e646a..276c2220 100644
--- a/frontend/src/components/home/SpacedRepetitionWidget.tsx
+++ b/frontend/src/components/home/SpacedRepetitionWidget.tsx
@@ -33,8 +33,13 @@ export interface SpacedRepetitionWidgetProps {
 
 /**
  * Widget state machine phases.
+ * - loading: Initial fetch in progress
+ * - idle: No cards due today
+ * - question: Showing question, awaiting user input
+ * - revealed: Answer shown, awaiting self-assessment
+ * - complete: All cards reviewed for this session
  */
-type WidgetPhase = "loading" | "question" | "revealed" | "complete";
+type WidgetPhase = "loading" | "idle" | "question" | "revealed" | "complete";
 
 /**
  * Internal widget state.
@@ -53,6 +58,8 @@ interface WidgetState {
   initialCount: number;
   /** Whether we've started a review session */
   sessionStarted: boolean;
+  /** Whether the initial fetch failed (hide widget on error) */
+  fetchFailed: boolean;
 }
 
 const INITIAL_STATE: WidgetState = {
@@ -63,6 +70,7 @@ const INITIAL_STATE: WidgetState = {
   queue: [],
   initialCount: 0,
   sessionStarted: false,
+  fetchFailed: false,
 };
 
 /**
@@ -117,11 +125,23 @@ export function SpacedRepetitionWidget({
 
     getDueCards()
       .then((result) => {
-        if (!result || result.count === 0) {
-          setState(INITIAL_STATE);
+        // API error (returns null on failure) - hide widget
+        if (result === null) {
+          setState({ ...INITIAL_STATE, fetchFailed: true });
           return;
         }
 
+        // No cards due - show idle state
+        if (result.count === 0) {
+          setState({
+            ...INITIAL_STATE,
+            phase: "idle",
+            sessionStarted: true,
+          });
+          return;
+        }
+
+        // Cards available - show first question
         const cards = result.cards;
         setState({
           phase: "question",
@@ -131,10 +151,12 @@ export function SpacedRepetitionWidget({
           queue: cards.slice(1),
           initialCount: result.count,
           sessionStarted: true,
+          fetchFailed: false,
         });
       })
       .catch(() => {
-        setState(INITIAL_STATE);
+        // Unexpected error - hide widget
+        setState({ ...INITIAL_STATE, fetchFailed: true });
       });
   }, [vaultId, getDueCards]);
 
@@ -305,13 +327,16 @@ export function SpacedRepetitionWidget({
     [handleShowAnswer]
   );
 
-  // Don't render if no vault or if we haven't loaded cards yet
+  // Don't render if no vault or if initial fetch failed
   if (!vaultId) return null;
-  if (!state.sessionStarted) return null;
+  if (state.fetchFailed) return null;
 
-  // Calculate remaining cards for header
+  // Calculate remaining cards for header (0 during loading/idle)
   const remainingCount = state.queue.length + (state.currentCard ? 1 : 0);
 
+  // Show loading state during initial fetch
+  const showLoading = state.phase === "loading";
+
   return (
     <>
       <section
@@ -321,19 +346,30 @@ export function SpacedRepetitionWidget({
         {/* Header */}
         <header className="spaced-repetition-widget__header">
           <h3 className="spaced-repetition-widget__title">Spaced Repetition</h3>
-          <span className="spaced-repetition-widget__count">
-            {remainingCount} {remainingCount === 1 ? "card" : "cards"}
-          </span>
+          {!showLoading && state.phase !== "idle" && (
+            <span className="spaced-repetition-widget__count">
+              {remainingCount} {remainingCount === 1 ? "card" : "cards"}
+            </span>
+          )}
         </header>
 
         {/* Loading state */}
-        {state.phase === "loading" && (
+        {showLoading && (
           <div className="spaced-repetition-widget__loading">
             <div className="spaced-repetition-widget__spinner" />
             <span>Loading cards...</span>
           </div>
         )}
 
+        {/* Idle state - no cards due */}
+        {state.phase === "idle" && (
+          <div className="spaced-repetition-widget__idle">
+            <span className="spaced-repetition-widget__idle-message">
+              No cards due today
+            </span>
+          </div>
+        )}
+
         {/* Error state */}
         {error && (
           <div className="spaced-repetition-widget__error" role="alert">
diff --git a/frontend/src/components/home/__tests__/HomeView.test.tsx b/frontend/src/components/home/__tests__/HomeView.test.tsx
index b1f7223f..6ef53193 100644
--- a/frontend/src/components/home/__tests__/HomeView.test.tsx
+++ b/frontend/src/components/home/__tests__/HomeView.test.tsx
@@ -52,10 +52,11 @@ describe("HomeView", () => {
   });
 
   describe("inspiration", () => {
-    it("does not render InspirationCard when no inspiration data", () => {
+    it("renders InspirationCard with skeleton when no inspiration data", () => {
       render(<HomeView />, { wrapper: Wrapper });
 
-      expect(screen.queryByLabelText("Inspiration")).toBeNull();
+      // InspirationCard always renders, showing skeleton when loading or no data
+      expect(screen.getByLabelText("Inspiration")).toBeTruthy();
     });
   });
 });
diff --git a/frontend/src/components/home/__tests__/SpacedRepetitionWidget.test.tsx b/frontend/src/components/home/__tests__/SpacedRepetitionWidget.test.tsx
index e34d587a..12e67921 100644
--- a/frontend/src/components/home/__tests__/SpacedRepetitionWidget.test.tsx
+++ b/frontend/src/components/home/__tests__/SpacedRepetitionWidget.test.tsx
@@ -168,15 +168,15 @@ describe("SpacedRepetitionWidget", () => {
       expect(container.firstChild).toBeNull();
     });
 
-    it("renders nothing when no cards are due", async () => {
+    it("shows idle state when no cards are due", async () => {
       const mockFetch = createMockFetch({ dueCards: { cards: [], count: 0 } });
-      const { container } = renderWithSession(
+      renderWithSession(
         <SpacedRepetitionWidget vaultId="test-vault" fetchFn={mockFetch} />
       );
 
-      // Wait for the fetch to complete
+      // Wait for the fetch to complete and show idle state
       await waitFor(() => {
-        expect(container.firstChild).toBeNull();
+        expect(screen.getByText("No cards due today")).toBeDefined();
       });
     });