# 26. Polish — Error Boundaries, Loading States, Skeletons, and Transitions

meta:
  id: shieldai-unified-restructure-26
  feature: shieldai-unified-restructure
  priority: P1
  depends_on: [shieldai-unified-restructure-24, shieldai-unified-restructure-25]
  tags: [frontend, polish, ux, accessibility, solidjs]

objective:
- Add production polish to the web app: error boundaries for graceful failure handling, skeleton screens for loading states, smooth page transitions, and comprehensive accessibility improvements.

deliverables:
- `web/src/components/ui/ErrorBoundary.tsx` — Global error boundary:
  - Catches runtime errors in child components
  - Displays friendly error page with ShieldAI branding
  - "Try again" button to reset error boundary
  - "Report issue" button (placeholder for Sentry integration)
  - Logs error details to console (and eventually monitoring)
- `web/src/components/ui/Skeleton.tsx` — Skeleton loading components:
  - `SkeletonText` — animated pulse lines for text placeholders
  - `SkeletonCard` — card-shaped skeleton with header, body, footer
  - `SkeletonAvatar` — circular skeleton for profile images
  - `SkeletonTable` — table row skeletons
  - All use `.bg-bg-tertiary` with shimmer animation
- `web/src/components/ui/PageTransition.tsx` — Page transition wrapper:
  - Fade-in + slight translate-y on route change
  - Respects `prefers-reduced-motion`
  - Uses SolidJS `<Transition>` or CSS animations
- Loading states integrated:
  - Dashboard widgets show skeletons while `createResource` is loading
  - Service pages show skeleton layouts while data fetches
  - Buttons show spinner inside during mutation loading
  - Forms show disabled state with spinner during submission
- Accessibility improvements:
  - All images have `alt` text
  - All interactive elements have focus rings
  - Color contrast meets WCAG AA (4.5:1 for text)
  - ARIA labels on icon-only buttons
  - Skip-to-content link for keyboard navigation
  - Reduced motion support for all animations
- `web/src/components/ui/EmptyState.tsx` — Empty state component:
  - Icon, title, description, and optional action button
  - Used when lists have no items (e.g., no watchlist items, no alerts)

steps:
1. Create `web/src/components/ui/ErrorBoundary.tsx`:
   - Use SolidJS `ErrorBoundary` component as base
   - Custom fallback UI with ShieldAI logo, error message, retry button
   - Capture stack trace for debugging
2. Create `web/src/components/ui/Skeleton.tsx`:
   - Use Tailwind `animate-pulse` or custom shimmer animation
   - Each skeleton variant accepts `lines`, `width`, `height` props
   - Use rounded rectangles that mimic content shape
3. Create `web/src/components/ui/PageTransition.tsx`:
   - Wrap route content in transition group
   - Apply `opacity-0 translate-y-2` → `opacity-100 translate-y-0` on enter
   - Duration: 200ms, easing: ease-out
4. Integrate skeletons:
   - Dashboard: replace `Loading...` text with `SkeletonCard` grids
   - Service pages: add skeleton layouts matching final content shape
   - Tables: use `SkeletonTable` with 5 rows
5. Integrate loading states in buttons:
   - Update `Button` primitive to show spinner when `loading` prop is true
   - Disable button and reduce opacity during loading
6. Add accessibility:
   - Audit all pages with axe DevTools
   - Fix any contrast issues (adjust colors in theme if needed)
   - Add `aria-label` to all icon buttons
   - Add `aria-live="polite"` regions for toast notifications
   - Ensure all form inputs have associated labels
7. Create `EmptyState` component and use it across pages:
   - DarkWatch: "No watchlist items yet" with "Add first item" button
   - VoicePrint: "No voice enrollments" with "Enroll voice" button
   - SpamShield: "No custom rules" with "Create rule" button
   - etc.
8. Test all improvements across light/dark modes.

steps:
- Unit: ErrorBoundary catches thrown errors and renders fallback
- Unit: Skeleton components render with correct dimensions
- Unit: PageTransition applies enter animation
- Accessibility: axe DevTools audit passes with 0 critical violations
- Visual: All loading states look polished and match content layout
- Visual: Empty states display correctly when lists are empty

acceptance_criteria:
- [ ] ErrorBoundary catches and displays friendly error UI for all routes
- [ ] Skeleton screens match the shape of final content (no layout shift)
- [ ] All buttons show loading state during mutations
- [ ] Page transitions are smooth and respect reduced motion
- [ ] Empty states are informative and provide clear next actions
- [ ] axe DevTools audit shows 0 critical or serious violations
- [ ] All color combinations meet WCAG AA contrast standards
- [ ] Keyboard navigation works for all interactive elements

validation:
- Throw an error in a component and verify ErrorBoundary catches it
- Throttle network to 3G and verify skeletons appear during loading
- Navigate between routes and verify smooth transitions
- Run axe DevTools on each page and fix any issues
- Test keyboard-only navigation (Tab, Enter, Escape) on all pages
- Run `cd web && pnpm test` for polish-related unit tests

notes:
- Reference Lendair's skeleton components: `~/code/Lendair/web/src/components/skeletons/`
- The `animate-pulse` Tailwind class is sufficient for skeletons. For a more polished look, consider a custom shimmer animation with a moving gradient.
- Error boundaries should NOT catch errors in event handlers or async code — only render errors. Use try/catch for async operations.
- For monitoring integration, consider adding Sentry in a follow-up task. For now, log errors to console.
- The `EmptyState` component should be reusable across all service pages. Keep it generic but allow customization of icon, title, description, and action.
- Test reduced motion by enabling "Reduce motion" in OS settings and verifying all animations are suppressed.