Implementation spec for the Phase 17.10 reduction of modal and drawer overuse. Goal: define preferred patterns for inline review, side-panel inspection, and staged confirmation.
Reference: as-is#
The admin app today opens a modal or drawer for almost any action with side-effects. Surveyed surfaces (per the V1-AWEB-092 inventory):
- Modal-driven:
ReviewHighRiskApprovalPanel(high-risk confirmation),RetentionManagementPanel(legal-hold release), several trust-safety lists (offender history dialog, appeal context),PolicyBundleEditorPanel(deploy confirmation),IncidentRunbookPostmortemPanel(close postmortem dialog). - Drawer-driven:
UnifiedInboxPanel(row inspection),ResearchIntegrityCopilotPanel(suggestion details),CitationValidationWorkspacePanel(citation drawer),AvatarPackReviewPanel(gate detail drawer). - Inline expansion:
ResearchSourceReviewPanel(per-citation re-review form expands inline),ResearchComparativePromotionPanel(per-card forms inline),ResearchReportPolicyGatingPanel(3-form grid inline),PrivacyConsentAuditPanel(per-card forms inline).
As-is pain points#
- Operators lose context on modal open. A modal blanks the queue; the operator's place in the list is lost.
- Drawers compete with the action rail (V1-AWEB-094). A row drawer + a sticky right-edge action rail occupy the same screen real estate.
- Confirmation modals stack. Some flows trigger modal → confirm → second modal; operators report "modal fatigue".
- Inline forms scale with row count. A 60-row queue with inline forms can render 60 expanded forms simultaneously (depending on panel logic).
- No consistent close affordance. Some modals close on Esc, some on
backdrop click, some only on explicit
Cancel.
Pattern decisions#
The redesign formalises three action-affordance patterns with strict applicability rules.
1. Inline review (preferred)#
Use when: the action is reversible, low-risk, single-step, and self-contained on the row's data (no second screen needed).
Examples to keep inline: V1-AWEB-085 comparative-text verdict, V1-AWEB-086 hallucination review, V1-AWEB-087 consent review, V1-AWEB-089 conversation note. All four already follow the inline pattern.
Render rule: the form expands beneath the row card, never beside it. Only one inline form is open at a time per panel (opening another collapses the previous).
2. Side-panel inspection (preferred for inspection)#
Use when: the operator needs to read more context than the row shows, but the action set is the same as the row's inline actions.
Examples to migrate: UnifiedInboxPanel row drawer (already a side panel),
CitationValidationWorkspacePanel citation drawer.
Render rule: the side panel is the right column of the master-detail split
(V1-AWEB-094). Opening a row updates the URL hash; closing returns the operator
to the queue with the hash cleared. Side panel does NOT trap focus; operators
can keep j/k-navigating the queue with the side panel open.
3. Staged confirmation (modal — only for irreversible)#
Use when: the action is irreversible, destructive, or requires elevated confirmation (high-risk approval, legal hold release, deploy to production, force-close incident).
Render rule: a single modal layer with three required sub- sections:
- Action summary — what will happen.
- Reversibility note — what cannot be undone.
- Confirmation control — typed confirmation (e.g., type the case id) for
the most destructive actions; otherwise an explicit
Confirmbutton with a keyboard-requiredTab + Enterto activate (no auto- focus on the confirm button).
The modal closes on Esc, backdrop click, or explicit Cancel. The modal does
NOT auto-focus the destructive button.
Anti-patterns (banned by the spec)#
- Modal that opens a second modal.
- Drawer that opens a modal that opens a drawer.
- Inline form that simultaneously renders for >1 row in the same panel.
- Modals that auto-focus the destructive action.
- Drawers that trap focus, preventing keyboard queue navigation.
Implementation deliverables#
apps/oshun/admin/src/components/AdminConfirmationModal.tsx.module.css— canonical modal with the three required subsections + typed-confirmation prop.
- Audit + migration of every existing modal usage:
ReviewHighRiskApprovalPanel→ adopt typed confirmation.RetentionManagementPanellegal-hold release → adopt typed confirmation.PolicyBundleEditorPaneldeploy → adopt typed confirmation.IncidentRunbookPostmortemPanelclose → adopt typed confirmation.- Trust-safety modals → migrate offender-history / appeal-context modals to side panels (Pattern 2).
- Audit + migration of every existing drawer usage:
UnifiedInboxPaneldrawer → migrate to master-detail side panel (V1-AWEB-094).ResearchIntegrityCopilotPanelsuggestion drawer → migrate to side panel.CitationValidationWorkspacePanelcitation drawer → migrate to side panel.AvatarPackReviewPanelgate-detail drawer → migrate to side panel.
- Inline form audit: confirm only one inline form is open per panel at a time across all V1-AWEB-085/086/087/088/089 panels.
- Tests: confirmation modal component test (typed confirmation flow),
Playwright
admin-modal-drawer.spec.tscovering Esc / backdrop close, no auto-focus on destructive, drawer-doesn't-trap-focus.
Acceptance criteria#
- Every existing modal in the admin app falls into Pattern 3 (staged confirmation) or has been migrated to Pattern 1 / 2.
- No modal opens another modal; no drawer opens a modal.
- Side-panel drawers do NOT trap focus; the operator can
j/k-navigate the queue while the drawer is open. - Confirmation modals do NOT auto-focus the destructive button; they require an
explicit
Tab + Enter. - Per-panel inline form rule: only one open at a time.
- Confirmation modal component test + Playwright spec pass.