# Implementation Plan: Admin Dashboard UI States Audit (`audit_ui_states_20260314`)

## Overview
This plan outlines the steps for auditing and improving the UI/UX states (Loading, Success, Empty, Error, Partial, Secondary) across the **Admin Dashboard**.

## Phase 1: Scouting & Analysis [Scout]
Identify current state-handling patterns and gaps in the dashboard.

- [ ] **Task: Research Existing Skeleton Patterns** [Skills: software-architecture] [MCP: FileSystem]
    - [Scout] Search `components/dashboard/` and `components/ui/` for any existing skeleton or loading component implementations.
    - [Scout] Identify where `useAction` is used in dashboard pages to see how loading/error states are currently handled.
- [ ] **Task: Map Dashboard Pages and Components** [Skills: software-architecture] [MCP: FileSystem]
    - [Scout] List all primary dashboard pages in `app/(private)/dashboard/`.
    - [Scout] Identify components that fetch data (e.g., `OrdersTable`, `CatalogList`).
- [ ] **Task: Create Audit Report Base** [Skills: fullstack-development] [MCP: FileSystem]
    - Write a document summarizing the current state of each dashboard page regarding the 6 UI states.

## Phase 2: Loading & Empty States (Red-Green-Refactor)
Implement consistent skeleton screens and page-specific empty states.

- [ ] **Task: Standardize Skeleton Layouts** [Skills: styling-ui-ux, shadcn-ui] [MCP: FileSystem]
    - [Scout] Check `components/ui/skeleton.tsx` (if it exists) or create it via `shadcn-ui`.
    - **Write Failing Tests**: Verify that `OrdersTable` and `CatalogList` display a skeleton while `isLoading` is true.
    - **Implement**: Add skeleton states to all primary dashboard tables and lists.
- [ ] **Task: Implement Page-Specific Empty States** [Skills: styling-ui-ux, uncodixfy] [MCP: FileSystem]
    - [Scout] Identify the "Add" actions for each page (e.g., "Add Product," "Create Order").
    - **Write Failing Tests**: Verify that `OrdersTable` displays a contextual empty state with an "Add" CTA when the dataset is empty.
    - **Implement**: Create unique empty state components for Orders, Catalog, and Customers.

## Phase 3: Error & Partial States (Red-Green-Refactor)
Ensure robust error recovery and graceful handling of partial data failures.

- [ ] **Task: Verify Automatic Retries in `useAction`** [Skills: managing-server-actions] [MCP: FileSystem]
    - [Scout] Check `hooks/useAction.ts` and `lib/actions.ts` for retry logic.
    - **Write Failing Tests**: Simulate a network failure and verify the action automatically retries before showing an error state.
    - **Implement**: Update `useAction` or its wrapper to include standard retry logic for GET requests.
- [ ] **Task: Implement Inline Error Banners** [Skills: styling-ui-ux, uncodixfy] [MCP: FileSystem]
    - [Scout] Identify secondary widgets or components that can fail independently (e.g., Dashboard stats).
    - **Write Failing Tests**: Verify that a failing stat widget shows an inline error message instead of crashing the dashboard.
    - **Implement**: Add inline error states to all dashboard widgets.

## Phase 4: Final Verification & Audit [Quality Gate]
Perform a comprehensive "Strictness Audit" and verify all resource budgets.

- [ ] **Task: Verify Resource Budgets** [Skills: debug-optimize-lcp] [MCP: Shell]
    - [Scout] Use Chrome DevTools or Lighthouse to measure transition latency.
    - **Verify**: Ensure state transitions (Loading -> Content) are **< 200ms**.
- [ ] **Task: Mobile Layout Audit** [Skills: optimizing-mobile-ux] [MCP: FileSystem]
    - [Scout] Test all new skeleton and empty states on mobile viewports.
    - **Verify**: No layout shifts or overflows in loading states on mobile.
- [ ] **Task: Final Audit Report & Documentation** [Skills: software-architecture] [MCP: FileSystem]
    - Update the initial audit report with the resolutions for each identified gap.