> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Prominent Back Control QA

> Verify the back navigation control is an outline-bordered button with a visible "Back" label across mobile and desktop surfaces.

* **Scope:** All surfaces using `BackNav`, `DetailPageLayout` (via `backHref`/`onBack`), and `MobileHeader`.
* **Owner:** PF mobile UX
* **Related:** PF-37 (mobile navigation), `BackNav.tsx`, `DetailPageLayout.tsx`, `MobileHeader.tsx`
* **Last updated:** 2026-06-02
* **Automated coverage:** `tests/e2e/platform/prominent-back-button.spec.ts`

***

## Visual + behavior standard (enforced)

Every back control must:

1. ✅ Render as an **outline button** (visible border, not ghost/transparent).
2. ✅ Show a visible **"Back" label** beside the icon (or context-specific, e.g. "Back to Reports").
3. ✅ **Desktop:** always visible on sub-pages. **Mobile:** the global MobileHeader back button is the sole back affordance — in-page `BackNav` is suppressed automatically by `PageHeader` and `DetailPageLayout`.
4. ✅ Meet a **minimum 44 × 44 px touch target** (`touch-target-h` class applied).
5. ✅ Provide `aria-label` for screen readers; icon is `aria-hidden`.
6. ✅ No double-back on mobile (two back controls with possibly different destinations).

**Icon:** `ArrowLeft` only — `ChevronLeft` is reserved for non-back controls (e.g. collapse, breadcrumbs).

***

## Mobile back architecture (decision)

**One** global back button lives in `MobileHeader` (via `useMobileBack`). All page-level back primitives (`PageHeader.backNav`, `DetailPageLayout`) suppress on mobile. Pages with a materially different back destination may opt in via `forceBackNavOnMobile={true}` on `PageHeader`.

***

## Pre-flight

1. Sign in to the **NorthSight Recovery** test org using the credentials in [`docs/testing/TESTING_SETUP_AND_RUN.md`](/testing/TESTING_SETUP_AND_RUN) (§9 AI / interactive browser testing).
2. Open browser devtools and set the viewport to **390 × 844** (iPhone 12/13/14 baseline).
3. Have a second viewport ready at **1280 × 720** (desktop baseline).
4. Use a recent Chromium build (Chrome/Edge ≥ 122) for the primary pass.

***

## Pass / fail rule

For every route below, confirm **all assertions** at both viewport sizes where applicable:

1. ✅ Desktop: outline button with visible label renders above the page title.
2. ✅ Desktop: clicking navigates to the correct parent.
3. ✅ Desktop touch target ≥ 44 × 44 px.
4. ✅ Mobile: only MobileHeader back button is visible (no in-body duplicate).
5. ✅ Mobile: MobileHeader back button is hidden on root dashboards (no back from home).

Mark ❌, capture screenshot, and file a bug referencing this checklist on any failure.

***

## Shared primitives

| #  | Surface                                   | Component                                       | Desktop ✓ | Mobile ✓ | Notes                                            |
| -- | ----------------------------------------- | ----------------------------------------------- | :-------: | :------: | ------------------------------------------------ |
| P1 | Mobile header back control                | `MobileHeader` → `BackNav` (ArrowLeft + "Back") |     —     |     ☐    | Visible when navigating to any sub-route         |
| P2 | Mobile header hidden on root              | `MobileHeader` root guard                       |     —     |     ☐    | Hidden on `/fa/dashboard`, `/hr/dashboard`, etc. |
| P3 | Detail page back via `backHref`           | `DetailPageLayout backHref`                     |     ☐     |     ☐    | Suppressed on mobile                             |
| P4 | Detail page back via `onBack`             | `DetailPageLayout onBack`                       |     ☐     |     ☐    | e.g. AZA1R/AZA1QRT review pages                  |
| P5 | Create page back via `PageHeader.backNav` | `BackNav` in `PageHeader.backNav`               |     ☐     |     ☐    | Suppressed on mobile                             |

***

## Migrated inline back buttons (representative sample)

| #  | Route / File                                                 | Desktop ✓ | Mobile ✓ | Notes          |
| -- | ------------------------------------------------------------ | :-------: | :------: | -------------- |
| 1  | `/fa/reports/statement-of-activities`                        |     ☐     |     ☐    | FA report page |
| 2  | `/fa/bills/new`                                              |     ☐     |     ☐    | FA create page |
| 3  | `/fa/purchase-orders/new`                                    |     ☐     |     ☐    | FA create page |
| 4  | `/hr/ats/interviews`                                         |     ☐     |     ☐    | HR ATS         |
| 5  | `/hr/engagement/surveys/:id`                                 |     ☐     |     ☐    | HR engagement  |
| 6  | `/hr/benefits/plans/:id`                                     |     ☐     |     ☐    | HR benefits    |
| 7  | `/hr/employee-relations/incidents/:id`                       |     ☐     |     ☐    | HR ER          |
| 8  | `/it/vendors/new`                                            |     ☐     |     ☐    | IT new vendor  |
| 9  | `/gr/governance-risk/accreditation`                          |     ☐     |     ☐    | GR reports     |
| 10 | `/rh/residences/:id`                                         |     ☐     |     ☐    | RH detail      |
| 11 | `/fm/maintenance-cost-report`                                |     ☐     |     ☐    | FM report      |
| 12 | `/it/knowledge-base/new` — `NewKnowledgeBaseArticlePage.tsx` |     ☐     |     ☐    |                |
| 13 | `/hr/engagement/action-plans/new` — `ActionPlanFormPage.tsx` |     ☐     |     ☐    |                |
| 14 | Document version comparison — `VersionComparisonView.tsx`    |     ☐     |     ☐    |                |

***

## Intentional skips (inline back not migrated — documented)

These files have inline back controls that cannot be cleanly migrated yet (complex action clusters, wizard-step dual-use, `ListPageLayout.actions`). Tracked in `INTENTIONAL_SKIP_ALLOWLIST` in `scripts/audit/audit-back-navigation.ts`.

| File                                        | Reason                                                          |
| ------------------------------------------- | --------------------------------------------------------------- |
| `fa/pages/FunctionalExpensesMatrixPage.tsx` | Back in `ListPageLayout.actions`, competes with primary actions |
| `fa/pages/CashFlowDirectPage.tsx`           | Back in `ListPageLayout.actions`                                |
| `fa/pages/BatchReimbursementPage.tsx`       | Back icon beside process-selected CTA                           |
| `fa/pages/PaymentPlanCreatePage.tsx`        | Link + visible label (already acceptable UX; future cleanup)    |
| `fa/pages/ExpenseReportNewPage.tsx`         | Dual back affordances (header + error branch)                   |

***

## Icon-only opt-outs

These surfaces pass `showLabel={false}` explicitly. Confirm the decision is still intentional and the touch target remains ≥ 44 × 44 px.

| # | Surface                       | Reason | Pass ✓ |
| - | ----------------------------- | ------ | :----: |
| — | *(none currently registered)* |        |        |

***

## Automated coverage

`tests/e2e/platform/prominent-back-button.spec.ts` covers:

* ✅ Desktop: outline button visible + border class present
* ✅ Desktop: touch target ≥ 36 px height (outline sm button)
* ✅ Mobile: at most one back button visible (no double-back)
* ✅ Mobile: header back visible on non-root routes
* ✅ Mobile: header back hidden on root dashboards

Run with: `npm run test:e2e -- tests/e2e/platform/prominent-back-button.spec.ts`

***

## Sign-off

| Field                                 | Value |
| ------------------------------------- | ----- |
| Tester name                           |       |
| Date                                  |       |
| Browser / version                     |       |
| All primitive rows green? (Y/N)       |       |
| All migrated inline rows green? (Y/N) |       |
| Bugs filed (links)                    |       |
| Notes                                 |       |

***

## Out of scope

* Wizard-shell step-back buttons — inside PF-41 wizard shells with their own navigation semantics.
* Pagination chevrons, carousel arrows, collapsible chevrons — excluded by design.
* Intentional skip files (documented in the table above).