resolutionflow/docs/plans/2026-02-20-frontend-standardization-prompt.md

Frontend Standardization: Full Audit & Fix

Objective

Perform a comprehensive audit of the entire ResolutionFlow frontend and standardize four UI patterns that are currently inconsistent across the application. Create reusable components where they don't exist, then retrofit every page and component to use them. When done, the entire app should feel like one developer built every page.

Use every tool, agent, and skill at your disposal. Search every file. Don't ask — fix.

---

Pattern 1: Loading States → Replace All Spinners with Skeleton Components

The Problem

Loading states are implemented differently across the app. Some pages use a centered spinning circle, others use pulse-animated rectangles, and some use nothing. There is no shared reusable skeleton component.

Current Inconsistencies to Find and Fix

Spinner pattern (replace everywhere you find it):

// THIS PATTERN — find every instance and replace with skeletons
<div className="flex justify-center py-12">
  <div className="h-8 w-8 animate-spin rounded-full border-4 border-primary border-t-transparent" />
</div>

Known locations (search for more):

• frontend/src/pages/SessionHistoryPage.tsx — uses spinner
• frontend/src/pages/TreeLibraryPage.tsx — uses spinner
• frontend/src/components/step-library/StepLibraryBrowser.tsx — uses spinner or loading boolean
• frontend/src/pages/QuickStartPage.tsx — uses spinner or loading state
• frontend/src/pages/TreeEditorPage.tsx — check for loading state
• frontend/src/pages/SessionDetailPage.tsx — check for loading state
• frontend/src/pages/TreeNavigationPage.tsx — check for loading state
• frontend/src/pages/MyTreesPage.tsx — check for loading state
• Any other page or component with isLoading state

What to Build

Create frontend/src/components/common/Skeleton.tsx:

A set of composable skeleton primitives:

// Base skeleton block with pulse animation
export function Skeleton({ className }: { className?: string }) {
  return <div className={cn("animate-pulse rounded bg-muted", className)} />
}

// Pre-built skeleton layouts for common patterns:
export function SkeletonCard() { /* Card-shaped skeleton matching TreeGridView card dimensions */ }
export function SkeletonRow() { /* Row-shaped skeleton matching TreeListView row dimensions */ }
export function SkeletonTableRow() { /* Table row skeleton matching TreeTableView row */ }
export function SkeletonText({ lines = 3 }: { lines?: number }) { /* Text block skeleton */ }

The Standard (enforce everywhere)

• Page-level data loading: Show skeleton placeholders that match the shape of the content that will appear. Grid pages get skeleton cards. List pages get skeleton rows. Detail pages get skeleton text blocks.
• Component-level loading: Small inline skeletons (e.g., a single line for a name loading).
• Never show a centered spinner. The only acceptable spinner is on a button that is performing an action (e.g., "Saving..." with a small inline spinner). Page/section loading always uses skeletons.
• Skeleton count should match expected content. If a page typically shows 6 cards, show 6 skeleton cards. If a list shows 10 rows, show 10 skeleton rows.

Audit Instructions

1. Search the entire frontend/src/ directory for: animate-spin, border-t-transparent, Loader2 (Lucide spinner icon), and any isLoading state variable.
2. For every match, determine if it's a page/section loading state or a button action state.
3. Replace all page/section loading states with appropriate skeleton components.
4. Leave button-level spinners alone (e.g., "Saving..." on submit buttons is fine).

---

Pattern 2: Empty States → Add Meaningful Messages + CTAs Everywhere

The Problem

Empty states across the app are bare text with no guidance and no call to action. A new user sees "No sessions found." or "No trees found." and has no idea what to do next.

Current Inconsistencies to Find and Fix

Known bare empty states:

• SessionHistoryPage.tsx: "No sessions found." — no CTA
• TreeLibraryPage.tsx: "No trees found. Try adjusting your filters." — has filter hint but no create CTA
• StepLibraryBrowser.tsx: check for empty state pattern
• QuickStartPage.tsx: check for empty state pattern
• MyTreesPage.tsx: check for empty state pattern
• Any page that renders a list and has a length === 0 check

What to Build

Create frontend/src/components/common/EmptyState.tsx:

interface EmptyStateProps {
  icon?: React.ReactNode        // Optional icon above the message
  title: string                  // e.g., "No sessions yet"
  description?: string           // e.g., "Start a troubleshooting session to see it here"
  action?: {
    label: string                // e.g., "Start a Session"
    onClick: () => void
  }
  secondaryAction?: {
    label: string                // e.g., "Clear filters"
    onClick: () => void
  }
}

The Standard (enforce everywhere)

Every empty state must have:

1. A clear title that says what's empty (not just "No results")
2. A description that tells the user why it's empty or what to do
3. A primary CTA (when applicable) that lets them take the obvious next action
4. A secondary action (when applicable) for filter/search scenarios: "Clear filters" or "Try a different search"

Context-specific empty states:

Page / Section	Title	Description	CTA
Session History (no sessions at all)	"No sessions yet"	"Start a troubleshooting session to see your history here"	"Browse Flows" → navigate to /trees
Session History (filter returns empty)	"No matching sessions"	"Try adjusting your filters"	"Clear filters" → reset filter
Tree Library (no trees at all)	"No flows available"	"Create your first troubleshooting flow to get started"	"Create Flow" → open create dropdown/navigate
Tree Library (search returns empty)	"No flows match your search"	"Try different keywords or clear your filters"	"Clear search" → reset search
My Trees (no authored trees)	"You haven't created any flows yet"	"Build a troubleshooting flow to guide your team"	"Create Flow" → open create dropdown
Step Library (no steps)	"No steps found"	"Create your first reusable step"	"Create Step" → open create form
Dashboard Favorites (no pins)	"No favorites yet"	"Star a flow to pin it here for quick access"	No button (action is contextual)
Dashboard My Flows (no authored flows)	"You haven't created any flows yet"	"Build your first troubleshooting flow"	"Create your first flow" → open create dropdown

Audit Instructions

1. Search frontend/src/ for: length === 0, .length === 0, sessions.length, trees.length, and any conditional rendering that shows text when a list is empty.
2. For every match, check if the empty state has a title, description, and CTA.
3. Replace bare text empty states with the EmptyState component using the appropriate context from the table above.
4. If you find an empty state not listed in the table, follow the same pattern: clear title, helpful description, obvious next action.

---

Pattern 3: Accessibility — Aria Labels on All Icon-Only Buttons

The Problem

Some icon-only buttons have proper aria-label attributes (e.g., ThemeToggle uses aria-label={Switch to ${label} theme}), but most don't. Icon buttons without aria-labels are invisible to screen readers.

The Gold Standard (already in the codebase)

From ThemeToggle.tsx:

<button
  onClick={() => setTheme(value)}
  className={cn('rounded p-1.5 transition-colors', ...)}
  aria-label={`Switch to ${label} theme`}
  aria-pressed={theme === value}
>
  <Icon className="h-4 w-4" />
</button>

From StepDetailModal.tsx:

<button
  onClick={onClose}
  className="rounded-md p-1 hover:bg-accent"
  aria-label="Close"
>
  <X className="h-5 w-5" />
</button>

The Standard (enforce everywhere)

Every <button> that contains only an icon (no visible text) MUST have:

1. aria-label="Descriptive action" — describes what the button does, not what the icon looks like
2. For toggle buttons: aria-pressed={isActive} (like the ThemeToggle pattern)
3. For buttons inside clickable parent containers (cards, rows): e.stopPropagation() and e.preventDefault() in the onClick handler

Common icon buttons to look for:

• Close buttons (X icon) → aria-label="Close"
• Delete buttons (Trash icon) → aria-label="Delete [thing]"
• Edit buttons (Pencil icon) → aria-label="Edit [thing]"
• Filter clear buttons (X in a chip) → aria-label="Remove [filter name] filter"
• Expand/collapse buttons (ChevronDown/Up) → aria-label="Expand" / aria-label="Collapse"
• Copy buttons → aria-label="Copy to clipboard"
• Pin/favorite buttons → aria-label="Add to favorites" / aria-label="Remove from favorites"
• Sort buttons → aria-label="Sort by [field]"
• Navigation arrows → aria-label="Previous page" / aria-label="Next page"
• Menu/hamburger buttons → aria-label="Open menu"
• Any icon-only button with <SomeLucideIcon /> and no text sibling

Audit Instructions

1. Search frontend/src/ for all <button elements.
2. For each button, check if it contains visible text content (a text node or a <span> with text).
3. If the button contains ONLY an icon (Lucide component, SVG, or image) with no visible text, verify it has an aria-label.
4. If aria-label is missing, add an appropriate one based on the button's purpose (check the onClick handler and surrounding context to determine what the button does).
5. For toggle buttons (pin/unpin, expand/collapse, theme), add aria-pressed where appropriate.
6. Also check for <a> tags that contain only icons — these need aria-label too.

---

Pattern 4: Error Banners (Verification Only)

The Current Pattern (already consistent — verify it stays that way)

{error && (
  <div className="mb-6 rounded-md bg-destructive/10 p-4 text-destructive">
    {error}
  </div>
)}

Audit Instructions

1. Search for all error display patterns in frontend/src/.
2. Verify they all use the same bg-destructive/10 p-4 text-destructive pattern.
3. If any page uses a different error display style, update it to match.
4. Do NOT change this pattern — just verify consistency.

---

Execution Order

1. Create the reusable components first:

   • frontend/src/components/common/Skeleton.tsx
   • frontend/src/components/common/EmptyState.tsx

2. Audit and fix Pattern 1 (Loading Skeletons):

   • Search for every spinner and isLoading pattern
   • Replace with appropriate skeleton components
   • Verify each page renders skeletons that match the shape of expected content

3. Audit and fix Pattern 2 (Empty States):

   • Search for every empty list/empty state pattern
   • Replace with EmptyState component using context-appropriate messaging
   • Ensure every empty state has at minimum a title and description

4. Audit and fix Pattern 3 (Aria Labels):

   • Search for every icon-only button
   • Add aria-label to every one that's missing it
   • Add aria-pressed to toggle buttons

5. Verify Pattern 4 (Error Banners):

   • Quick scan to confirm consistency
   • Fix any outliers

6. Final verification:

   • cd frontend && npm run build — must pass with zero errors
   • cd frontend && npm run test — must pass
   • Visually spot-check: no page should show a centered spinner anymore

---

Rules

• Do NOT change any business logic. Only change presentation/UI patterns.
• Do NOT change any API calls or data fetching logic.
• Do NOT add new dependencies. Use only Tailwind CSS utilities and existing project patterns.
• Do NOT change the error banner pattern — it's already correct.
• DO use cn() from @/lib/utils for conditional class merging (existing project standard).
• DO use Lucide icons (existing project standard). No title prop on Lucide — wrap in <span title="..."> if tooltip is needed.
• DO support dark mode in all new components (use Tailwind's text-foreground, bg-muted, text-muted-foreground etc., not hardcoded colors).
• DO keep the new components simple. No over-engineering. The Skeleton and EmptyState components should be under 100 lines each.