# UX/Forms/Tables Audit (U-001-100, code-side) — agent #9

**Headline:** Generally consistent (Sheet, AlertDialog, EmptyState, requestId surfacing all good across most surfaces). 4 HIGH gaps: native `alert()` for bulk-action failures, icon-only buttons missing aria-label, unicode glyphs in portal, Vaul Drawer in mobile search overlay. Plus 14 MEDIUM gaps in form discipline + a11y + mobile nav.

**Counts:** 0 critical · 4 high · 14 medium · 0 low

---

## 🟠 HIGH

### U-059: Unicode glyphs as status icons in portal documents page

- **File:** `src/app/(portal)/portal/documents/page.tsx:85-89`
- **What:** Signer status rendered as raw Unicode (`'✓'` signed, `'✗'` declined, `'○'` pending) inside colour-coded `<span>` with no `aria-label`.
- **Why it matters:** A11y — screen readers read literal Unicode names. Per project memory: decorative unicode glyphs are explicitly flagged. `inline-stage-picker.tsx:443` comment confirms the pattern ("was ⚑ unicode glyph — replaced with a Lucide").
- **Suggested fix:** Replace with `<CheckCircle2>` / `<XCircle>` / `<Circle>` Lucide icons + `aria-label`.

### U-066: Vaul Drawer used for mobile search overlay (violates Sheet doctrine)

- **File:** `src/components/search/mobile-search-overlay.tsx:6`
- **What:** `import { Drawer as VaulDrawer } from 'vaul'` — search overlay is a full-screen overlay, not a bottom sheet, but uses Vaul Drawer. CLAUDE.md says Vaul is reserved for mobile-bottom-sheet only (currently `MoreSheet` only).
- **Suggested fix:** Convert to `<Sheet side="bottom">` or `<Dialog>` fullscreen. Visualviewport handling (lines 50-89) becomes redundant once Radix dialog primitive backs it.

### U-076: Native `alert()` for bulk-action failure feedback in 3 lists

- **Files:** `src/components/interests/interest-list.tsx:146`, `src/components/companies/company-list.tsx:73`, `src/components/yachts/yacht-list.tsx:66`
- **What:** Partial-failure feedback via `alert(...)`. `client-list.tsx:145` uses `toast.warning(...)` correctly.
- **Why it matters:** Native alert blocks main thread, can't be styled, fires in tests without suppression.
- **Suggested fix:** Replace with `toast.warning(...)` matching `client-list.tsx`.

### U-079: Icon-only buttons missing aria-label (5 sites)

- **Files:**
  - `src/components/notifications/notification-bell.tsx:65` (Bell icon button)
  - `src/components/files/file-grid.tsx:121` (MoreHorizontal "…" on file cards)
  - `src/components/admin/forms/form-template-list.tsx:102` (Trash button)
  - `src/components/email/email-accounts-list.tsx:159` (Trash button)
  - `src/components/companies/company-members-tab.tsx:228` (MoreHorizontal)
- **Pattern reference (correct):** `src/components/shared/folder-actions-menu.tsx:96` uses `<span className="sr-only">More folder actions</span>`.
- **Suggested fix:** Add `aria-label` to each, following the folder-actions-menu sr-only pattern.

---

## 🟡 MEDIUM

### U-009: Audit log inline div instead of EmptyState component

- **File:** `src/components/admin/audit/audit-log-list.tsx:524`
- **What:** `<div><p className="text-muted-foreground">No audit log entries found.</p></div>` rather than `<EmptyState title="..." />`.
- **Suggested fix:** Replace with `<EmptyState title="No audit log entries found." />`.

### U-010: Two duplicate EmptyState components with incompatible APIs

- **Files:** `src/components/ui/empty-state.tsx` vs `src/components/shared/empty-state.tsx`
- **What:** `ui/` accepts `{icon: ReactNode, body, actions}`; `shared/` accepts `{icon: ElementType, description, action: {label, onClick}}`. 3 files use `ui/` (admin/reconcile-queue, documents/documents-hub, reservations/reservation-detail), 24 use `shared/`.
- **Suggested fix:** Pick `shared/` as canonical (8× usage); migrate the 3 `ui/` callers and delete `ui/empty-state`.

### U-021: Required-field marker inconsistent

- **Files:** `src/components/clients/client-form.tsx:273`, `src/components/interests/interest-form.tsx:281`
- **What:** Some fields use inline `*`, others have no marker; no `aria-required` on inputs; no consistent pattern.
- **Suggested fix:** Single pattern: `<Label>Field <span aria-hidden>*</span></Label>` + `aria-required="true"` on input.

### U-022: Help-text discoverability inconsistent

- **File:** `src/components/shared/filter-bar.tsx`, `src/components/clients/client-form.tsx`
- **What:** No tooltip pattern; some fields have always-visible muted-foreground hints, some have nothing.
- **Suggested fix:** Document a rule (always-visible for constraints/format hints; tooltips only for icons).

### U-024: Cancel/dismiss without unsaved-changes warning on ClientForm/YachtForm

- **Files:** `src/components/clients/client-form.tsx`, `src/components/yachts/yacht-form.tsx`
- **What:** `InterestForm.requestClose()` (line 123) checks `isDirty` and shows discard AlertDialog; `CompanyForm` also has it. ClientForm and YachtForm don't — sheet closes immediately.
- **Suggested fix:** Add `isDirty` guard + discard AlertDialog matching InterestForm pattern.

### U-031: FileUploadZone size limit not surfaced as client-side check

- **File:** `src/components/files/file-upload-zone.tsx:170`
- **What:** Accept attribute lists extensions; "up to 50MB" copy at line 163; no client-side size check before upload. Server-side check fails silently with "Upload failed" at line 103.
- **Suggested fix:** Wire client-side size check before upload; show clear "File too large" message.

### U-044: No jump-to-page input in pagination

- **File:** `src/components/shared/data-table.tsx:420`
- **Suggested fix:** Add small `<input type="number">` between Previous/Next.

### U-048: No column resize/reorder on DataTable

- **File:** `src/components/shared/data-table.tsx`
- **What:** Visibility supported via `ColumnPicker`; widths fixed; no drag-reorder.
- **Suggested fix:** Opt-in `enableColumnResizing` per table via TanStack Table v8 `onColumnSizingChange`.

### U-069: Invoice delete uses custom overlay, not AlertDialog

- **File:** `src/app/(dashboard)/[portSlug]/invoices/page.tsx:167`
- **What:** Hand-rolled `<div className="fixed inset-0 bg-background/80 backdrop-blur-xs z-50 ...">` rather than `<AlertDialog>` / `<ConfirmationDialog>`. Lacks focus trap, Escape, role="alertdialog".
- **Suggested fix:** Replace with `<ConfirmationDialog>` matching pattern elsewhere.

### U-074: Success toast missing on ClientForm + InterestForm create/edit

- **Files:** `src/components/clients/client-form.tsx:215`, `src/components/interests/interest-form.tsx:235`
- **What:** `onSuccess` invalidates queries + closes sheet, no `toast.success()`. `ComposeDialog.onSuccess:81` does fire one.
- **Suggested fix:** `toast.success(isEdit ? 'Client updated' : 'Client created')`.

### U-080: Logo preview `<img alt="">` should describe state

- **File:** `src/components/admin/shared/settings-form-card.tsx:420`
- **Suggested fix:** Use `alt="Port logo preview"` or dynamic from field label.

### U-081: Heading hierarchy inconsistent within tab components

- **Files:** `email-accounts-list.tsx:114`, `interest-contract-tab.tsx:130/251/291/364` (h2 → h3 → h2 jumps)
- **Suggested fix:** Audit each tab; standardize h2 = primary section, h3 = sub-section; never h2 after h3 at same nesting depth.

### U-086: DialogContent missing aria-describedby on minimal-content dialogs

- **File:** `src/components/email/compose-dialog.tsx:95` and ~40 other dialogs
- **What:** Only `file-preview-dialog.tsx:82` explicitly suppresses the Radix warning.
- **Suggested fix:** Add `<DialogDescription className="sr-only">...</DialogDescription>` or `aria-describedby={undefined}` to suppress.

### U-091: Mobile topbar title blank on list pages

- **Files:** `client-list.tsx`, `yacht-list.tsx`, `interest-list.tsx`, `berth-list.tsx`
- **What:** `useMobileChrome` only called from detail pages. List pages leave topbar in fallback (no title, stale from previous detail page).
- **Suggested fix:** Add `useMobileChrome({ title, showBackButton: false })` per list with cleanup pattern.

### U-093: Invoices missing from mobile navigation

- **File:** `src/components/layout/mobile/more-sheet.tsx:54`
- **What:** Not in `MORE_GROUPS`, not in bottom tabs. Mobile users can only reach via direct URL.
- **Suggested fix:** Add `{ label: 'Invoices', icon: FileText, segment: 'invoices' }` to Operations group.

---

## ✅ Sample passing checks

- U-001-008 list empty states + skeletons clean across clients/yachts/interests/berths/companies/reservations/invoices/email-threads
- U-012 FileUploadZone drag-hover with `border-primary bg-primary/5`
- U-023 field-level errors via react-hook-form `formState.errors` consistent
- U-026 BulkAddBerthsWizard + CatchUpWizard persist state across step nav
- U-027 phone E.164 via `formatAsYouType` emits `{ e164, country }`
- U-029 native `<input type="date">` provides browser calendar + keyboard
- U-033 Combobox keyboard nav inherited from Radix `<Command>` primitives
- U-040 Sort indicators via `getSortIcon` (`ArrowUpDown`/`ArrowUp`/`ArrowDown`)
- U-041/042 Filter chip dismiss + Clear-all in FilterBar
- U-043 page size selector 25/50/100/250/All
- U-049 virtual list via `@tanstack/react-virtual` (`virtual virtualHeightPx={640}` in audit log)
- U-054 STAGE_BADGE in `src/lib/constants.ts:100` — 7 distinct stages with distinct Tailwind colour families
- U-055 outcome badge: won=emerald, lost\_\*=rose, cancelled=slate
- U-057 status-pill covers all required document statuses
- U-060/061 button hierarchy + destructive red consistent
- U-065 Sheet used for forms+previews on both desktop and mobile (23 components)
- U-067 AlertDialog used for destructive confirmations (`useConfirmation`, `ArchiveConfirmDialog`, `ConfirmationDialog`, `BulkHardDeleteDialog`)
- U-070-072 click-outside, Esc, focus-trap, focus-restore all inherited from Radix
- U-073 toast position consistent (sonner top-right)
- U-075 `toastError()` (`src/lib/api/toast-error.ts:43`) surfaces requestId + Copy ID action — used in 89 files
- U-094 iOS safe-area-inset comprehensive (`pb-safe-bottom`, `pt-safe-top`, FAB `calc(env(safe-area-inset-bottom)+86px)`)
- U-097 visualViewport handling on mobile-search-overlay
- U-092 More sheet covers Documents/Interests/Yachts/Companies/Residential/Alerts/Reminders/Expenses/Reservations/Reports/Analytics/Settings/Admin