TenantAtlas/docs/ui-ux-enterprise-audit/README.md

# Tenantial Enterprise UI Audit

Spec 323 establishes the docs-only UI Design Registry baseline for Tenantial/TenantPilot. It records what UI surfaces exist, how they are classified, which pages were reviewed in the browser, and which later design lane should own each surface.

This audit did not change runtime UI, routes, authorization, database schema, business logic, tests, assets, packages, queues, scheduler, or deployment scripts.

## Outputs

- `route-inventory.md`: master route/page inventory with audit IDs, scope, archetype, design depth, repo-truth level, screenshots, reports, and notes.
- `page-reports/`: concise page-level reports for reviewed or browser-blocked pages.
- `design-coverage-matrix.md`: roll-up counts by area, archetype, design depth, and missing coverage.
- `strategic-surfaces.md`: P0/P1/P2 strategic pages that need individual target mockups or explicit product treatment.
- `grouped-follow-up-candidates.md`: grouped later specs so small pages do not become one spec per page.
- `unresolved-pages.md`: browser blockers, record/detail routes requiring seeded data, and manual-review surfaces.
- `screenshots/desktop/`: desktop current-state screenshots and blocker evidence from the local browser pass.
- `templates/`: reusable templates for future UI audit updates.

## Spec 325 Target Experience Artifacts

Spec 325 adds screenshot-anchored strategic target direction without changing runtime UI.

- `target-experience-briefs/README.md`: entry point for selected surface briefs.
- `target-experience-briefs/strategic-target-image-shortlist.md`: proportional 9-surface shortlist, selected/deferred rationale, and source links.
- `target-images/README.md`: accepted target images and sidecar index.
- `target-images/target/`: dark/light PNG target images plus sidecar Markdown files.
- `target-images/reference/spec-325-premium-reference/`: user-accepted premium visual reference set used to calibrate the regenerated target images.
- `target-images/source/README.md`: source screenshot reuse policy.
- `target-images/problem-annotations/README.md`: annotation policy for future waves.
- `follow-up-specs/325-strategic-target-image-implementation-candidates.md`: grouped runtime implementation candidates derived from the target artifacts.

Spec 325 selected Workspace Overview, Environment Dashboard, Operations Hub, Governance Inbox, Customer Review Workspace, Audit Log, Restore Safety Workflow, Provider Readiness, and Baseline Compare / Drift. Runtime implemented remains `No` for every Spec 325 artifact.

The Spec 325 dark target PNGs are the primary premium visual target direction. Light variants remain support artifacts because Filament includes light mode by default.

## Discovery Basis

Spec 323 used multiple repo-based discovery methods:

- `cd apps/platform && ./vendor/bin/sail artisan route:list --json`
- Laravel Boost route listing for non-vendor route confirmation
- File discovery in `apps/platform/app/Filament/Pages`, `Resources`, `Clusters`, `System/Pages`, `Livewire`, `resources/views`, and `routes`
- Panel inspection in `apps/platform/app/Providers/Filament` and `apps/platform/bootstrap/providers.php`
- Navigation inspection through `WorkspaceHubRegistry`, `WorkspaceSidebarNavigation`, and `AdminSurfaceScope`
- Browser pass through `http://localhost/admin/local/smoke-login?redirect=/admin`

The browser pass used the existing local Spec 180 smoke fixture. No seeders, factories, runtime fixtures, or app code were added to make pages easier to capture.

## Classification Model

Every inventory row receives:

- **Primary archetype**: one of the allowed Spec 323 page archetypes.
- **Design depth**: `Strategic Surface`, `Domain Pattern Surface`, `Design-System Cleanup Surface`, `Internal / Deprecated / Hidden`, or `Manual Review Required`.
- **Repo truth**: `repo-verified`, `plausible-existing`, `foundation-only`, `spec-only`, `conceptual-future-state`, or `unknown`.

Repo-truth labels are intentionally strict. A page can be repo-verified as a route while still requiring manual review for its final product treatment if auth, data, record state, or provider state blocks meaningful browser inspection.

## Reading The Audit

Start with `design-coverage-matrix.md` for counts and gaps, then use `route-inventory.md` for row-level classification. Page reports provide the first design review for strategic and representative domain surfaces. `unresolved-pages.md` is the blocker ledger; a row there is not a product claim.

Screenshot links are current-state evidence only. They are not target mockups and must not be treated as approved future-state UI.

## Ongoing Design Coverage Gate

After Spec 323, every UI-relevant feature must update this registry when it introduces or materially changes a reachable page, modal, drawer, form, table, action, or customer-facing state.

The mechanical PR guard is `scripts/check-ui-productization-coverage`. The PR fast-feedback workflow runs it against `origin/dev`: if guarded UI surface paths change under `apps/platform/app/Filament/`, `apps/platform/app/Support/Navigation/`, `apps/platform/app/Providers/Filament/`, `apps/platform/resources/views/`, `apps/platform/app/Livewire/`, or `apps/platform/routes/`, the PR must also update a real UI coverage artifact, or the active spec must contain a checked UI impact decision or a checked `- [x] No UI surface impact` decision with nearby non-empty rationale.

Standalone usage:

```bash
bash scripts/check-ui-productization-coverage HEAD
```

The guard checks committed changes against the supplied base ref and also considers staged, unstaged, and untracked local files where Git can report them. It is a silent-omission guard, not a design-review substitute.

Unchecked template checkboxes, unchecked spec checkboxes, headings, and generic phrases in templates/prompts/docs do not satisfy the guard when guarded UI files changed. Template and prompt changes remain allowed without coverage acknowledgment when no guarded UI file changed.

Guard regression cases can be run with:

```bash
bash scripts/validate-ui-productization-coverage-guard
```

Coverage remains proportional:

- Strategic, customer-facing, dangerous-action-bearing, or materially new surfaces usually need inventory and matrix updates, and may need a screenshot or page report.
- Normal domain pages may reuse an existing page report, domain pattern, or grouped follow-up candidate.
- Small non-material UI changes may use a checked no-impact rationale when rendered behavior and product meaning are unchanged.
- Backend-only, docs-only, tooling-only, and test-only work should declare no UI surface impact in the active spec instead of creating page reports.

Navigation support code and Filament panel/provider files are guarded because they can change reachable UI without touching a page class. If such a path changes only for a non-surface reason, the active spec must explain that no-impact rationale.

Required close-out for new UI surfaces:

- Add or update a row in `route-inventory.md`.
- Assign primary archetype, design depth, and repo-truth level.
- Link to an existing page report, domain pattern, component pattern, or unresolved blocker.
- Add a screenshot when the page is strategic or materially different from an existing pattern.
- Add a page report when the change introduces a new product decision, workflow, dangerous action, or customer-facing experience.
- Update `design-coverage-matrix.md` counts.
- Add unresolved/manual-review entries when the surface cannot be reviewed.

Standard UI/UX Coverage Requirements checklist:

- Workspace, environment, tenant, and provider context are visible where the user can act on scoped data.
- Empty, loading, stale, unknown, partial, failed, and disconnected states are visually distinct from healthy states.
- Dangerous or irreversible actions are identified in the relevant page report and require confirmation, authorization, and audit continuity in the implementation spec.
- Customer-facing and auditor-facing surfaces avoid raw-first data, unsupported compliance claims, and internal-only terminology.
- Tables, filters, forms, drawers, modals, and actions are mapped to an existing domain pattern or a new target pattern.
- Strategic surfaces have a target artifact before implementation changes rely on them.
- Any page that cannot be reviewed is recorded in `unresolved-pages.md` with the blocking reason.

Decision model:

- New strategic page: individual target experience/mockup and follow-up spec.
- Normal domain page: map to a shared domain pattern and grouped follow-up.
- Small admin/utility page: map to design-system cleanup rules.
- Modal/drawer/action/state: map to a component/state pattern or page report section.
- Internal or experimental surface: mark internal/manual-review and avoid customer/product claims.

## Baseline Counts

- UI route/page inventory rows: 98.
- Reviewed/browser-probed pages with reports: 15.
- Desktop screenshots captured: 15 total, including 12 page screenshots and 3 blocker evidence screenshots.
- Strategic surface rows identified: 44.
- Unresolved/manual-review entries: 32.

Tablet and mobile screenshots were intentionally not captured in this pass. Spec 323 permits bounded browser work; responsive screenshots should be added by the later strategic mockup and implementation-wave specs.