# Command Dashboard UX Acceptance + Read-only Module Detail Polish

Use this reference after a mock-only sensitive command dashboard already has a working gateway, frontend shell, store/API client, and local E2E harness. The goal is to mature the UI into a safer MVP command cockpit without adding real adapters or write flows.

## Scope guard

Keep the phase strictly mock-only and read-only:

- no real Finance/Health/AutoShorts endpoints
- no Health DB or Finance runtime
- no POST/mutations/uploads/restart/confirm/apply/report-generation
- no iframes, charts, tables on Home, screenshots/videos committed, or productive paths
- no exact finance values, health raw data, lab values, document names, secrets, or local runtime paths

## Recommended implementation pattern

1. Create shared module-detail components instead of polishing each page independently:
   - `ModuleDetailShell`
   - `ModuleHeroStatus`
   - `ModuleKpiGrid`
   - `ModuleSourceHealth`
   - `ModuleAttentionPanel`
   - `ModuleBlockedNotice`
   - `ModuleSafeLinks`
   - `ModuleActivityPanel`
2. Make Finance, Health, System, and any first-class module such as AutoShorts use the same shell.
3. If a module appears as a Home module card and has a primary action, add a safe read-only route for it rather than letting the action point to a generic or dead route. For AutoShorts, `/autoshorts` should show only review/package/queue metadata and blocked upload/confirm notices.
4. Source Health should expose only safe metadata: `reachable`, `stale`, `source_type`, `contract_version`, `last_success_at`. Do not render URLs, local paths, stack traces, process details, or provider secrets.
5. Module KPI blocks should cap at 3 KPIs from the existing `ModuleSnapshot`; do not invent new data.
6. Blocked actions should render as clear read-only blocked notices, never enabled-looking buttons.

## UX acceptance E2E checks

Add Playwright acceptance tests against the real local mock Gateway + Dashboard:

- Home: max 5 attention items, 4 module cards, max 3 KPIs/card, no tables, no canvas/charts, no iframes, no horizontal scroll.
- Detail pages: `/finance`, `/health`, `/system`, `/approvals`, `/reports`, and module-specific pages like `/autoshorts` render safe states.
- Navigation: every module-card detail link has a valid destination and no primary action goes nowhere.
- iPad: BottomNav visible, touch targets >= 44px, no horizontal scroll.
- Desktop: Sidebar visible, BottomNav hidden/non-dominant, sticky header present.
- Accessibility-light: `main` and `nav` exist; keyboard Tab reaches links; status and blocked states have text, not color-only signals.

Keep this as a separate local target such as `make ux-acceptance`; do not add browser E2E to fast `make verify` unless CI/browser setup is deliberately hardened.

## Pitfalls discovered

- Playwright/Vue tests must wait for async rendering before counting cards or links. Prefer `await expect(locator.first()).toBeVisible()` or `toHaveCount(4)` before evaluating arrays.
- Avoid regex headings like `/Übersicht/` when another heading contains the same word (`Modulübersicht`). Use exact accessible names.
- Safety copy can itself violate safety tests. Do not display forbidden words like lab/raw-data field names just to say they are forbidden; use neutral phrasing such as “nur sichere Status- und Pipeline-Metadaten”.
- In Vite dev mode, full `page.content()` can include local file paths in injected dev CSS. For UI safety E2E, scan visible text and the app root DOM (`#app`) rather than the entire dev document.
- Tailwind `lg` starts at 1024px, which collides with iPad landscape. If iPad should use BottomNav, switch desktop shell breakpoints to `xl`.
- When adding a new module route, update unit-test stub routers too, or tests may pass with noisy Vue Router warnings.

## Documentation updates

Update:

- root README
- dashboard README
- dashboard local-dev runbook
- visual QA checklist
- UI acceptance checklist
- a phase-specific text report under `docs/qa/`, explicitly stating no screenshots/videos were committed

## Verification checklist

Run and report real outputs:

- `make dashboard-test`
- `make dashboard-build`
- `make test-gateway`
- `python3 scripts/verify-repo-safety.py`
- `make verify`
- `make ux-acceptance` if added
- `make e2e-local` if Playwright/Chromium is available