# UI UX Audit

> UI/UX Audit for app.customagents.io Dashboard

- Skill: `ever-just/ui-ux-audit` (Agent Skill)
- Install (CLI): `npx skillmds@latest add ever-just/ui-ux-audit`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ever-just/ui-ux-audit/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: ever-just (https://skillmd.com/u/ever-just)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ever-just/ui-ux-audit

---

# UI/UX Audit for app.customagents.io Dashboard

## Purpose
This skill covers how to audit the UI/UX of the Custom Agents dashboard (Next.js 15, TailwindCSS 4, Phosphor Icons, React 19). It captures known patterns, anti-patterns, standards, and how to evaluate and improve the interface across web/desktop, mobile, and PWA contexts.

---

## Stack Context
- **Framework:** Next.js 15.1 App Router, React 19
- **Styling:** TailwindCSS 4 with custom CSS variables (`@theme` block in `globals.css`)
- **Icons:** Phosphor Icons (`@phosphor-icons/react`)
- **Auth:** NextAuth v5 (beta 25)
- **PWA:** Manual `sw.js` in `/public` — no next-pwa plugin, no `manifest.json`
- **Theming:** Custom ThemeProvider with `light`/`dark`/`system` modes via CSS variables
- **Layout:** Fixed sidebar (w-64) + sticky header (h-16) + `<main className="p-4 sm:p-6">`

---

## Audit Areas & Checklists

### 1. Layout & Navigation
- [ ] Sidebar collapse state is NOT persisted (localStorage) — resets on every page load
- [ ] No logo/icon in sidebar — text "CUSTOM AGENTS" only; no visual identity
- [ ] Header hamburger toggles sidebar but has no `aria-label`
- [ ] No breadcrumb navigation for deep pages (e.g., `/agents/[id]`)
- [ ] Settings sub-navigation on mobile overflows horizontally — relies on scroll, no visual hint
- [ ] No active page title in mobile header — user can't confirm context on small screens
- [ ] Missing keyboard navigation (no skip-to-content link, no focus traps in modals/menus)

### 2. Dashboard / Home Page
- [ ] Stats cards use "..." as loading state — should use skeleton placeholders
- [ ] "Emails Today" stat fetches ALL activities (up to 500) just to count — performance issue
- [ ] Dashboard duplicates the Agents list — `/` and `/agents` show the same card grid
- [ ] No date/time context on stats (e.g., "today" is ambiguous without timestamp)
- [ ] No empty-state onboarding flow for brand-new users (just a "No agents yet" card)

### 3. Agents List & Cards
- [ ] Agent cards are entire `<Link>` wrappers — the mailto icon inside causes nested interactive elements (accessibility violation)
- [ ] No search/filter on agents list — becomes unusable at 10+ agents
- [ ] No sort capability (by name, status, last activity)
- [ ] Card grid goes 1→2→3 col but never shows more context per agent (message count, last activity time)

### 4. Agent Detail Page (Tabs)
- [ ] Tab bar overflows on mobile (5 tabs: Activity, Chat, Config, Knowledge, Integrations) — no scroll indicator
- [ ] Tab state is lost on page navigation (not stored in URL query param)
- [ ] Loading state is plain text "Loading agent..." — no skeleton
- [ ] Agent deletion uses `window.confirm()` — browser dialog, not a proper modal confirmation
- [ ] `DotsThree` more menu only has Pause/Resume — feels incomplete

#### Activity Tab
- [ ] Group mode buttons (Timeline/Thread/Contact) have no minimum touch target on mobile (`px-3 py-1.5 text-xs`)
- [ ] Activity items are clickable cards but expand inline — on mobile expanded content can be very long with no scroll management
- [ ] `console.log` left in production code (lines 142-143, 147)
- [ ] Activity loading shows centered text, not a skeleton list

#### Chat Tab
- [ ] Chat height is `calc(100vh-280px)` — hardcoded magic number that breaks at different viewports
- [ ] Input is a single-line `<Input>` — multi-line messages have no way to be entered (no Shift+Enter textarea)
- [ ] Config changes diff displayed as raw JSON — should be human-readable
- [ ] No chat clear/reset capability
- [ ] No character limit indicator on the input

#### Config Tab
- [ ] No unsaved changes indicator — user can navigate away and lose edits without warning
- [ ] Form is not inside a `<form>` tag (no native browser form benefits, no Enter-to-submit)
- [ ] Escalation rules character counter (`0/2000`) is inconsistently shown only in Config tab, not in New Agent form

### 5. New Agent Form
- [ ] Multi-step wizard flow would be better UX than one long scrollable card stack
- [ ] No progress indicator for the form (user doesn't know how long it is)
- [ ] Role and Instructions fields have no character limits/counters shown
- [ ] Form validation errors only surface on submit — no inline validation
- [ ] `select` for domain dropdown uses raw HTML `<select>` — inconsistent with the rest of the design system

### 6. Drafts Page
- [ ] Filter buttons wrap to new lines on small mobile (< 360px)
- [ ] Approve/Reject buttons are in top-right corner — very small hit targets (`h-7`)
- [ ] No confirmation before rejection — easy to accidentally reject
- [ ] "Preview & Edit" textarea has no max height + overflow-y — can grow infinitely tall
- [ ] Approved/rejected drafts stay visible with no way to permanently clear/archive them

### 7. Activity Page (Global)
- [ ] No refresh button — stale on long-lived sessions
- [ ] No filtering by agent, date range, or activity type
- [ ] No pagination — loads 100 items with no "load more"
- [ ] Activity items are not clickable/expandable (unlike the per-agent view)

### 8. Settings Pages
- [ ] `settings/page.tsx` does a client-side redirect — causes flash before navigating
- [ ] General settings page shows subscription status but has no "Upgrade" CTA
- [ ] Notifications page likely stub/empty (not verified but pattern suggests it)
- [ ] Team page likely stub (no invite flow visible in codebase)
- [ ] No success/error toast system — feedback is ad-hoc per-component (e.g., Check icon for 2s)

### 9. Auth Pages
- [ ] Sign-in logo uses `<img>` not `<Image>` (no Next.js optimization)
- [ ] No "Forgot password" link
- [ ] No "Show password" toggle
- [ ] Google OAuth is disabled but commented code is visible in codebase (messy)
- [ ] No loading skeleton — shows plain text "Loading..." in Suspense fallback

### 10. Design System / Consistency
- [ ] No global toast/notification system — each page handles its own feedback
- [ ] No modal/dialog component — uses `window.confirm()` for destructive actions
- [ ] No skeleton/loading placeholder components — loading states are inconsistent (text, "...", spinners)
- [ ] `select` elements (domain picker in new agent) use raw HTML, not a custom component matching design system
- [ ] Button sizes inconsistently mixed (`h-7`, `size="sm"`, `size="icon"`)
- [ ] Only 6 UI components in `/components/ui/` — very minimal component library

### 11. Mobile Responsiveness
- [ ] Sidebar on mobile: no swipe-to-open gesture
- [ ] Settings subnav: horizontal scroll without visible scrollbar or pills indicator
- [ ] Agent detail tabs: 5 tabs overflow on screens < 375px
- [ ] Drafts approve/reject buttons stack oddly on < 320px
- [ ] Chat input area fixed at bottom but not accounting for iOS keyboard (no `env(safe-area-inset-bottom)`)
- [ ] `userScalable: false` in viewport disables pinch-zoom — accessibility concern (WCAG 1.4.4)

### 12. PWA
- [ ] **No `manifest.json`** — not installable as PWA
- [ ] `sw.js` exists in `/public` but is not registered anywhere in the codebase
- [ ] No `next-pwa` or equivalent configured in `next.config.ts`
- [ ] No offline page/fallback
- [ ] No push notification infrastructure
- [ ] No app icons set (only `favicon.ico`) — PWA needs 192x192 + 512x512 icons
- [ ] `theme-color` meta tag missing from `layout.tsx`
- [ ] `apple-mobile-web-app-capable` meta tag missing
- [ ] `apple-touch-icon` missing from `/public`

### 13. Performance & Optimization
- [ ] Dashboard fetches agents, activities (500), and drafts sequentially on load
- [ ] Activity page fetches all agents then all activities — N+1 pattern
- [ ] No React `Suspense` boundaries for data-fetching components
- [ ] No optimistic UI on toggle/pause/resume — waits for API round-trip
- [ ] Images: logo uses unoptimized `<img>` tags with no lazy loading
- [ ] No route prefetching hints beyond Next.js defaults
- [ ] No error boundaries — a single component crash can blank the entire page

### 14. Accessibility
- [ ] Missing `aria-label` on icon-only buttons (hamburger menu, theme toggle, more menu)
- [ ] `userScalable: false` violates WCAG 1.4.4 (Resize Text)
- [ ] Color-only status indicators (green/yellow/red badges) with no text alternative
- [ ] Focus management not handled after modal/menu open
- [ ] Activity items use `div onClick` without `role="button"` or `tabIndex`
- [ ] No skip-to-content link

---

## How to Run an Audit Session

1. **Code audit:** Read all files in `dashboard/src/app/` and `dashboard/src/components/`
2. **Visual audit:** Use Playwright or browser_preview tool; test at 375px, 768px, 1280px widths
3. **PWA audit:** Check `document.querySelector('link[rel="manifest"]')` → should return manifest URL
4. **A11y audit:** Run axe-core or Lighthouse accessibility scan
5. **Performance:** Run Lighthouse at https://app.customagents.io
6. **Mobile:** Use browser DevTools device emulation (iPhone 14, Pixel 7)

---

## Improvement Priority Tiers

### P0 — Critical (fix immediately)
1. Add `manifest.json` + register service worker → PWA installability
2. Remove `userScalable: false` → WCAG compliance
3. Add `aria-label` to all icon-only buttons
4. Replace `window.confirm()` with modal dialogs
5. Add global toast/notification system

### P1 — High Impact UX
1. Persist sidebar state in localStorage
2. Skeleton loading states everywhere
3. Tab bar URL persistence (`?tab=chat`)
4. Add search/filter to agents list
5. Mobile: swipe-to-open sidebar
6. iOS keyboard safe area on chat input
7. Unsaved changes warning on Config tab

### P2 — Polish & Delight
1. Add logo/icon to sidebar
2. Multi-step wizard for new agent form
3. Human-readable config change diffs in chat
4. Drafts: confirmation before reject
5. Activity: filter by type/agent/date
6. "Forgot password" on sign-in
7. Replace raw `<select>` with design system component

### P3 — Nice to Have
1. Push notifications for escalations (requires PWA infra)
2. Agent avatar/color customization
3. Keyboard shortcuts (⌘K command palette)
4. Bulk draft approve/reject
5. Dark mode OLED optimization (#000000 background)