# V1-AMOB-018 — Admin Mobile Redesign Inventory

Status: v1.0 Owners: Oshun Admin Mobile design + engineering Scope: Admin Mobile
Experience Overhaul (section 18.4 of the OSHUN V1 Execution Backlog)

This document is the canonical input for the downstream redesign tasks
(V1-AMOB-019 through V1-AMOB-023) and the signoff coverage in V1-AMOB-024 /
V1-AMOB-025. Every redesign decision for the admin mobile cockpit references one
of the surfaces enumerated here; every Maestro signoff flow asserts at least one
of the success criteria attached to those surfaces.

A machine-readable copy of the same content lives at
`apps/oshun/admin-mobile/src/design/adminMobileRedesignInventory.ts` so tests
can enforce coverage, drift-protection, and redesign-owner-task alignment.

## Why this inventory exists

The admin mobile cockpit ships nine surfaces that carry operator decision
weight: the Urgent tab home, the compact review card, the review action sheet,
the incident acknowledgement view, the high-priority support case handling view,
the creator/reviewer inbox, the escalation push entry (foreground banner), the
step-up challenge screen, and the offline-safe retry surface.

Each surface already passes the charter's baseline rules (scope gating, step-up
posture, touch-target floors, a11y audit). The redesign program does not replace
those rules — it tightens the operator ergonomics on top of them.

## How to read each entry

Each entry has five fixed sections:

- **Current state** — one sentence capturing what the surface looks like today,
  so the redesign author knows what is being changed.
- **Goals** — the outcome the redesign must achieve. Framed as operator-visible
  verbs, not visual tweaks.
- **Constraints** — non-negotiables inherited from the shell charter. A redesign
  that violates a constraint is a regression, not a tradeoff.
- **Success criteria** — observable / testable checks. The signoff Maestro flows
  in V1-AMOB-024 / V1-AMOB-025 assert these directly.
- **Component touchpoints** — the shell files the redesign will modify, so code
  review can bound blast radius.

## Surfaces

### `urgent-queue-home` — Urgent queue home (owner: V1-AMOB-019)

|                       |                                                                                                                                                                                                                                                                                                         |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Priority              | critical                                                                                                                                                                                                                                                                                                |
| Current state         | Stats strip + compact urgent queue list + assignment overview with pull-to-refresh and offline banner. Navigation is top-loaded and requires two hands on taller devices to reach the stats tiles.                                                                                                      |
| Goals                 | Orient operators to the top three signals (total urgent, overdue, assigned-to-me) in a single thumb-reach zone. Keep the primary action reachable from the bottom third of the viewport on phones up to 6.7 inches. Make the offline banner persistent but non-blocking.                                |
| Constraints           | Workspace-scoped BFF payloads remain canonical. Severity colors stay aligned with shell tokens. Scroll position is preserved across refresh events.                                                                                                                                                     |
| Success criteria      | Operator can reach the retry/primary card from the bottom half of the viewport without shifting grip. Stats tiles have ≥44pt touch targets with urgent total, overdue, and assigned-to-me in the top viewport. Maestro signoff confirms the Urgent tab renders within 1s after a cached-view hydration. |
| Component touchpoints | `AdminMobileUrgentStats`, `AdminMobileUrgentQueueList`, `AdminMobileAssignmentOverview`, `AdminMobileOfflineBanner`                                                                                                                                                                                     |

### `review-card` — Compact review card (owner: V1-AMOB-020)

|                       |                                                                                                                                                                                                                                                                  |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Priority              | critical                                                                                                                                                                                                                                                         |
| Current state         | Severity rail + chip row (severity, SLA, artifact class, escalation, governance), artifact title, stage subtitle, assignee footer with blocker count.                                                                                                            |
| Goals                 | Sharpen severity scanning so operators identify critical / high items in under 250ms. Eliminate adjacent high-stakes tap targets that currently sit within 6pt of each other. Collapse secondary metadata under a reveal so the card keeps a 3-row scan profile. |
| Constraints           | Artifact class, escalation, and governance stay first-viewport signals when present. Severity chip cannot demote below `deriveAdminMobileReviewSeverity`. Card tap still routes through the existing workspace path.                                             |
| Success criteria      | All primary targets have ≥8pt spacing between centers. Every severity chip passes a 4.5:1 text-to-background contrast audit. Maestro signoff asserts card height stays within 132–168pt across severities.                                                       |
| Component touchpoints | `AdminMobileReviewCard`                                                                                                                                                                                                                                          |

### `review-action-sheet` — Review action sheet (owner: V1-AMOB-020)

|                       |                                                                                                                                                                                                                                                                                                                 |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Priority              | critical                                                                                                                                                                                                                                                                                                        |
| Current state         | Scope + step-up gated action sheet with three decision buttons, rationale textarea, submit button, scope/step-up notice strips.                                                                                                                                                                                 |
| Goals                 | Put the most common decision (approve) in the dominant thumb-reach zone without making reject / request-changes harder to find. Surface validation state inline against the rationale textarea without pushing submit off-screen. Keep the step-up redirect CTA in the notice strip rather than the action row. |
| Constraints           | Rationale length rules come from `@oshun/contracts`. Pending-high-risk-approval outcome always renders above submit. Submit stays disabled until every gate is satisfied.                                                                                                                                       |
| Success criteria      | Rejecting with a 3-character rationale keeps submit disabled and surfaces an inline error within one frame. Approve button is reachable without grip change on 6.7-inch phones. Maestro signoff asserts rationale-too-long surfaces the critical chip.                                                          |
| Component touchpoints | `AdminMobileReviewActionSheet`                                                                                                                                                                                                                                                                                  |

### `incident-acknowledgement` — Incident acknowledgement (owner: V1-AMOB-021)

|                       |                                                                                                                                                                                                                                                                    |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Priority              | critical                                                                                                                                                                                                                                                           |
| Current state         | Severity rail + chip row + Acknowledge button. Meta block, impacted workspaces, and the recent-timeline section live below the fold on small devices.                                                                                                              |
| Goals                 | Make the posture chip the strongest visual signal at first glance. Keep Acknowledge above the fold on 5.4-inch phones. Reduce timeline visual noise while preserving the five most recent events.                                                                  |
| Constraints           | Posture derivation comes from `derivePosture`. Button stays disabled for terminal + already-acknowledged incidents. Affected-users / error-rate rows only appear when the BFF populates them.                                                                      |
| Success criteria      | Acknowledge button is visible in the initial viewport for sev-0 / sev-1 on 5.4-inch phones. Terminal incidents render without a tappable Acknowledge anywhere. Maestro signoff verifies the next-update-overdue chip turns red when the update window has elapsed. |
| Component touchpoints | `AdminMobileIncidentAcknowledgement`                                                                                                                                                                                                                               |

### `support-case-handling` — Support case handling (owner: V1-AMOB-021)

|                       |                                                                                                                                                                                                                                                                                              |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Priority              | high                                                                                                                                                                                                                                                                                         |
| Current state         | Severity-aware view with chip row (severity, status, SLA, posture, entitlement), meta block, newest customer message, linked cases, and pick-up / escalate actions.                                                                                                                          |
| Goals                 | Preserve single-viewport layout while adding a response-time countdown adjacent to the SLA chip. Cluster pick-up + escalate actions with matched visual weight so operators never mistake one for the other. Surface customer-entitlement severity promotion visually, not only through MRR. |
| Constraints           | Severity promotion rules from `deriveSupportSeverity` stay authoritative. Escalate stays disabled when posture is resolved / closed. Unread inbound badge cannot regress below 16pt.                                                                                                         |
| Success criteria      | Pick-up and escalate actions share a row with equal vertical padding. Entitlement chip carries a distinct border for paid vs trial tiers. Maestro signoff asserts the handling view still renders the newest customer message when the case has 20+ interactions.                            |
| Component touchpoints | `AdminMobileSupportCaseHandling`                                                                                                                                                                                                                                                             |

### `creator-reviewer-inbox` — Creator & reviewer inbox (owner: V1-AMOB-020)

|                       |                                                                                                                                                                                                                                                                      |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Priority              | high                                                                                                                                                                                                                                                                 |
| Current state         | Severity-tinted rows grouped by delivery lane (alert first, banner second). Silent notifications are dropped.                                                                                                                                                        |
| Goals                 | Promote alert-lane entries so they are identifiable without reading the header. Keep the creator / reviewer / delegate pill readable alongside the lane pill without line-wrapping on 375pt widths. Preserve deep-link routing to the review workspace on every row. |
| Constraints           | Operator delivery preferences continue to suppress muted kinds entirely. Row heights comply with `touchTargetMin`.                                                                                                                                                   |
| Success criteria      | Alerts render with a distinct left rail that is visibly separate from banner entries. No entry exceeds three lines of text at a 375pt width. Maestro signoff asserts alerts sort ahead of banners in the inbox list.                                                 |
| Component touchpoints | `AdminMobileCreatorReviewerInbox`                                                                                                                                                                                                                                    |

### `escalation-push-entry` — Escalation push entry (owner: V1-AMOB-023)

|                       |                                                                                                                                                                                                                                                              |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Priority              | critical                                                                                                                                                                                                                                                     |
| Current state         | Foreground banner with severity-tinted palette, tap-through routing, auto-dismiss. Tap routes to the path emitted by `resolveAdminMobileEscalationRoute`.                                                                                                    |
| Goals                 | Add haptic feedback on banner reveal (medium impact on sev-0, light on sev-1, none on advisory). Preserve motion-sensitivity: operators with reduced-motion preferences see a fade instead of a slide. Never block navigation while the banner is animating. |
| Constraints           | Banner still auto-dismisses after the configured interval. Safe-area insets respected on notched devices. Deep-link sanitization rules from the payload parser cannot be bypassed.                                                                           |
| Success criteria      | Banner does not intercept taps on the underlying tab bar. Reduced-motion operators see fade-only animation. Maestro signoff asserts sev-0 banner reveal fires the configured haptic.                                                                         |
| Component touchpoints | `AdminMobileForegroundBanner`, `AdminMobileNotificationBridge`                                                                                                                                                                                               |

### `step-up-challenge` — Step-up challenge (owner: V1-AMOB-023)

|                       |                                                                                                                                                                                                                                                                                                           |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Priority              | critical                                                                                                                                                                                                                                                                                                  |
| Current state         | Route-level screen that runs the injected authenticator and redirects back to the requesting workspace on success.                                                                                                                                                                                        |
| Goals                 | Make the challenge feel contiguous with the workspace it interrupts (same severity chrome, breadcrumb to the source). Add a confirmation layer for hardware-token challenges so operators understand what they are attesting to. Make cancel a visible secondary action, not a back-gesture escape hatch. |
| Constraints           | Redirect target sanitizes to a same-app URL — no open redirect through `returnTo`. Authenticator errors map to typed `AdminMobileStepUpChallengeError` codes. Per-workspace step-up requirements stay authoritative.                                                                                      |
| Success criteria      | Operators on 6.7-inch phones can tap cancel without shifting grip. Challenge screen renders a visible breadcrumb to the source workspace. Maestro signoff asserts a failed hardware-token challenge routes back to Unauthorized with the canonical reason.                                                |
| Component touchpoints | `app/step-up.tsx`, `AdminMobileStepUpChallengeError`                                                                                                                                                                                                                                                      |

### `offline-retry` — Offline / degraded connectivity retry (owner: V1-AMOB-022)

|                       |                                                                                                                                                                                                                                                                                                                                                                       |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Priority              | high                                                                                                                                                                                                                                                                                                                                                                  |
| Current state         | Offline banner on the Urgent tab with three lanes (offline / cached-stale / cached-fresh). Hook auto-refreshes on reconnect.                                                                                                                                                                                                                                          |
| Goals                 | Preserve the banner's copy while making the reconnect transition explicit (banner morph rather than disappear). Provide an explicit "Retry now" action embedded in the banner for operators who cannot wait for the subscription-triggered refresh. Keep the cached view fully interactive while offline — only decisions that mutate remote state should be blocked. |
| Constraints           | Cache invalidation rules stay authoritative (version mismatch, hard expiry, cross-operator). Auto-refresh on reconnect cannot run while the disabled flag is set. Banner does not block the stats strip from being readable.                                                                                                                                          |
| Success criteria      | Offline banner exposes a visible retry action. Cache-stale banner disappears automatically within 300ms of a successful refresh. Maestro signoff covers the three offline banner lanes.                                                                                                                                                                               |
| Component touchpoints | `AdminMobileOfflineBanner`, `useAdminMobileUrgentQueue`, `AdminMobileOfflineRuntime`                                                                                                                                                                                                                                                                                  |

## Signoff

This inventory is the source of truth for the admin mobile experience overhaul.
Every downstream redesign task (V1-AMOB-019 through V1-AMOB-023) closes with a
pointer to the surfaces it touched here; V1-AMOB-024 / V1-AMOB-025 extend the
Maestro signoff suite to cover each success criterion above.
