# Implementation Plan: Tenantial Enterprise UI Audit Foundation **Branch**: `323-tenantial-enterprise-ui-audit-foundation` **Date**: 2026-05-17 **Spec**: `specs/323-tenantial-enterprise-ui-audit-foundation/spec.md` **Status**: Draft **Runtime posture**: Documentation/browser-audit only. No runtime UI, route, auth, DB, or business-logic changes. ## Summary Create a durable UI/UX audit foundation for Tenantial/TenantPilot by discovering reachable product UI surfaces, capturing feasible screenshots, classifying every discovered page, producing a design coverage matrix, and establishing a living UI Design Registry gate for future UI-relevant specs. The implementation output lives under `docs/ui-ux-enterprise-audit/` plus a minimal brand context placeholder only if `docs/brand/tenantial-brand-context.md` is missing. The follow-up governance output updates the Constitution, Spec Kit templates, implementation prompts, PR template, and PR fast-feedback guard. It must not modify app runtime files. ## Technical Context **Language / Version**: PHP 8.4.15 runtime, but this spec is Markdown/browser-audit work. **Primary Framework**: Laravel 12.52.0. **Admin UI**: Filament 5.2.1. **Reactive Layer**: Livewire 4.1.4. **Database**: PostgreSQL via Sail, not modified. **Testing**: No Pest runtime tests required for Markdown-only output. **Validation Lanes**: Docs/process validation through `git diff --check`; UI/Productization Coverage guard script; browser audit session if screenshots are captured. **Target Platform**: Laravel monolith in `apps/platform`. **Project Type**: Web application. **Performance Goals**: Keep browser audit bounded; document blockers instead of forcing all routes through screenshots. **Constraints**: No application implementation, no migrations, no packages, no env var changes, no queue/scheduler/storage changes, no route/auth changes, no broad full-suite runs. **Scale / Scope**: All relevant reachable UI routes/pages discovered from Laravel route list, Filament pages/resources/clusters/providers, Livewire/views/routes, navigation definitions, and browser pass where feasible. Package posture: - Filament v5 requires Livewire v4.0+; this repo uses Livewire 4.1.4. - Laravel 12 panel providers are registered in `apps/platform/bootstrap/providers.php`; this spec does not add or modify panel providers. - No Filament assets are added. No `filament:assets` deployment change is expected. ## Current Repo Truth Spec 323 builds on the route/shell/context work from Specs 318 through 322. The adjacent repo truth includes: ```text specs/318-admin-surface-scope-shell-context-audit/ specs/319-environment-owned-surface-routing-shell-context-contract/ specs/320-workspace-owned-analysis-surface-registration-shell-cutover/ specs/321-alerts-audit-log-environment-filter-contract-decision/ specs/322-browser-no-drift-regression-guard/ docs/ui/tenantpilot-enterprise-ui-standards.md docs/ui/operator-ux-surface-standards.md docs/product/standards/filament-native-enterprise-ui.md docs/product/spec-candidates.md docs/product/roadmap.md ``` Relevant runtime discovery surfaces for audit only: ```text apps/platform/app/Filament/Pages/ apps/platform/app/Filament/Resources/ apps/platform/app/Filament/Clusters/ apps/platform/app/Livewire/ apps/platform/resources/views/ apps/platform/routes/ apps/platform/app/Providers/Filament/ apps/platform/bootstrap/providers.php ``` Implementation may read these files and run read-only route/browser commands. It must not edit app runtime files. ## Project Structure ### Spec Artifacts ```text specs/323-tenantial-enterprise-ui-audit-foundation/spec.md specs/323-tenantial-enterprise-ui-audit-foundation/plan.md specs/323-tenantial-enterprise-ui-audit-foundation/tasks.md specs/323-tenantial-enterprise-ui-audit-foundation/checklists/requirements.md ``` ### Audit Artifacts To Create During Implementation ```text docs/ui-ux-enterprise-audit/ ├── README.md ├── route-inventory.md ├── design-coverage-matrix.md ├── strategic-surfaces.md ├── grouped-follow-up-candidates.md ├── unresolved-pages.md ├── screenshots/ │ ├── desktop/ │ ├── tablet/ │ └── mobile/ ├── page-reports/ └── templates/ ├── page-audit-template.md ├── route-inventory-template.md └── design-coverage-template.md ``` Conditional artifact: ```text docs/brand/tenantial-brand-context.md ``` Create the conditional artifact only if no brand context exists, and keep it as a minimal placeholder/reference blocker for later mockup specs. ### Process Guardrail Artifacts To Update ```text .specify/memory/constitution.md .specify/templates/spec-template.md .specify/templates/plan-template.md .specify/templates/tasks-template.md .specify/templates/checklist-template.md .codex/prompts/speckit.implement.md .github/agents/speckit.implement.agent.md .gitea/pull_request_template.md .gitea/workflows/test-pr-fast-feedback.yml scripts/check-ui-productization-coverage ``` ## UI / Surface Guardrail Plan - **Guardrail scope**: Documentation-only audit of existing surfaces plus future UI Design Coverage Gate baseline. - **Native vs custom classification summary**: Existing surfaces may be native Filament, custom Blade/Livewire, or mixed; Spec 323 observes and classifies but does not change them. - **Shared-family relevance**: Navigation, shell, page reports, tables, forms, modals, drawers, actions, status states, dangerous actions, evidence/report viewers, customer review surfaces. - **State layers in scope**: route path, query string, shell, page state, modal/drawer/action state when visible, screenshot artifact, inventory classification. - **Audience modes in scope**: operator, customer reviewer, auditor, platform/support user where reachable. - **Decision/diagnostic/raw hierarchy plan**: Page reports must classify default-visible decision content, diagnostic content, and raw/support evidence. - **Raw/support gating plan**: Flag raw IDs, JSON, provider/internal fields, logs, or unsupported compliance claims when default-visible on customer/operator surfaces. - **One-primary-action / duplicate-truth control**: Page reports must flag pages where primary next action is unclear or equal-weight technical/debug actions compete with user workflow. - **Handling modes by drift class or surface**: `individual target mockup required`, `domain-level pattern sufficient`, `design-system cleanup sufficient`, `internal/deprecated`, or `manual review required`. - **Repository-signal treatment**: Any discovered route without classification is a blocker for Spec 323 completion. - **Special surface test profiles**: N/A for runtime tests; browser audit evidence is manual/artifact-based. - **Required tests or manual smoke**: Browser audit/screenshot pass where feasible; `git diff --check`; UI/Productization Coverage guard script. - **Exception path and spread control**: If a page cannot be reached or evaluated, record it in `unresolved-pages.md` with reason. - **Active feature PR close-out entry**: Guardrail / Design Coverage Registry Baseline. ## Shared Pattern & System Fit - **Cross-cutting feature marker**: yes, documentation governance only. - **Systems touched**: Audit docs, screenshots, templates, route inventory, coverage matrix, future feature DoD. - **Shared abstractions reused**: Existing UI standards, Filament v5 rules, Specs 318-322 route/shell context language. - **New abstraction introduced? why?**: No runtime abstraction. The docs-only UI Design Registry is introduced to prevent future unclassified reachable UI debt. - **Why existing structure was insufficient**: Existing standards say how good surfaces should behave, but no master route/page inventory assigns every route a design decision. - **Bounded deviation / spread control**: The registry is maintained as Markdown artifacts and does not become a runtime registry, enum, presenter, or UI framework. ## OperationRun UX Impact - **Touches OperationRun start/completion/link UX?**: no. - **Central contract reused**: N/A. - **Delegated UX behaviors**: N/A. - **Surface-owned behavior kept local**: Existing OperationRun pages may be audited as current-state UI. - **Queued DB-notification policy**: N/A. - **Terminal notification path**: N/A. - **Exception path**: none. ## Provider Boundary & Portability Fit - **Shared provider/platform boundary touched?**: Observation only. - **Provider-owned seams**: Microsoft/Entra/Graph tenant identity and provider connection semantics where already present. - **Platform-core seams**: Workspace, Environment, Managed Environment, route/shell context, product page role. - **Neutral platform terms / contracts preserved**: Workspace, Environment, Managed Environment, Provider Connection, Operation, Evidence, Review. - **Retained provider-specific semantics and why**: Runtime copy is not changed in this spec. Audit reports flag provider-specific terms when they leak into platform-core or customer/operator copy. - **Bounded extraction or follow-up path**: Product language and IA findings are routed to follow-up specs, not fixed here. ## Constitution Check ### Pre-Implementation - **Inventory-first / snapshots-second**: Pass. The spec inventories UI routes/pages only and does not alter inventory/snapshot domain truth. - **Read/write separation**: Pass. The spec is read-only; no product write actions are introduced. - **Graph contract path**: Pass. No Graph calls are introduced. Browser audit must not trigger Graph writes. - **Deterministic capabilities**: Pass. Capability derivation is not changed. - **Workspace/tenant isolation**: Pass. The audit records scope and RBAC notes but does not change authorization. - **RBAC-UX**: Pass. Dangerous actions and customer-facing exposure are audited only. - **OperationRun UX**: N/A. - **Test governance**: Pass with docs-only lane. Browser audit is manual screenshot evidence, not new test family. - **Proportionality**: Pass. Docs-only registry avoids runtime taxonomy/frameworking. - **Shared Pattern First**: Pass. Future pages map to individual mockup, domain pattern, design-system pattern, internal/deprecated, or manual review. - **Filament-native UI**: Pass. Existing Filament surfaces are observed; no custom UI is introduced. - **Spec Candidate Gate**: Pass. Direct manual promotion with 11/12 score and bounded docs-only scope. ### Post-Design No constitutional violation is expected. Implementation must stop and update `spec.md` and `plan.md` before making any runtime UI, route, auth, database, test-suite, or business-logic changes. ## Filament v5 Output Contract - **Livewire v4.0+ compliance**: This repo uses Livewire 4.1.4; Spec 323 changes no Livewire code. - **Provider registration location**: Laravel 12 panel providers remain in `apps/platform/bootstrap/providers.php`; no provider changes. - **Globally searchable resources**: No Resource code changes. The audit may record global-search reachability only; it must not enable or disable global search. - **Destructive/high-impact actions**: No action behavior changes. The audit must flag pages exposing dangerous actions and record whether visible confirmation/authorization/evidence posture appears adequate. - **Asset strategy**: No assets added; no new `filament:assets` deployment step. - **Testing plan**: Markdown/process validation via `git diff --check` and `bash scripts/check-ui-productization-coverage HEAD`; browser audit and screenshots where feasible; no full suite because app runtime behavior is unchanged. ## Test Governance Check - **Test purpose / classification by changed surface**: N/A for runtime; docs/process validation plus manual browser audit. - **Affected validation lanes**: docs validation plus UI/Productization Coverage guard script; optional browser session for screenshots. - **Why this lane mix is the narrowest sufficient proof**: The deliverable is Markdown/screenshot/process guardrail artifacts, not app runtime behavior. - **Narrowest proving command(s)**: `git diff --check`; `bash scripts/check-ui-productization-coverage HEAD`. - **Fixture / helper / factory / seed / context cost risks**: none. Do not add seeders or fixtures for screenshots. - **Expensive defaults or shared helper growth introduced?**: no. - **Heavy-family additions, promotions, or visibility changes**: none. - **Surface-class relief / special coverage rule**: Documentation-only audit; future UI specs use the ongoing coverage gate. - **Closing validation and reviewer handoff**: Reviewer checks route/page counts, screenshot counts, unresolved counts, strategic surfaces, and no runtime file changes. - **Budget / baseline / trend follow-up**: none. - **Review-stop questions**: Any unclassified discovered route, unsupported product truth claim, missing strategic screenshot reason, or runtime file change blocks completion. - **Escalation path**: document-in-feature for unresolved pages; follow-up-spec for strategic mockups/pattern specs. - **Active feature PR close-out entry**: Guardrail / Design Coverage Registry Baseline. - **Why no dedicated follow-up spec is needed for the gate itself**: Spec 323 establishes the baseline; Specs 324-327 are already reserved for mockups, patterns, domain coverage, and implementation. ## Technical Approach ### Phase 1 - Create Audit Structure Create the audit directory tree and required Markdown templates. Add a README that defines audit purpose, non-goals, classification models, how to read reports, the ongoing Design Coverage Gate, and next specs. ### Phase 2 - Discover Routes And Pages Use safe read-only discovery: ```bash cd apps/platform && ./vendor/bin/sail artisan route:list ``` Fallback if Sail is unavailable: ```bash cd apps/platform && php artisan route:list ``` Then inspect Filament pages/resources/clusters/providers, Livewire components, views, routes, and navigation definitions. Build `route-inventory.md` with stable audit IDs (`UI-001`, `UI-002`, ...). ### Phase 3 - Browser Pass And Screenshots Open reachable pages where feasible. Prioritize: 1. strategic likely pages 2. domain hub/list pages 3. customer-facing pages 4. dangerous-action pages 5. onboarding/provider pages 6. dashboard/shell pages Capture desktop screenshots for reachable strategic pages. Capture domain screenshots where practical. Record blockers in `unresolved-pages.md`. ### Phase 4 - Page Reports Create `page-reports/-.md` for every reviewed page using the page audit template. Keep reports concise and consistent rather than over-polished. ### Phase 5 - Coverage Matrix And Strategic Surfaces Summarize totals and coverage by area/archetype/design depth. Populate strategic surfaces with P0/P1/P2 priority and recommended target artifact. ### Phase 6 - Grouped Follow-Up Candidates Create grouped follow-up candidates by domain: - Customer Review Workspace - Decision / Governance Inbox - Operations / Monitoring - Evidence / Audit - Reviews / Review Packs - Drift / Findings - Backup / Restore - Provider / Onboarding - Inventory - Settings / Admin - Support / Diagnostics - Commercial / Entitlements - Auth / Access - Global App Shell / Navigation - Global Tables / Forms / States ### Phase 7 - Ongoing Design Coverage Gate Document how future UI-relevant specs update the registry. Include the standard UI/UX Coverage Requirements checklist and decision model for strategic pages, domain pages, utility pages, modals/drawers/actions, and internal/manual-review surfaces. Also codify the gate outside the audit docs: - add UI/Productization Coverage to the Constitution - add UI Surface Impact and UI/Productization Coverage blocks to the Spec Kit spec template - carry the planning/task/checklist guardrails into the plan, tasks, and checklist templates - add the pre-implementation guardrail to the Codex and GitHub Spec Kit implement prompts - add a PR-template checkbox - add a diff-based PR fast-feedback guard that requires coverage artifacts or a checked `No UI surface impact` decision when guarded UI paths change ### Phase 8 - Validation And Close-Out Run `git diff --check` and `bash scripts/check-ui-productization-coverage HEAD`. Do not run the full suite because app runtime behavior is unchanged. Final report includes created/changed files, route/page count, screenshot count, strategic surface count, unresolved page count, validation commands, no-runtime-code-change note, and full-suite-not-run note. ## Data / Migration / Deployment Impact - **Migrations**: none. - **Models / DB**: none. - **Env vars**: none. - **Queues / scheduler**: none. - **Storage / volumes**: screenshot artifacts are committed Markdown-adjacent files under `docs/`; no runtime storage changes. - **Deployment**: no runtime deployment impact. PR fast-feedback gains a lightweight guard step before the Sail/PHP test lane. - **Filament assets**: no asset registration; no new `filament:assets` requirement. ## Browser Audit Plan Use the in-app browser or a local browser session when feasible. Prefer the Browser plugin for local targets if a dev server URL is known. Use Laravel Boost `get_absolute_url` when sharing a project URL, but final output need not share a runtime URL unless a dev server is started. Screenshots must use stable paths: ```text docs/ui-ux-enterprise-audit/screenshots/desktop/-.png docs/ui-ux-enterprise-audit/screenshots/tablet/-.png docs/ui-ux-enterprise-audit/screenshots/mobile/-.png ``` Do not add seeders or runtime fixtures to make screenshots pretty. If a page needs data/provider/auth state that is unavailable, document the blocker. ## Risks And Controls | Risk | Control | | --- | --- | | Route inventory misses hidden/direct pages | Use route list, file-based discovery, navigation inspection, and browser pass. | | Audit invents future-state product truth | Require repo-truth classification and prohibit conceptual/spec-only claims as implemented. | | Too many pages become individual mockup specs | Use design-depth model; group domain and cleanup pages. | | Screenshot pass becomes too expensive | Require desktop screenshots only for reachable strategic pages; document blockers. | | Future features ignore the registry | Add ongoing Design Coverage Gate and UI/UX Coverage Requirements to README/templates, Spec Kit templates, implement prompts, PR template, and PR fast-feedback guard. | | Runtime changes slip into docs-first work | Final diff review must show only docs/screenshot/spec artifacts; stop on app code changes. | | Brand assets are missing | Create only minimal placeholder/reference blocker; do not invent final assets. | ## Validation Plan Required: ```bash git diff --check bash scripts/check-ui-productization-coverage HEAD ``` Optional/documented: ```text Browser audit only. No runtime code changed. ``` Do not run unless runtime changes are made, which is out of scope: ```text Full suite Broad unrelated test lanes Test expectation updates ``` ## Readiness Gate Spec 323 is ready for implementation when: - `spec.md`, `plan.md`, and `tasks.md` exist. - The scope is docs/browser-audit only. - Required output structure and classification models are explicit. - The ongoing Design Coverage Gate is included. - Validation is bounded to Markdown/screenshot/process guardrail work. - No unresolved preparation issue requires application implementation.