# OSHUN V1 Visual Rhythm and Notification Density Audit

Status: completed on March 26, 2026

Related:

- `docs/releases/v1/design/customer-visual-thesis.md`
- `docs/releases/v1/design/admin-visual-thesis.md`
- `docs/releases/v1/scope/minimal-chrome-rules.md`
- `docs/releases/v1/scope/card-avoidance-rules.md`
- `docs/releases/v1/scope/scan-first-content-hierarchy-rules.md`
- `docs/releases/v1/scope/copy-compression-rules.md`

## Standard

The governing bar for this audit is unchanged:

- one dominant emphasis per section or working surface
- notification surfaces summarize first and expose inbox controls only where the
  inbox itself is the task
- dashboard and admin metrics stay readable without becoming a wall of equally
  loud cards
- review and operational actions stay scannable and secondary until the user
  needs them

This audit uses the customer/admin visual theses plus the minimal-chrome,
card-avoidance, scan-first hierarchy, and copy-compression rules as the
pass/fail source of truth.

## Scope

This audit covers the most visible rhythm and emphasis problems in the current
customer and admin surfaces:

- OSHUN web Home notification stack in `apps/oshun/web/src/app/page.tsx` and
  `apps/oshun/web/src/components/NotificationsCenterPanel.tsx`
- Metis admin shared KPI cards in `apps/metis/admin/src/components/StatCard.tsx`
- Metis admin dashboard and analytics surfaces that consume that shared card
- Metis admin course operations surface in
  `apps/metis/admin/src/app/courses/page.tsx`

Before implementation, the existing full-inbox behavior in
`NotificationsCenterPanel`, the home-page placement of that panel, the shared
`StatCard` implementation on dashboard and analytics, and the pre-existing
courses review queue plus row-action treatments were reviewed so the fix could
reuse working patterns instead of inventing a parallel UI language.

## Findings

### Customer surface deviation

Home mounted the full notification inbox directly into the landing surface:

- full unread/priority/total stat tiles
- inbox and domain filters
- mark-all-read controls
- per-card read and dismiss actions

That made Home compete with itself. The right pattern for Home was a high-signal
preview, not a full inbox workstation.

### Admin KPI deviation

Metis dashboard and analytics used the shared `StatCard` everywhere, but the old
treatment stacked large values, trend text, and supporting labels with too much
equal emphasis. The result was a repeated loud-card rhythm across multiple
surfaces.

### Admin review-queue deviation

The courses page used an alert-like review queue block and mixed row actions
with several strong fills. The queue was technically functional, but it pulled
too much visual weight away from filtering, scanning, and deciding.

## Implementation Approach Selected

The selected fixes preserved the working information model while reducing
competing emphasis:

- keep the full notification center behavior intact, but add a dedicated preview
  variant for dense surfaces like Home
- calm the shared `StatCard` once so dashboard and analytics both inherit the
  quieter hierarchy
- replace the courses alert-block posture with a triage posture: summary first,
  then a short queue preview, then the main table

## Changes Implemented

- added `variant="preview"` support to
  `apps/oshun/web/src/components/NotificationsCenterPanel.tsx`
- ranked preview notifications by signal, limited Home to three items, added a
  compact preview summary, and removed full-inbox controls from the Home surface
- switched the Home page in `apps/oshun/web/src/app/page.tsx` to the new preview
  variant
- extended customer automation with unit coverage for the preview behavior and
  Playwright coverage in `apps/oshun/web/e2e/home-notification-preview.spec.ts`
- calmed Metis shared KPI cards in
  `apps/metis/admin/src/components/StatCard.tsx` with smaller overline labels, a
  separate value/trend rhythm, and subdued helper copy
- reworked `apps/metis/admin/src/app/courses/page.tsx` around a calmer summary
  strip, a limited review-queue preview, softer filter chrome, and consistent
  pill actions
- added Metis unit coverage in `apps/metis/admin/src/app/courses/page.test.tsx`
- added Metis browser coverage in `apps/metis/admin/e2e/visual-rhythm.spec.ts`
  plus `apps/metis/admin/playwright.config.ts`

## Result

| Surface                | Previous failure mode                                      | Resolution                                                               | Result |
| ---------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------ | ------ |
| OSHUN web Home         | Full inbox controls crowded the landing UI                 | Home now renders only a high-signal preview                              | Pass   |
| Metis dashboard        | KPI cards repeated a loud, same-weight wall                | Shared cards now use calmer labels, trend pills, helper copy             | Pass   |
| Metis analytics        | KPI rhythm matched the same loud card wall                 | Shared card changes carry through analytics                              | Pass   |
| Metis courses workflow | Alert-style queue and noisy actions competed with scanning | Queue now previews only the next decisions and actions scan as secondary | Pass   |

## Verification

Focused verification that passes:

```bash
pnpm exec prettier --check \
  'apps/oshun/web/src/components/NotificationsCenterPanel.tsx' \
  'apps/oshun/web/src/app/page.tsx' \
  'apps/oshun/web/src/components/__tests__/NotificationsCenterPanel.test.tsx' \
  'apps/oshun/web/e2e/home-notification-preview.spec.ts' \
  'apps/metis/admin/src/components/StatCard.tsx' \
  'apps/metis/admin/src/app/courses/page.tsx' \
  'apps/metis/admin/src/app/courses/page.test.tsx' \
  'apps/metis/admin/e2e/visual-rhythm.spec.ts' \
  'apps/metis/admin/playwright.config.ts' \
  'apps/metis/admin/vitest.config.ts' \
  'apps/metis/admin/package.json' \
  'docs/releases/v1/audits/visual/rhythm-notification-density.md' \
  'docs/releases/v1/specs/readme.md' \
  'docs/releases/v1/specs/todos.md'

pnpm --dir apps/oshun/web exec eslint \
  'src/components/NotificationsCenterPanel.tsx' \
  'src/app/page.tsx' \
  'src/components/__tests__/NotificationsCenterPanel.test.tsx'

pnpm --dir apps/oshun/web exec vitest run \
  src/components/__tests__/NotificationsCenterPanel.test.tsx

pnpm --dir apps/oshun/web exec playwright test \
  e2e/home-notification-preview.spec.ts

pnpm --dir apps/metis/admin exec eslint --no-ignore \
  'src/components/StatCard.tsx' \
  'src/app/courses/page.tsx' \
  'src/app/courses/page.test.tsx' \
  'e2e/visual-rhythm.spec.ts' \
  'playwright.config.ts'

pnpm --dir apps/metis/admin exec vitest run \
  src/app/courses/page.test.tsx

pnpm --dir apps/metis/admin exec playwright test \
  e2e/visual-rhythm.spec.ts

pnpm --dir apps/metis/admin exec tsc --noEmit

pnpm --dir apps/metis/admin exec next build
```

Because `js_repl` is not available in the active Codex session, the
`playwright-interactive` workflow could not be executed as a persistent
interactive browser session here. The applicable browser QA still ran through
the repository Playwright CLI harnesses for both the customer and admin
surfaces.

Known repo-level blockers encountered during completion:

- `pnpm --dir apps/oshun/web exec tsc --noEmit` fails on pre-existing unrelated
  web issues outside this task, including an unused variable in
  `e2e/studio-bellona-build-artifact-management-smoke.spec.ts`, multiple
  analytics typing mismatches such as
  `src/analytics/studioApiGatewayBffCompositionTelemetry.ts`, and unrelated
  studio component token/property mismatches.
- `pnpm --dir apps/oshun/web exec next build` fails on pre-existing unrelated
  studio and analytics issues outside this task, including missing exported
  studio workspaces and the existing analytics client type incompatibility in
  `src/analytics/studioApiGatewayBffCompositionTelemetry.ts:61`.
