docs: add tenantial enterprise UI audit foundation
Some checks failed
PR Fast Feedback / fast-feedback (pull_request) Failing after 53s
Some checks failed
PR Fast Feedback / fast-feedback (pull_request) Failing after 53s
This commit is contained in:
Ahmed Darrazi
parent
094fff87b6
commit
893af34bad
@ -53,7 +53,21 @@ ## Outline
|
||||
- **IF EXISTS**: Read research.md for technical decisions and constraints
|
||||
- **IF EXISTS**: Read quickstart.md for integration scenarios
|
||||
|
||||
4. **Project Setup Verification**:
|
||||
4. **UI/Productization Coverage Guardrail**:
|
||||
- Before implementing, determine whether this spec adds, removes, renames, or materially changes any reachable UI surface.
|
||||
- A UI surface includes pages, routes, navigation entries, tables, forms, modals, drawers, wizard steps, actions, dangerous-action confirmations, empty/loading/error states, customer-facing views, and operator workflow surfaces.
|
||||
- If UI is affected:
|
||||
- update the UI/UX audit inventory under `docs/ui-ux-enterprise-audit/`
|
||||
- assign page archetype
|
||||
- assign design depth
|
||||
- assign repo-truth level
|
||||
- link to an existing pattern or document the missing pattern/mockup need
|
||||
- review customer-safe and dangerous-action implications where applicable
|
||||
- update the coverage matrix or unresolved/manual-review ledger
|
||||
- If no reachable UI surface is affected, ensure the active spec contains exactly `- [x] No UI surface impact` with a short rationale.
|
||||
- Do not mark the spec complete if a new or changed reachable UI surface remains unclassified.
|
||||
|
||||
5. **Project Setup Verification**:
|
||||
- **REQUIRED**: Create/verify ignore files based on actual project setup:
|
||||
|
||||
**Detection & Creation Logic**:
|
||||
@ -97,27 +111,27 @@ ## Outline
|
||||
- **Terraform**: `.terraform/`, `*.tfstate*`, `*.tfvars`, `.terraform.lock.hcl`
|
||||
- **Kubernetes/k8s**: `*.secret.yaml`, `secrets/`, `.kube/`, `kubeconfig*`, `*.key`, `*.crt`
|
||||
|
||||
5. Parse tasks.md structure and extract:
|
||||
6. Parse tasks.md structure and extract:
|
||||
- **Task phases**: Setup, Tests, Core, Integration, Polish
|
||||
- **Task dependencies**: Sequential vs parallel execution rules
|
||||
- **Task details**: ID, description, file paths, parallel markers [P]
|
||||
- **Execution flow**: Order and dependency requirements
|
||||
|
||||
6. Execute implementation following the task plan:
|
||||
7. Execute implementation following the task plan:
|
||||
- **Phase-by-phase execution**: Complete each phase before moving to the next
|
||||
- **Respect dependencies**: Run sequential tasks in order, parallel tasks [P] can run together
|
||||
- **Follow TDD approach**: Execute test tasks before their corresponding implementation tasks
|
||||
- **File-based coordination**: Tasks affecting the same files must run sequentially
|
||||
- **Validation checkpoints**: Verify each phase completion before proceeding
|
||||
|
||||
7. Implementation execution rules:
|
||||
8. Implementation execution rules:
|
||||
- **Setup first**: Initialize project structure, dependencies, configuration
|
||||
- **Tests before code**: If you need to write tests for contracts, entities, and integration scenarios
|
||||
- **Core development**: Implement models, services, CLI commands, endpoints
|
||||
- **Integration work**: Database connections, middleware, logging, external services
|
||||
- **Polish and validation**: Unit tests, performance optimization, documentation
|
||||
|
||||
8. Progress tracking and error handling:
|
||||
9. Progress tracking and error handling:
|
||||
- Report progress after each completed task
|
||||
- Halt execution if any non-parallel task fails
|
||||
- For parallel tasks [P], continue with successful tasks, report failed ones
|
||||
@ -125,7 +139,7 @@ ## Outline
|
||||
- Suggest next steps if implementation cannot proceed
|
||||
- **IMPORTANT** For completed tasks, make sure to mark the task off as [X] in the tasks file.
|
||||
|
||||
9. Completion validation:
|
||||
10. Completion validation:
|
||||
- Verify all required tasks are completed
|
||||
- Check that implemented features match the original specification
|
||||
- Validate that tests pass and coverage meets requirements
|
||||
|
||||
@ -25,6 +25,7 @@ ## Migration / Config / Ops (falls relevant)
|
||||
## UI (Filament/Livewire) (falls relevant)
|
||||
- [ ] UI-Flows geprüft
|
||||
- [ ] Screenshots/Notizen hinzugefügt
|
||||
- [ ] UI Surface Impact in der Spec dokumentiert: entweder `[x] No UI surface impact` mit Begründung oder UI/Productization Coverage + Audit-Artefakte aktualisiert
|
||||
|
||||
## Notes
|
||||
<!-- Links, Screenshots, Follow-ups, offene Punkte -->
|
||||
<!-- Links, Screenshots, Follow-ups, offene Punkte -->
|
||||
|
||||
@ -21,6 +21,11 @@ jobs:
|
||||
- name: Checkout repository
|
||||
uses: actions/checkout@v4
|
||||
|
||||
- name: Run UI/Productization Coverage guard
|
||||
run: |
|
||||
git fetch origin dev --depth=1
|
||||
bash scripts/check-ui-productization-coverage origin/dev
|
||||
|
||||
- name: Set up PHP
|
||||
uses: shivammathur/setup-php@v2
|
||||
with:
|
||||
|
||||
26
.github/agents/speckit.implement.agent.md
vendored
26
.github/agents/speckit.implement.agent.md
vendored
@ -53,7 +53,21 @@ ## Outline
|
||||
- **IF EXISTS**: Read research.md for technical decisions and constraints
|
||||
- **IF EXISTS**: Read quickstart.md for integration scenarios
|
||||
|
||||
4. **Project Setup Verification**:
|
||||
4. **UI/Productization Coverage Guardrail**:
|
||||
- Before implementing, determine whether this spec adds, removes, renames, or materially changes any reachable UI surface.
|
||||
- A UI surface includes pages, routes, navigation entries, tables, forms, modals, drawers, wizard steps, actions, dangerous-action confirmations, empty/loading/error states, customer-facing views, and operator workflow surfaces.
|
||||
- If UI is affected:
|
||||
- update the UI/UX audit inventory under `docs/ui-ux-enterprise-audit/`
|
||||
- assign page archetype
|
||||
- assign design depth
|
||||
- assign repo-truth level
|
||||
- link to an existing pattern or document the missing pattern/mockup need
|
||||
- review customer-safe and dangerous-action implications where applicable
|
||||
- update the coverage matrix or unresolved/manual-review ledger
|
||||
- If no reachable UI surface is affected, ensure the active spec contains exactly `- [x] No UI surface impact` with a short rationale.
|
||||
- Do not mark the spec complete if a new or changed reachable UI surface remains unclassified.
|
||||
|
||||
5. **Project Setup Verification**:
|
||||
- **REQUIRED**: Create/verify ignore files based on actual project setup:
|
||||
|
||||
**Detection & Creation Logic**:
|
||||
@ -97,27 +111,27 @@ ## Outline
|
||||
- **Terraform**: `.terraform/`, `*.tfstate*`, `*.tfvars`, `.terraform.lock.hcl`
|
||||
- **Kubernetes/k8s**: `*.secret.yaml`, `secrets/`, `.kube/`, `kubeconfig*`, `*.key`, `*.crt`
|
||||
|
||||
5. Parse tasks.md structure and extract:
|
||||
6. Parse tasks.md structure and extract:
|
||||
- **Task phases**: Setup, Tests, Core, Integration, Polish
|
||||
- **Task dependencies**: Sequential vs parallel execution rules
|
||||
- **Task details**: ID, description, file paths, parallel markers [P]
|
||||
- **Execution flow**: Order and dependency requirements
|
||||
|
||||
6. Execute implementation following the task plan:
|
||||
7. Execute implementation following the task plan:
|
||||
- **Phase-by-phase execution**: Complete each phase before moving to the next
|
||||
- **Respect dependencies**: Run sequential tasks in order, parallel tasks [P] can run together
|
||||
- **Follow TDD approach**: Execute test tasks before their corresponding implementation tasks
|
||||
- **File-based coordination**: Tasks affecting the same files must run sequentially
|
||||
- **Validation checkpoints**: Verify each phase completion before proceeding
|
||||
|
||||
7. Implementation execution rules:
|
||||
8. Implementation execution rules:
|
||||
- **Setup first**: Initialize project structure, dependencies, configuration
|
||||
- **Tests before code**: If you need to write tests for contracts, entities, and integration scenarios
|
||||
- **Core development**: Implement models, services, CLI commands, endpoints
|
||||
- **Integration work**: Database connections, middleware, logging, external services
|
||||
- **Polish and validation**: Unit tests, performance optimization, documentation
|
||||
|
||||
8. Progress tracking and error handling:
|
||||
9. Progress tracking and error handling:
|
||||
- Report progress after each completed task
|
||||
- Halt execution if any non-parallel task fails
|
||||
- For parallel tasks [P], continue with successful tasks, report failed ones
|
||||
@ -125,7 +139,7 @@ ## Outline
|
||||
- Suggest next steps if implementation cannot proceed
|
||||
- **IMPORTANT** For completed tasks, make sure to mark the task off as [X] in the tasks file.
|
||||
|
||||
9. Completion validation:
|
||||
10. Completion validation:
|
||||
- Verify all required tasks are completed
|
||||
- Check that implemented features match the original specification
|
||||
- Validate that tests pass and coverage meets requirements
|
||||
|
||||
@ -1,35 +1,35 @@
|
||||
<!--
|
||||
Sync Impact Report
|
||||
|
||||
- Version change: 2.12.0 -> 2.13.0
|
||||
- Version change: 2.13.0 -> 2.14.0
|
||||
- Modified principles:
|
||||
- Expanded Filament Native First / No Ad-hoc Styling (UI-FIL-001)
|
||||
so custom Filament UI must follow the canonical TenantPilot
|
||||
enterprise UI standard, must not introduce ad-hoc styling for
|
||||
cards, buttons, hovers, badges, icons, progress bars, empty states,
|
||||
or interactive rows, and may only show interactive affordance when
|
||||
a repo-real route/action and permitted capability exist
|
||||
- Added sections: None
|
||||
- Added UI/Productization Coverage (UI-COV-001) so every reachable
|
||||
product surface needs an explicit productization and design coverage
|
||||
decision before a feature can be considered complete
|
||||
- Expanded governance expectations so specs/PRs that change reachable
|
||||
UI must update the UI audit registry or document a checked no-impact
|
||||
decision
|
||||
- Added sections:
|
||||
- UI/Productization Coverage (UI-COV-001)
|
||||
- Removed sections: None
|
||||
- Templates requiring updates:
|
||||
- .specify/templates/spec-template.md: require canonical UI-standard
|
||||
compliance, no ad-hoc custom styling, and repo-real affordance
|
||||
disclosure ✅
|
||||
- .specify/templates/plan-template.md: add UI-FIL-001 checks for the
|
||||
canonical UI standard and affordance honesty ✅
|
||||
- .specify/templates/tasks-template.md: add implementation tasks for
|
||||
no ad-hoc styling and repo-real interactive affordances ✅
|
||||
- .specify/templates/checklist-template.md: add explicit custom UI
|
||||
standard and affordance review check ✅
|
||||
- docs/product/principles.md: align the high-level product rule with
|
||||
the canonical UI standard ✅
|
||||
- docs/product/standards/filament-native-enterprise-ui.md: align the
|
||||
compact standard with the canonical UI source ✅
|
||||
- docs/product/standards/README.md: index the canonical UI-standard
|
||||
document ✅
|
||||
- docs/HANDOVER.md: refresh the Filament standards summary ✅
|
||||
- docs/ui/tenantpilot-enterprise-ui-standards.md: fix the
|
||||
constitution-reference path to the canonical file ✅
|
||||
- .specify/templates/spec-template.md: add mandatory UI Surface Impact
|
||||
and UI/Productization Coverage blocks ✅
|
||||
- .specify/templates/plan-template.md: add UI coverage guardrail
|
||||
planning fields and constitution check item ✅
|
||||
- .specify/templates/tasks-template.md: add pre-implementation UI
|
||||
coverage decision and artifact-update tasks ✅
|
||||
- .specify/templates/checklist-template.md: add UI coverage review
|
||||
checks ✅
|
||||
- .codex/prompts/speckit.implement.md: add implementation-loop UI
|
||||
coverage guardrail ✅
|
||||
- .github/agents/speckit.implement.agent.md: add implementation-loop
|
||||
UI coverage guardrail ✅
|
||||
- .gitea/pull_request_template.md: add UI coverage close-out checkbox ✅
|
||||
- CI/script updates:
|
||||
- scripts/check-ui-productization-coverage: new diff guard for UI
|
||||
surface changes ✅
|
||||
- .gitea/workflows/test-pr-fast-feedback.yml: run the guard on PRs ✅
|
||||
- Commands checked:
|
||||
- N/A `.specify/templates/commands/*.md` directory is not present
|
||||
- Follow-up TODOs: None
|
||||
@ -95,6 +95,15 @@ ### UI Semantics Must Not Become Their Own Framework (UI-SEM-001)
|
||||
- Direct mapping from canonical domain truth to UI is preferred over intermediate semantic superstructures.
|
||||
- Presentation helpers SHOULD remain optional adapters, not mandatory architecture.
|
||||
|
||||
### UI/Productization Coverage (UI-COV-001)
|
||||
- Every reachable product surface MUST have an explicit productization and design coverage decision.
|
||||
- A feature is not complete if it introduces, removes, renames, or materially changes a reachable UI surface without classifying that surface by page archetype, design depth, repo-truth level, target pattern or mockup need, customer/operator safety where applicable, and dangerous-action handling where applicable.
|
||||
- A UI surface includes pages, routes, navigation entries, tables, forms, modals, drawers, wizard steps, actions, dangerous-action confirmations, empty/loading/error states, customer-facing views, and operator workflow surfaces.
|
||||
- No reachable page may remain unclassified, undesigned, or without a recommended target state.
|
||||
- The durable coverage registry lives under `docs/ui-ux-enterprise-audit/`. Future UI-relevant specs MUST update the registry artifacts or document an explicit checked no-impact decision in the active spec.
|
||||
- `No UI surface impact` is valid only when the feature does not add, remove, rename, or materially change any reachable UI surface, or when a guarded file path changed for non-surface reasons and the active spec explains that rationale.
|
||||
- Reviews and CI SHOULD block PRs that change UI surface files without either coverage artifact updates or an explicit checked no-impact decision.
|
||||
|
||||
### Shared Pattern First For Cross-Cutting Interaction Classes (XCUT-001)
|
||||
- Cross-cutting interaction classes such as notifications, status messaging, action links, header actions, dashboard signals/cards, navigation entry points, alerts, evidence/report viewers, and similar operator-facing infrastructure MUST first attach to an existing shared contract, presenter, builder, renderer, or other shared path when one already exists.
|
||||
- New local or domain-specific implementations for an existing interaction class are allowed only when the current shared path is demonstrably insufficient for current-release truth.
|
||||
@ -1856,6 +1865,11 @@ ### Scope, Compliance, and Review Expectations
|
||||
- Specs and PRs that change operator-facing surfaces MUST classify each
|
||||
affected surface under DECIDE-001 and justify any new Primary
|
||||
Decision Surface or workflow-first navigation change.
|
||||
- Specs and PRs that add, remove, rename, or materially change reachable
|
||||
UI surfaces MUST complete the UI Surface Impact decision, update
|
||||
`docs/ui-ux-enterprise-audit/` coverage artifacts where needed, or
|
||||
carry an explicit checked `No UI surface impact` decision with
|
||||
rationale.
|
||||
- Reviews MUST reject runtime or test changes when lane classification is missing, fast-lane work quietly absorbs heavy cost, expensive defaults are introduced silently, or material CI/runtime drift is left undocumented.
|
||||
- Review and approval MUST favor simplification, replacement, and absorption over additive semantic layering.
|
||||
- Future-release preparation alone is not sufficient justification for new persistence or frameworkization unless security, tenant isolation, auditability, compliance evidence, or queue correctness already require it.
|
||||
@ -1870,4 +1884,4 @@ ### Versioning Policy (SemVer)
|
||||
- **MINOR**: new principle/section or materially expanded guidance.
|
||||
- **MAJOR**: removing/redefining principles in a backward-incompatible way.
|
||||
|
||||
**Version**: 2.13.0 | **Ratified**: 2026-01-03 | **Last Amended**: 2026-05-03
|
||||
**Version**: 2.14.0 | **Ratified**: 2026-01-03 | **Last Amended**: 2026-05-17
|
||||
|
||||
@ -18,6 +18,9 @@ ## Applicability And Low-Impact Gate
|
||||
|
||||
- [ ] CHK001 The change explicitly says whether an operator-facing surface or guardrail workflow surface is affected; low-impact `N/A` handling is used once and not contradicted elsewhere.
|
||||
- [ ] CHK002 The spec, plan, and task artifacts carry forward the same native/custom classification, shared-family relevance, state-layer ownership, and exception need without inventing second wording.
|
||||
- [ ] CHK029 The spec includes exactly one coherent UI Surface Impact decision: either checked `No UI surface impact` with rationale, or one or more concrete UI impact boxes with completed UI/Productization Coverage.
|
||||
- [ ] CHK030 If reachable UI changed, the review confirms page archetype, design depth, repo-truth level, target pattern/mockup need, customer-safe review need, and dangerous-action review need are recorded.
|
||||
- [ ] CHK031 If reachable UI changed, `docs/ui-ux-enterprise-audit/route-inventory.md` and `docs/ui-ux-enterprise-audit/design-coverage-matrix.md` are updated, or `unresolved-pages.md` records why review is blocked.
|
||||
|
||||
## Native, Shared-Family, And State Ownership
|
||||
|
||||
|
||||
@ -46,6 +46,9 @@ ## UI / Surface Guardrail Plan
|
||||
- **Required tests or manual smoke**: [functional-core / state-contract / exception-fallback / manual-smoke / N/A]
|
||||
- **Exception path and spread control**: [none / describe the named exception boundary]
|
||||
- **Active feature PR close-out entry**: [Guardrail / Exception / Smoke Coverage / N/A]
|
||||
- **UI/Productization coverage decision**: [No UI surface impact / coverage artifacts updated / unresolved manual-review entry / N/A]
|
||||
- **Coverage artifacts to update**: [`route-inventory.md` / `design-coverage-matrix.md` / `page-reports/...` / `grouped-follow-up-candidates.md` / `unresolved-pages.md` / none]
|
||||
- **No-impact rationale**: [Required when `No UI surface impact` is checked in the spec]
|
||||
|
||||
## Shared Pattern & System Fit
|
||||
|
||||
@ -172,6 +175,12 @@ ## Constitution Check
|
||||
exception path, and the active feature PR close-out entry stay
|
||||
explicit without duplicating the same decision across spec, plan,
|
||||
tasks, checklist, and close-out surfaces
|
||||
- UI/Productization coverage (UI-COV-001): every spec completes the UI
|
||||
Surface Impact decision; changed reachable UI surfaces update
|
||||
`docs/ui-ux-enterprise-audit/` coverage artifacts with page archetype,
|
||||
design depth, repo-truth level, target pattern/mockup need,
|
||||
customer-safe review need, and dangerous-action review need; a checked
|
||||
`No UI surface impact` decision is used only with a short rationale
|
||||
|
||||
## Test Governance Check
|
||||
|
||||
|
||||
@ -35,6 +35,41 @@ ## Spec Scope Fields *(mandatory)*
|
||||
- **Default filter behavior when tenant-context is active**: [e.g., prefilter to current tenant]
|
||||
- **Explicit entitlement checks preventing cross-tenant leakage**: [Describe checks]
|
||||
|
||||
## UI Surface Impact *(mandatory — UI-COV-001)*
|
||||
|
||||
Does this spec add, remove, rename, or materially change any reachable UI surface?
|
||||
|
||||
- [ ] No UI surface impact
|
||||
- [ ] Existing page changed
|
||||
- [ ] New page/route added
|
||||
- [ ] New modal/drawer/action added
|
||||
- [ ] New table/form/state added
|
||||
- [ ] Customer-facing surface changed
|
||||
- [ ] Dangerous action changed
|
||||
|
||||
If any box except "No UI surface impact" is checked, complete the UI/Productization Coverage section below. "No UI surface impact" MUST NOT be checked together with another impact box; if a guarded file path changes for non-surface reasons, keep only "No UI surface impact" checked and explain the rationale below.
|
||||
|
||||
## UI/Productization Coverage *(mandatory when UI Surface Impact is not "No UI surface impact"; otherwise write `N/A - no reachable UI surface impact` plus rationale)*
|
||||
|
||||
- **Route/page/surface**: [route, page class, modal/drawer/action/table/form/state]
|
||||
- **Current or new page archetype**: [existing archetype from `docs/ui-ux-enterprise-audit/route-inventory.md` or proposed new archetype]
|
||||
- **Design depth**: [Strategic Surface / Domain Pattern Surface / Design-System Cleanup Surface / Internal/Hidden / Manual Review Required]
|
||||
- **Repo-truth level**: [repo-verified / plausible-existing / foundation-only / spec-only / conceptual-future-state / unknown]
|
||||
- **Existing pattern reused**: [page report, domain pattern, component pattern, or `none`]
|
||||
- **New pattern required**: [none / target mockup / domain pattern / component-state pattern / manual review]
|
||||
- **Screenshot required**: [yes/no + path or rationale]
|
||||
- **Page audit required**: [yes/no + path or rationale]
|
||||
- **Customer-safe review required**: [yes/no + rationale]
|
||||
- **Dangerous-action review required**: [yes/no + confirmation/authorization/audit implications]
|
||||
- **Coverage files updated or explicitly not needed**:
|
||||
- [ ] `docs/ui-ux-enterprise-audit/route-inventory.md`
|
||||
- [ ] `docs/ui-ux-enterprise-audit/design-coverage-matrix.md`
|
||||
- [ ] `docs/ui-ux-enterprise-audit/page-reports/...`
|
||||
- [ ] `docs/ui-ux-enterprise-audit/grouped-follow-up-candidates.md`
|
||||
- [ ] `docs/ui-ux-enterprise-audit/unresolved-pages.md`
|
||||
- [ ] `N/A - no reachable UI surface impact`
|
||||
- **No-impact rationale when applicable**: [Required when `No UI surface impact` is checked]
|
||||
|
||||
## Cross-Cutting / Shared Pattern Reuse *(mandatory when the feature touches notifications, status messaging, action links, header actions, dashboard signals/cards, alerts, navigation entry points, evidence/report viewers, or any other existing shared operator interaction family; otherwise write `N/A - no shared interaction family touched`)*
|
||||
|
||||
- **Cross-cutting feature?**: [yes/no]
|
||||
@ -265,6 +300,17 @@ ## Requirements *(mandatory)*
|
||||
- record any allowed deviation, the consistency it must preserve, and its ownership/spread-control cost,
|
||||
- and make the reviewer focus explicit so parallel local UX paths do not appear silently.
|
||||
|
||||
**Constitution alignment (UI-COV-001):** Every spec MUST complete the UI Surface Impact block. If the feature adds, removes, renames, or materially changes any reachable UI surface, the spec MUST also complete UI/Productization Coverage and state:
|
||||
- the affected route/page/surface,
|
||||
- page archetype,
|
||||
- design depth,
|
||||
- repo-truth level,
|
||||
- target pattern or mockup need,
|
||||
- customer/operator safety review need,
|
||||
- dangerous-action review need,
|
||||
- and which `docs/ui-ux-enterprise-audit/` artifacts were updated or why the surface is unresolved/manual review.
|
||||
If there is no reachable UI impact, the spec MUST check exactly `No UI surface impact` and provide a short rationale.
|
||||
|
||||
**Constitution alignment (DECIDE-AUD-001 / OPSURF-001):** If this feature changes a detail or status surface, the spec MUST describe:
|
||||
- how the surface separates customer-readable decision content, operator diagnostics, and support/raw evidence,
|
||||
- which audience modes are in scope (`customer/read-only`, `operator/MSP`, `support/platform`),
|
||||
|
||||
@ -62,6 +62,13 @@ # Tasks: [FEATURE NAME]
|
||||
- implementing bounded normalization or extraction where a current hotspot is too provider-shaped, rather than introducing speculative multi-provider frameworks,
|
||||
- and recording `document-in-feature` or `follow-up-spec` when a bounded provider-specific hotspot remains.
|
||||
**UI / Surface Guardrails**: If this feature adds or changes operator-facing surfaces or the workflow that governs them, tasks MUST include:
|
||||
- determining before implementation whether the spec adds, removes, renames, or materially changes any reachable UI surface,
|
||||
- checking exactly `No UI surface impact` in the spec with a short rationale when no reachable UI surface is affected,
|
||||
- updating `docs/ui-ux-enterprise-audit/route-inventory.md` and `docs/ui-ux-enterprise-audit/design-coverage-matrix.md` when reachable UI is added or materially changed,
|
||||
- assigning page archetype, design depth, repo-truth level, target pattern/mockup need, customer-safe review need, and dangerous-action review need for each affected surface,
|
||||
- linking the affected surface to an existing page report, domain pattern, component pattern, new page report, unresolved/manual-review entry, or grouped follow-up candidate,
|
||||
- adding screenshot/page-audit tasks when the new or changed surface is strategic, customer-facing, dangerous-action-bearing, or materially different from an existing pattern,
|
||||
- ensuring no new or changed reachable UI surface remains unclassified before the feature is marked complete,
|
||||
- carrying forward the spec's native/custom classification, shared-family relevance, state-layer ownership, and exception need into implementation work without renaming the same decision,
|
||||
- classifying any triggered repository signals with one handling mode (`hard-stop-candidate`, `review-mandatory`, `exception-required`, or `report-only`),
|
||||
- adding explicit review or definition-of-done work when a guarded surface class, repository signal, or exception path is involved,
|
||||
|
||||
7
docs/brand/tenantial-brand-context.md
Normal file
7
docs/brand/tenantial-brand-context.md
Normal file
@ -0,0 +1,7 @@
|
||||
# Tenantial Brand Context
|
||||
|
||||
Official Tenantial brand assets and target mockup direction are not present in this repository as of Spec 323.
|
||||
|
||||
Later mockup specs should add or reference approved brand material before producing high-fidelity target visuals. Until then, product audit language should use the existing Tenantial/TenantPilot enterprise UX lens: calm, precise, premium, operator-first, evidence-first, workspace-aware, controlled, and customer-safe.
|
||||
|
||||
Do not infer final colors, typography, logo usage, illustration style, or marketing copy from this placeholder.
|
||||
89
docs/ui-ux-enterprise-audit/README.md
Normal file
89
docs/ui-ux-enterprise-audit/README.md
Normal file
@ -0,0 +1,89 @@
|
||||
# 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.
|
||||
|
||||
## 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 UI coverage artifact or the active spec must contain a checked `- [x] No UI surface impact` decision.
|
||||
|
||||
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.
|
||||
93
docs/ui-ux-enterprise-audit/design-coverage-matrix.md
Normal file
93
docs/ui-ux-enterprise-audit/design-coverage-matrix.md
Normal file
@ -0,0 +1,93 @@
|
||||
# Design Coverage Matrix
|
||||
|
||||
Source of truth: `route-inventory.md` as of Spec 323. Counts are inventory rows unless explicitly marked as unique files or unique reports.
|
||||
|
||||
## Summary
|
||||
|
||||
| Metric | Count | Notes |
|
||||
| --- | ---: | --- |
|
||||
| UI route/page inventory rows | 98 | Includes dynamic route families and utility/auth endpoints. |
|
||||
| Unique page reports | 15 | `page-reports/*.md`; two inventory rows share existing reports where routes resolve to the same surface. |
|
||||
| Desktop screenshots | 15 | 12 rendered product pages and 3 blocker evidence screenshots. |
|
||||
| Tablet screenshots | 0 | Deferred to later strategic mockup/implementation specs. |
|
||||
| Mobile screenshots | 0 | Deferred to later strategic mockup/implementation specs. |
|
||||
| Strategic Surface rows | 44 | Individual target treatment or explicit product decision required. |
|
||||
| Domain Pattern Surface rows | 45 | Can be handled through grouped pattern specs unless later evidence raises risk. |
|
||||
| Design-System Cleanup Surface rows | 7 | Tables/forms/states/copy cleanup, no individual target mockup expected by default. |
|
||||
| Internal / Deprecated / Hidden rows | 1 | Local-only smoke login routes. |
|
||||
| Manual Review Required rows | 1 | File-discovered break-glass page without confirmed route. |
|
||||
| High-priority unresolved/manual-review entries | 32 | Recorded in `unresolved-pages.md`. |
|
||||
|
||||
## Coverage By Area
|
||||
|
||||
| Area | Rows | Coverage Notes |
|
||||
| --- | ---: | --- |
|
||||
| Platform/system | 14 | Route-discovered; not browser-reviewed in Spec 323 because system auth/capability state needs separate fixture. |
|
||||
| Governance | 12 | Strong browser coverage for inbox, decisions, exceptions, baselines; detail/diff routes remain unresolved. |
|
||||
| Monitoring | 9 | Operations hub and alert delivery landing captured; record details and config forms remain pattern/manual review. |
|
||||
| Inventory | 8 | Route-discovered only; coverage, policy version detail, and raw-data exposure need later review. |
|
||||
| Evidence / audit | 8 | Audit log captured; evidence/report detail routes need customer-safe progressive-disclosure review. |
|
||||
| Reviews | 6 | Review register and customer workspace captured; review pack/detail routes remain unresolved. |
|
||||
| Backup / restore | 6 | High-risk area; backup sets and restore runs were blocked by fixture capability. |
|
||||
| Settings / admin | 5 | Workspace and environment access are RBAC-sensitive and need later review. |
|
||||
| Provider / integration | 5 | Provider connections captured; create/edit/onboarding remain high-risk unresolved surfaces. |
|
||||
| Findings | 5 | Queue/inbox patterns captured; finding detail needs individual triage target. |
|
||||
| Auth/access | 4 | Mostly flow/guard surfaces; copy and denial states should be pattern-reviewed. |
|
||||
| App shell | 4 | Workspace overview captured; chooser/context routes need domain pattern pass. |
|
||||
| Workspace / environment | 2 | Environment dashboard captured; managed-environments landing remains unresolved. |
|
||||
| Utility | 2 | Non-product endpoints; design-system cleanup only. |
|
||||
| Support | 2 | Diagnostics/support surfaces should stay secondary to operator workflows. |
|
||||
| Provider / onboarding | 2 | Wizard and draft states require later target treatment. |
|
||||
| Directory | 2 | Provider-bound directory cache pages; likely pattern covered. |
|
||||
| Public | 1 | Welcome route; not a product admin surface. |
|
||||
| Customer review | 1 | Captured; highest customer-safe language priority. |
|
||||
|
||||
## Coverage By Primary Archetype
|
||||
|
||||
| Primary Archetype | Rows | Design Implication |
|
||||
| --- | ---: | --- |
|
||||
| Settings / Admin | 13 | RBAC, entitlement, lifecycle, and dangerous setting changes need confirmation and authorization review. |
|
||||
| Evidence / Audit | 10 | Must keep proof, timestamps, source, and raw details clearly separated. |
|
||||
| Operations / Monitoring | 9 | Needs consistent run status, retry/rerun semantics, and diagnostic hierarchy. |
|
||||
| Inventory | 8 | Needs raw provider payload disclosure rules and confidence/status language. |
|
||||
| Drift / Diff | 8 | Needs assignment, comparison, snapshot, and evidence-gap hierarchy. |
|
||||
| Provider / Integration | 7 | Consent, credentials, permissions, and disconnect states require high trust clarity. |
|
||||
| Reviews | 6 | Customer/auditor language, export context, and proof links are central. |
|
||||
| Findings / Inbox | 6 | Needs triage, owner, SLA, exception, and close-state clarity. |
|
||||
| Backup / Restore | 6 | Highest safety burden: dry-run, confirmation, audit, and restore-point truth. |
|
||||
| Auth / Access | 6 | Guard, denial, external auth, and smoke/local flows should stay explicit. |
|
||||
| Support / Diagnostics | 5 | Should not compete with product decision surfaces. |
|
||||
| Overview / Dashboard | 4 | Must prioritize one or two decision paths over raw status. |
|
||||
| Exceptions / Accepted Risk | 4 | Needs accepted-risk language, expiration, approver, and audit continuity. |
|
||||
| Workspace / Tenant Context | 3 | Context must be visible and unambiguous before scoped actions. |
|
||||
| Utility / Internal | 2 | Keep hidden/internal unless deliberately productized. |
|
||||
| Customer Workspace | 1 | Requires customer-safe first-read treatment. |
|
||||
|
||||
## Coverage By Design Depth
|
||||
|
||||
| Design Depth | Rows | Gate Treatment |
|
||||
| --- | ---: | --- |
|
||||
| Strategic Surface | 44 | Requires individual target artifact or explicit product decision before substantive UI implementation. |
|
||||
| Domain Pattern Surface | 45 | Can be handled by grouped pattern specs and shared components. |
|
||||
| Design-System Cleanup Surface | 7 | Table/form/action/state cleanup can be folded into implementation waves. |
|
||||
| Manual Review Required | 1 | Must not be treated as product-ready until route/auth state is confirmed. |
|
||||
| Internal / Deprecated / Hidden | 1 | Local-only/testing; keep out of customer-facing design claims. |
|
||||
|
||||
## Missing Or Unclear Coverage
|
||||
|
||||
The largest open gaps are strategic detail/workflow surfaces, system-plane routes, and high-risk restore/backup flows that need seeded capability states. `unresolved-pages.md` records 32 high-priority entries.
|
||||
|
||||
Tablet and mobile coverage is intentionally absent from this baseline. Later target specs should add responsive evidence for the app shell, workspace overview, environment dashboard, customer review workspace, governance inbox, operations, evidence, backup/restore, and critical forms.
|
||||
|
||||
## Recommended Next Specs
|
||||
|
||||
1. P0 enterprise shell and workspace/environment decision hierarchy: app shell, workspace overview, environment dashboard, navigation/context.
|
||||
2. P0 governance and customer review workspace: governance inbox, decision register, exceptions queue, customer review workspace, review register.
|
||||
3. P0 backup/restore and evidence safety: backup sets, restore runs, backup schedules, review packs, audit/evidence exports.
|
||||
4. P1 provider/onboarding and access: provider connections, consent/onboarding, environment access scopes, workspace administration.
|
||||
5. P1 drift/diff and inventory: baseline compare, baseline matrix, policy version detail, inventory coverage.
|
||||
6. P2 system-plane controls: system dashboard, operational controls, system operation detail, access logs, repair workspace owners.
|
||||
|
||||
## Update Rule
|
||||
|
||||
Future feature work must update this matrix whenever `route-inventory.md` changes. Add the new row count, adjust area/archetype/depth totals, link any screenshots or reports, and add unresolved entries when browser review is blocked.
|
||||
21
docs/ui-ux-enterprise-audit/grouped-follow-up-candidates.md
Normal file
21
docs/ui-ux-enterprise-audit/grouped-follow-up-candidates.md
Normal file
@ -0,0 +1,21 @@
|
||||
# Grouped Follow-Up Candidates
|
||||
|
||||
Spec 323 intentionally avoids one follow-up spec per small page. These groups define the next practical design lanes.
|
||||
|
||||
| Group | Covered Pages | Shared Problem | Recommended Later Spec Type | Individual Mockup Need | Domain-Pattern Sufficiency | Priority |
|
||||
| --- | --- | --- | --- | --- | --- | --- |
|
||||
| App shell / navigation | UI-001, UI-002, UI-003, UI-004, UI-010, UI-011 | Workspace/environment context and primary next-action hierarchy. | Strategic target spec. | Yes for overview/dashboard; no for choosers if pattern-covered. | Shell/context pattern for chooser states. | P0 |
|
||||
| Customer review workspace | UI-037, UI-038, UI-039, UI-040, UI-041, UI-042, UI-043 | Customer-safe review planning, proof, pack/export context, and auditor language. | Strategic customer-review spec. | Yes for UI-038 and review-pack/detail. | Review list tables can use pattern coverage. | P0 |
|
||||
| Governance inbox | UI-026, UI-028, UI-029, UI-035, UI-036, UI-057, UI-058, UI-061, UI-076 | Decision, accepted-risk, drift, and compare surfaces need common evidence grammar. | Strategic governance spec. | Yes for inbox, decisions, exception detail, compare. | Baseline lists/forms can use domain patterns. | P0 |
|
||||
| Operations | UI-016, UI-017, UI-018, UI-019, UI-020, UI-021, UI-022, UI-023, UI-024 | Operation and alert states need consistent severity, retry, and diagnostic hierarchy. | Domain pattern plus strategic operation detail. | Yes for operation hub/detail. | Alert resources can use table/form/action pattern. | P1 |
|
||||
| Evidence | UI-025, UI-044, UI-045, UI-046, UI-047, UI-048, UI-059, UI-060 | Evidence, raw payloads, timestamps, provenance, and export context need progressive disclosure. | Evidence/audit pattern spec. | Yes for evidence overview and stored report detail. | Snapshot/report lists can share pattern. | P1 |
|
||||
| Reviews | UI-037, UI-039, UI-040, UI-041, UI-042, UI-043 | Review planning, progress, evidence packs, and downloads must read as trustworthy artifacts. | Review workflow spec. | Yes for workspace and detail/export pages. | List/create forms can share review pattern. | P1 |
|
||||
| Drift / findings | UI-030, UI-031, UI-032, UI-033, UI-034, UI-055, UI-056, UI-057, UI-058, UI-061, UI-063, UI-069, UI-076 | Triage, diff, baseline, assignment, and confidence states need unified status language. | Strategic drift/findings spec. | Yes for finding detail, baseline compare, policy version detail. | Findings list/intake/hygiene can share patterns. | P0 |
|
||||
| Backup / restore | UI-049, UI-050, UI-051, UI-052, UI-053, UI-054 | Backup truth, restore safety, dry-run, confirmation, partial restore, and audit continuity. | Strategic safety workflow spec. | Yes for backup sets and restore create/view. | Schedule list/form can share backup pattern. | P0 |
|
||||
| Provider / onboarding | UI-014, UI-015, UI-072, UI-073, UI-074, UI-077, UI-078 | Consent, scopes, provider health, required permissions, and disconnected states need trust copy. | Provider onboarding/integration spec. | Yes for provider connections and create flow. | Required permissions and callback flows can be pattern-covered. | P1 |
|
||||
| Inventory | UI-062, UI-063, UI-064, UI-065, UI-066, UI-067, UI-068, UI-069, UI-070, UI-071 | Raw provider inventory, policy versions, and coverage confidence need clear provenance and disclosure. | Inventory pattern spec. | Yes for inventory coverage and policy version detail. | Standard inventory lists/details can share pattern. | P1 |
|
||||
| Settings / admin | UI-007, UI-008, UI-009, UI-013, UI-021, UI-022, UI-023, UI-024, UI-050, UI-075, UI-087, UI-088, UI-089, UI-090 | Workspace, alert, backup, and platform settings need RBAC-aware copy and action safety. | Admin/settings pattern spec. | Yes for workspace management and environment access scopes. | Create/edit forms can share settings pattern. | P1 |
|
||||
| Support / diagnostics | UI-012, UI-077, UI-080, UI-091, UI-092, UI-093, UI-096, UI-097 | Diagnostics and repair tools should support operators without becoming primary customer surfaces. | Support/diagnostics pattern spec. | Yes for break-glass/repair controls. | Runbook/failure/stuck pages can share pattern. | P2 |
|
||||
| Commercial / entitlements | UI-008, UI-075 | Plan, ownership, entitlement, and lifecycle language need calm precision. | Commercial/admin copy pattern. | No standalone mockup unless monetization flows expand. | Pattern coverage likely sufficient. | P2 |
|
||||
| Auth / access | UI-005, UI-006, UI-013, UI-078, UI-079, UI-083, UI-086, UI-097 | Login, denial, external auth, delegated RBAC, and break-glass states must be explicit and safe. | Auth/access state pattern. | Yes only for access scopes and repair owners. | Login/denial/callback flows can share state pattern. | P1 |
|
||||
| Global tables / forms / states | Cross-cutting all list/create/edit/detail resources | Empty, loading, stale, unknown, failed, disconnected, partial, and unauthorized states need one shared grammar. | Design-system cleanup spec. | No per-page mockups by default. | Shared pattern sufficient unless a page is strategic. | P0 |
|
||||
@ -0,0 +1,48 @@
|
||||
# UI-001 Workspace Overview
|
||||
|
||||
| Field | Value |
|
||||
| --- | --- |
|
||||
| Route | `/admin` -> `/admin/workspaces/{workspace}/overview` |
|
||||
| Source | `WorkspaceOverview`, `WorkspaceOverviewBuilder`, `WorkspaceHubRegistry` |
|
||||
| Area / scope | App shell / workspace |
|
||||
| Archetype | Overview / Dashboard |
|
||||
| Design depth | Strategic Surface |
|
||||
| Repo truth | repo-verified |
|
||||
| Screenshot | `../screenshots/desktop/ui-001-workspace-overview.png` |
|
||||
| Browser status | Reached through local smoke login; redirected to workspace route. |
|
||||
|
||||
## First Five Seconds
|
||||
|
||||
The page clearly communicates a workspace home with operational and governance attention cards. The strongest next action is not always singular because several cards and links compete: choose environment, operations, alerts, backup attention, recovery attention, and findings links.
|
||||
|
||||
## Productization Review
|
||||
|
||||
- Decision-first: strong, with attention cards ahead of diagnostics.
|
||||
- Evidence-first: partially present through counts and posture explanations.
|
||||
- Context: workspace shell is explicit and no environment is selected.
|
||||
- Customer/auditor safety: not customer-facing, but copy is calm and mostly productized.
|
||||
- Diagnostics: recent operations are correctly framed as diagnostic rather than governance health.
|
||||
|
||||
## Information Inventory
|
||||
|
||||
Default-visible content includes workspace identity, environment count, governance attention, backup/recovery attention, active operations, alert failures, assigned work, and hygiene state. Status/trust signals distinguish calm, affected environments, and diagnostic activity. Empty states are mostly honest.
|
||||
|
||||
## Dangerous Actions
|
||||
|
||||
No destructive action was visible on the first viewport. Main risk is false affordance or multiple equal-weight primary links, not immediate mutation.
|
||||
|
||||
## Scores
|
||||
|
||||
| IA | Density | User Clarity | Sellability | Disclosure | Hierarchy | DS Fit | A11y | Responsive | Components | UX Writing | Perf |
|
||||
| ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: |
|
||||
| 4 | 4 | 4 | 4 | 4 | 3 | 4 | 3 | 3 | 4 | 4 | 4 |
|
||||
|
||||
## Top Issues
|
||||
|
||||
1. Several high-value links compete for primary action hierarchy.
|
||||
2. Backup/recovery counts need a target mockup that separates posture, evidence, and next action.
|
||||
3. Responsive behavior was not captured in Spec 323.
|
||||
|
||||
## Target Direction
|
||||
|
||||
Keep as P0 strategic target. Later mockup should preserve the calm workspace-first hierarchy while making one next action dominant and keeping diagnostic activity secondary.
|
||||
@ -0,0 +1,48 @@
|
||||
# UI-002 Environment Dashboard
|
||||
|
||||
| Field | Value |
|
||||
| --- | --- |
|
||||
| Route | `/admin/workspaces/{workspace}/environments/{environment}` |
|
||||
| Source | `EnvironmentDashboard`, managed-environment widgets |
|
||||
| Area / scope | Environment dashboard / environment-bound |
|
||||
| Archetype | Overview / Dashboard |
|
||||
| Design depth | Strategic Surface |
|
||||
| Repo truth | repo-verified |
|
||||
| Screenshot | `../screenshots/desktop/ui-002-environment-dashboard.png` |
|
||||
| Browser status | Reached with local Spec 180 smoke fixture. |
|
||||
|
||||
## First Five Seconds
|
||||
|
||||
The page makes the selected environment visible and shows backup/recovery posture. It is clear that the operator is inside an environment, but several posture, verification, backup, and recovery messages compete for what should happen first.
|
||||
|
||||
## Productization Review
|
||||
|
||||
- Decision-first: strong but dense.
|
||||
- Evidence-first: good evidence/posture signals, but proof hierarchy needs simplification.
|
||||
- Context: workspace + environment route is explicit.
|
||||
- Customer/auditor safety: operator-facing; customer-safe language should be checked before reuse.
|
||||
- Diagnostics: verification and health details should stay progressive.
|
||||
|
||||
## Information Inventory
|
||||
|
||||
Default content includes environment name, backup health, recovery readiness, operations, verification/reporting widgets, and navigation to environment-owned resources. Status signals include stale/non-healthy backup posture and recovery evidence concerns.
|
||||
|
||||
## Dangerous Actions
|
||||
|
||||
Likely downstream actions include backup, restore, permission checks, provider fixes, and baseline compare. Target design must show mutation scope before action: TenantPilot only, Microsoft tenant, or simulation only.
|
||||
|
||||
## Scores
|
||||
|
||||
| IA | Density | User Clarity | Sellability | Disclosure | Hierarchy | DS Fit | A11y | Responsive | Components | UX Writing | Perf |
|
||||
| ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: |
|
||||
| 3 | 3 | 4 | 4 | 3 | 3 | 4 | 3 | 3 | 4 | 4 | 4 |
|
||||
|
||||
## Top Issues
|
||||
|
||||
1. Too many domain signals appear with similar weight.
|
||||
2. Backup truth and recovery evidence need clearer separation.
|
||||
3. Dangerous downstream actions need impact/confirmation/evidence review in target mockup.
|
||||
|
||||
## Target Direction
|
||||
|
||||
P0 individual target mockup. The page should become the environment command surface: one primary posture decision, secondary domain drilldowns, and diagnostics behind deliberate disclosure.
|
||||
@ -0,0 +1,48 @@
|
||||
# UI-003 Operations
|
||||
|
||||
| Field | Value |
|
||||
| --- | --- |
|
||||
| Route | `/admin/workspaces/{workspace}/operations` |
|
||||
| Source | `Operations`, `OperationRunLinks` |
|
||||
| Area / scope | Monitoring / workspace |
|
||||
| Archetype | Operations / Monitoring |
|
||||
| Design depth | Strategic Surface |
|
||||
| Repo truth | repo-verified |
|
||||
| Screenshot | `../screenshots/desktop/ui-003-operations.png` |
|
||||
| Browser status | Reached through local workspace route. |
|
||||
|
||||
## First Five Seconds
|
||||
|
||||
The page reads as an operations monitor. It communicates execution truth, but it still needs a sharper split between active work, terminal follow-up, and diagnostic history.
|
||||
|
||||
## Productization Review
|
||||
|
||||
- Decision-first: medium; monitoring tends to be chronological.
|
||||
- Evidence-first: OperationRun records are the source.
|
||||
- Context: workspace route is explicit.
|
||||
- Customer/auditor safety: not customer-facing by default.
|
||||
- Diagnostics: appropriate as the primary mode here, but should not imply governance health.
|
||||
|
||||
## Information Inventory
|
||||
|
||||
The page exposes run state, status, recent work, and likely links to run detail. Execution outcome is visible; governance result and artifact truth remain separate surfaces.
|
||||
|
||||
## Dangerous Actions
|
||||
|
||||
Potential actions include retry, cancel, investigate, or open related artifacts. Target design should keep terminal actions confirmation-gated and secondary to run inspection.
|
||||
|
||||
## Scores
|
||||
|
||||
| IA | Density | User Clarity | Sellability | Disclosure | Hierarchy | DS Fit | A11y | Responsive | Components | UX Writing | Perf |
|
||||
| ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: |
|
||||
| 3 | 4 | 4 | 3 | 4 | 3 | 4 | 3 | 3 | 4 | 3 | 4 |
|
||||
|
||||
## Top Issues
|
||||
|
||||
1. Execution truth must stay visually separate from product health.
|
||||
2. Detail drilldowns need consistent evidence/result links.
|
||||
3. Responsive/table behavior was not captured.
|
||||
|
||||
## Target Direction
|
||||
|
||||
P1 strategic target. Use one monitoring pattern for active, failed, partial, and completed runs, with evidence/result links delegated to shared OperationRun UX contracts.
|
||||
@ -0,0 +1,48 @@
|
||||
# UI-004 Governance Inbox
|
||||
|
||||
| Field | Value |
|
||||
| --- | --- |
|
||||
| Route | `/admin/governance/inbox` |
|
||||
| Source | `GovernanceInbox` |
|
||||
| Area / scope | Governance / workspace |
|
||||
| Archetype | Findings / Inbox |
|
||||
| Design depth | Strategic Surface |
|
||||
| Repo truth | repo-verified |
|
||||
| Screenshot | `../screenshots/desktop/ui-004-governance-inbox.png` |
|
||||
| Browser status | Reached through local workspace route. |
|
||||
|
||||
## First Five Seconds
|
||||
|
||||
The page is positioned as a decision queue. It needs to make the human-in-the-loop moment unmistakable: what is pending, why it matters, who owns it, and what should be done next.
|
||||
|
||||
## Productization Review
|
||||
|
||||
- Decision-first: strong concept, needs sharper first action.
|
||||
- Evidence-first: should link to finding, review, run, and proof artifacts.
|
||||
- Context: workspace hub.
|
||||
- Customer/auditor safety: operator-facing, but outputs may feed customer review.
|
||||
- Diagnostics: should remain lower than recommendation and evidence basis.
|
||||
|
||||
## Information Inventory
|
||||
|
||||
Default content should include pending decision type, impact, environment scope, evidence basis, owner, age/SLA, and recommended next action. Any raw reason ownership or payload data should be hidden.
|
||||
|
||||
## Dangerous Actions
|
||||
|
||||
Potential approve, reject, accept risk, close, assign, or escalate actions. Target handling requires explicit confirmation and audit posture per action family.
|
||||
|
||||
## Scores
|
||||
|
||||
| IA | Density | User Clarity | Sellability | Disclosure | Hierarchy | DS Fit | A11y | Responsive | Components | UX Writing | Perf |
|
||||
| ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: |
|
||||
| 3 | 3 | 3 | 4 | 3 | 3 | 4 | 3 | 3 | 4 | 3 | 4 |
|
||||
|
||||
## Top Issues
|
||||
|
||||
1. Needs one dominant queue-clearing action model.
|
||||
2. Decision evidence and status dimensions must be separated.
|
||||
3. Customer-safe downstream wording needs review.
|
||||
|
||||
## Target Direction
|
||||
|
||||
P0 individual target mockup. This should become the central operator decision surface rather than another technical list.
|
||||
@ -0,0 +1,48 @@
|
||||
# UI-005 Decision Register
|
||||
|
||||
| Field | Value |
|
||||
| --- | --- |
|
||||
| Route | `/admin/governance/decisions` |
|
||||
| Source | `DecisionRegister` |
|
||||
| Area / scope | Governance / workspace |
|
||||
| Archetype | Evidence / Audit |
|
||||
| Design depth | Strategic Surface |
|
||||
| Repo truth | repo-verified |
|
||||
| Screenshot | `../screenshots/desktop/ui-005-decision-register.png` |
|
||||
| Browser status | Reached through local workspace route. |
|
||||
|
||||
## First Five Seconds
|
||||
|
||||
The page reads as a governance record surface. It should make historical decision truth, proof links, and review-pack/customer-safe relevance visible without becoming a raw audit table.
|
||||
|
||||
## Productization Review
|
||||
|
||||
- Decision-first: historical rather than queue-first.
|
||||
- Evidence-first: strong fit for proof/run/evidence linkage.
|
||||
- Context: workspace hub, environment filtering where explicit.
|
||||
- Customer/auditor safety: high, because data may feed customer-facing summaries.
|
||||
- Diagnostics: raw details should be lower than outcome and proof.
|
||||
|
||||
## Information Inventory
|
||||
|
||||
Default content should show decision type, outcome, owner/actor, environment scope where relevant, evidence basis, related operation/run, and review-pack inclusion state.
|
||||
|
||||
## Dangerous Actions
|
||||
|
||||
No immediate destructive action was exercised. Related actions may reopen or link decisions; target review should ensure no unsupported mutation appears primary.
|
||||
|
||||
## Scores
|
||||
|
||||
| IA | Density | User Clarity | Sellability | Disclosure | Hierarchy | DS Fit | A11y | Responsive | Components | UX Writing | Perf |
|
||||
| ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: |
|
||||
| 4 | 4 | 4 | 4 | 4 | 4 | 4 | 3 | 3 | 4 | 4 | 4 |
|
||||
|
||||
## Top Issues
|
||||
|
||||
1. Needs a customer-safe register/reporting variant decision.
|
||||
2. Proof links must stay visible but not overwhelm decision summaries.
|
||||
3. Environment filter state must remain explicit.
|
||||
|
||||
## Target Direction
|
||||
|
||||
P1 strategic target. Treat as the governance ledger pattern for historical proof and customer-safe summaries.
|
||||
@ -0,0 +1,48 @@
|
||||
# UI-006 Customer Review Workspace
|
||||
|
||||
| Field | Value |
|
||||
| --- | --- |
|
||||
| Route | `/admin/reviews/workspace` |
|
||||
| Source | `CustomerReviewWorkspace` |
|
||||
| Area / scope | Customer review / workspace |
|
||||
| Archetype | Customer Workspace |
|
||||
| Design depth | Strategic Surface |
|
||||
| Repo truth | repo-verified |
|
||||
| Screenshot | `../screenshots/desktop/ui-006-customer-review-workspace.png` |
|
||||
| Browser status | Reached through local workspace route. |
|
||||
|
||||
## First Five Seconds
|
||||
|
||||
This is the most important customer-safe productization candidate. The page should answer what the customer can trust, what changed, what risks are accepted, which evidence supports the state, and what should happen next.
|
||||
|
||||
## Productization Review
|
||||
|
||||
- Decision-first: strong candidate, needs final target hierarchy.
|
||||
- Evidence-first: must anchor all claims to review/evidence artifacts.
|
||||
- Context: workspace-level customer view.
|
||||
- Customer/auditor safety: primary concern.
|
||||
- Diagnostics: raw/internal details must stay hidden by default.
|
||||
|
||||
## Information Inventory
|
||||
|
||||
Default content should include review readiness, evidence basis, accepted risk summary, decision summary, review-pack download, and management-readable next action.
|
||||
|
||||
## Dangerous Actions
|
||||
|
||||
Customer-facing surface should be read-first. Export/download and publish/review actions need clear scope, audit, and language.
|
||||
|
||||
## Scores
|
||||
|
||||
| IA | Density | User Clarity | Sellability | Disclosure | Hierarchy | DS Fit | A11y | Responsive | Components | UX Writing | Perf |
|
||||
| ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: |
|
||||
| 3 | 3 | 3 | 5 | 3 | 3 | 4 | 3 | 3 | 4 | 3 | 4 |
|
||||
|
||||
## Top Issues
|
||||
|
||||
1. Needs customer-safe language and data exposure review before sellable use.
|
||||
2. Evidence and accepted-risk meaning should be visible without raw diagnostics.
|
||||
3. Requires individual target mockup, not only cleanup.
|
||||
|
||||
## Target Direction
|
||||
|
||||
P0 individual target mockup and follow-up implementation wave. This page is a core sellability surface.
|
||||
48
docs/ui-ux-enterprise-audit/page-reports/ui-007-alerts.md
Normal file
48
docs/ui-ux-enterprise-audit/page-reports/ui-007-alerts.md
Normal file
@ -0,0 +1,48 @@
|
||||
# UI-007 Alerts / Alert Deliveries
|
||||
|
||||
| Field | Value |
|
||||
| --- | --- |
|
||||
| Route | `/admin/alerts` and `/admin/alerts/alert-deliveries` |
|
||||
| Source | `AlertsCluster`, `AlertDeliveryResource` |
|
||||
| Area / scope | Monitoring / workspace |
|
||||
| Archetype | Operations / Monitoring |
|
||||
| Design depth | Strategic Surface |
|
||||
| Repo truth | repo-verified |
|
||||
| Screenshot | `../screenshots/desktop/ui-007-alerts.png` |
|
||||
| Browser status | Opening `/admin/alerts` landed on Alert Deliveries. |
|
||||
|
||||
## First Five Seconds
|
||||
|
||||
The surface currently reads more like a table-backed delivery register than a decision-first alert center. That may be correct for deliveries, but the broader alert center needs a clearer overview/state pattern.
|
||||
|
||||
## Productization Review
|
||||
|
||||
- Decision-first: weak for alert overview, acceptable for delivery history.
|
||||
- Evidence-first: delivery records are explicit.
|
||||
- Context: workspace hub; environment filter should be visible when used.
|
||||
- Customer/auditor safety: not customer-facing by default.
|
||||
- Diagnostics: delivery failure detail should not dominate alert outcome.
|
||||
|
||||
## Information Inventory
|
||||
|
||||
Default content should distinguish alert rules, destinations, deliveries, failures, and required follow-up. Alert delivery rows should show delivery outcome, target, event type, environment attribution, and retry/diagnostic state.
|
||||
|
||||
## Dangerous Actions
|
||||
|
||||
Alert destination enable/disable, destination delete, and test-send actions are high-impact enough to require confirmation/audit review in later specs.
|
||||
|
||||
## Scores
|
||||
|
||||
| IA | Density | User Clarity | Sellability | Disclosure | Hierarchy | DS Fit | A11y | Responsive | Components | UX Writing | Perf |
|
||||
| ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: |
|
||||
| 3 | 4 | 3 | 3 | 3 | 3 | 4 | 3 | 3 | 4 | 3 | 4 |
|
||||
|
||||
## Top Issues
|
||||
|
||||
1. `/admin/alerts` needs an explicit alert-center decision model.
|
||||
2. Delivery table and configuration surfaces should not share the same design priority.
|
||||
3. Environment filtering should stay clear and chip-backed.
|
||||
|
||||
## Target Direction
|
||||
|
||||
P1 strategic target for Alert Center, domain pattern for deliveries/rules/destinations.
|
||||
48
docs/ui-ux-enterprise-audit/page-reports/ui-008-audit-log.md
Normal file
48
docs/ui-ux-enterprise-audit/page-reports/ui-008-audit-log.md
Normal file
@ -0,0 +1,48 @@
|
||||
# UI-008 Audit Log
|
||||
|
||||
| Field | Value |
|
||||
| --- | --- |
|
||||
| Route | `/admin/audit-log` |
|
||||
| Source | `AuditLog` page |
|
||||
| Area / scope | Evidence / audit / workspace |
|
||||
| Archetype | Evidence / Audit |
|
||||
| Design depth | Strategic Surface |
|
||||
| Repo truth | repo-verified |
|
||||
| Screenshot | `../screenshots/desktop/ui-008-audit-log.png` |
|
||||
| Browser status | Reached through workspace route. |
|
||||
|
||||
## First Five Seconds
|
||||
|
||||
The page is clearly an audit log. Its product role should be audit evidence first, diagnostics second, with explicit filters and no raw payload dominance in the default layout.
|
||||
|
||||
## Productization Review
|
||||
|
||||
- Decision-first: medium, because audit is investigative.
|
||||
- Evidence-first: strong.
|
||||
- Context: workspace hub with optional environment filter.
|
||||
- Customer/auditor safety: high for export/review contexts.
|
||||
- Diagnostics: raw metadata should be deliberately disclosed.
|
||||
|
||||
## Information Inventory
|
||||
|
||||
Default content should expose action, actor, target, workspace/environment attribution, timestamp, and outcome. Event inspection should stay scoped by filter and entitlement.
|
||||
|
||||
## Dangerous Actions
|
||||
|
||||
No visible destructive action should be primary. Export or detail-inspection actions require tenant-safe data exposure review.
|
||||
|
||||
## Scores
|
||||
|
||||
| IA | Density | User Clarity | Sellability | Disclosure | Hierarchy | DS Fit | A11y | Responsive | Components | UX Writing | Perf |
|
||||
| ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: |
|
||||
| 4 | 4 | 4 | 4 | 4 | 4 | 4 | 3 | 3 | 4 | 4 | 4 |
|
||||
|
||||
## Top Issues
|
||||
|
||||
1. Selected-event detail must respect active environment filters.
|
||||
2. Customer/auditor export language needs dedicated review.
|
||||
3. Metadata/raw payload hierarchy should stay secondary.
|
||||
|
||||
## Target Direction
|
||||
|
||||
P1 strategic target as the auditability proof pattern for workspace and environment-attributed events.
|
||||
@ -0,0 +1,48 @@
|
||||
# UI-009 Provider Connections
|
||||
|
||||
| Field | Value |
|
||||
| --- | --- |
|
||||
| Route | `/admin/provider-connections` |
|
||||
| Source | `ProviderConnectionResource` |
|
||||
| Area / scope | Provider / integration / workspace |
|
||||
| Archetype | Provider / Integration |
|
||||
| Design depth | Strategic Surface |
|
||||
| Repo truth | repo-verified |
|
||||
| Screenshot | `../screenshots/desktop/ui-009-provider-connections.png` |
|
||||
| Browser status | Reached through workspace route. |
|
||||
|
||||
## First Five Seconds
|
||||
|
||||
The surface is the main integration authority. It should make connection health, scope, credentials/consent state, and safe next action legible without exposing secrets or raw provider errors by default.
|
||||
|
||||
## Productization Review
|
||||
|
||||
- Decision-first: medium; table needs stronger next-action state.
|
||||
- Evidence-first: provider health and verification can support decisions.
|
||||
- Context: workspace-owned provider connection surface.
|
||||
- Customer/auditor safety: internal/operator only.
|
||||
- Diagnostics: raw provider details must stay hidden or support-gated.
|
||||
|
||||
## Information Inventory
|
||||
|
||||
Default content should include provider, connection type, target scope, health, permissions/consent, last verification, and next action. Diagnostic details should explain missing policy/scopes without raw secrets.
|
||||
|
||||
## Dangerous Actions
|
||||
|
||||
Credential rotation, disconnect/disable, reverify, and delete are high-impact. Target design must include authorization, confirmation, audit, and recovery guidance.
|
||||
|
||||
## Scores
|
||||
|
||||
| IA | Density | User Clarity | Sellability | Disclosure | Hierarchy | DS Fit | A11y | Responsive | Components | UX Writing | Perf |
|
||||
| ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: |
|
||||
| 3 | 4 | 3 | 4 | 3 | 3 | 4 | 3 | 3 | 4 | 3 | 4 |
|
||||
|
||||
## Top Issues
|
||||
|
||||
1. Needs stronger health/permission summary over raw integration detail.
|
||||
2. Dangerous provider actions require target confirmation and audit treatment.
|
||||
3. Provider-specific terminology should not leak into platform-core copy.
|
||||
|
||||
## Target Direction
|
||||
|
||||
P0 individual target mockup. This is a trust-critical setup and recovery surface.
|
||||
@ -0,0 +1,48 @@
|
||||
# UI-010 Baseline Profiles
|
||||
|
||||
| Field | Value |
|
||||
| --- | --- |
|
||||
| Route | `/admin/baseline-profiles` |
|
||||
| Source | `BaselineProfileResource` |
|
||||
| Area / scope | Governance / workspace-owned analysis |
|
||||
| Archetype | Drift / Diff |
|
||||
| Design depth | Strategic Surface |
|
||||
| Repo truth | repo-verified |
|
||||
| Screenshot | `../screenshots/desktop/ui-010-baseline-profiles.png` |
|
||||
| Browser status | Reached through workspace route. |
|
||||
|
||||
## First Five Seconds
|
||||
|
||||
The page is a baseline library. It needs to make the reusable standard, snapshot truth, assignment state, and compare readiness clearer than a generic admin resource.
|
||||
|
||||
## Productization Review
|
||||
|
||||
- Decision-first: medium; library behavior is visible but product purpose needs clearer framing.
|
||||
- Evidence-first: snapshot and compare links should be central.
|
||||
- Context: workspace-owned, not environment shell.
|
||||
- Customer/auditor safety: not directly customer-facing.
|
||||
- Diagnostics: capture/compare evidence should be available on demand.
|
||||
|
||||
## Information Inventory
|
||||
|
||||
Default content should include profile status, capture mode, latest snapshot, assignment count, compare posture, and next action.
|
||||
|
||||
## Dangerous Actions
|
||||
|
||||
Capture, compare, archive, and baseline assignment changes are high impact. They need confirmation, authorization, audit, and OperationRun continuity.
|
||||
|
||||
## Scores
|
||||
|
||||
| IA | Density | User Clarity | Sellability | Disclosure | Hierarchy | DS Fit | A11y | Responsive | Components | UX Writing | Perf |
|
||||
| ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: |
|
||||
| 3 | 4 | 3 | 4 | 3 | 3 | 4 | 3 | 3 | 4 | 3 | 4 |
|
||||
|
||||
## Top Issues
|
||||
|
||||
1. Generic resource feel hides the product role of baselines.
|
||||
2. Snapshot truth and assigned-environment impact need stronger hierarchy.
|
||||
3. Dangerous capture/compare actions need target-state review.
|
||||
|
||||
## Target Direction
|
||||
|
||||
P1 strategic target for governance baseline library and domain pattern for related create/edit/detail pages.
|
||||
48
docs/ui-ux-enterprise-audit/page-reports/ui-011-reviews.md
Normal file
48
docs/ui-ux-enterprise-audit/page-reports/ui-011-reviews.md
Normal file
@ -0,0 +1,48 @@
|
||||
# UI-011 Review Register
|
||||
|
||||
| Field | Value |
|
||||
| --- | --- |
|
||||
| Route | `/admin/reviews` |
|
||||
| Source | `ReviewRegister` |
|
||||
| Area / scope | Reviews / workspace |
|
||||
| Archetype | Reviews |
|
||||
| Design depth | Strategic Surface |
|
||||
| Repo truth | repo-verified |
|
||||
| Screenshot | `../screenshots/desktop/ui-011-reviews.png` |
|
||||
| Browser status | Reached through workspace route. |
|
||||
|
||||
## First Five Seconds
|
||||
|
||||
The page is a review register. It should help an operator understand review readiness, open work, evidence basis, publication state, and customer-facing outputs without requiring detail-page reconstruction.
|
||||
|
||||
## Productization Review
|
||||
|
||||
- Decision-first: medium.
|
||||
- Evidence-first: should link to evidence/review packs.
|
||||
- Context: workspace hub.
|
||||
- Customer/auditor safety: high because review outputs become customer-facing.
|
||||
- Diagnostics: review internals should stay below outcome/readiness.
|
||||
|
||||
## Information Inventory
|
||||
|
||||
Default content should show review subject, lifecycle, readiness, evidence freshness, accepted risk state, and next action.
|
||||
|
||||
## Dangerous Actions
|
||||
|
||||
Publish, export, review-pack generation, or close actions are high-impact and must preserve auditability and confirmation where applicable.
|
||||
|
||||
## Scores
|
||||
|
||||
| IA | Density | User Clarity | Sellability | Disclosure | Hierarchy | DS Fit | A11y | Responsive | Components | UX Writing | Perf |
|
||||
| ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: |
|
||||
| 3 | 4 | 3 | 4 | 3 | 3 | 4 | 3 | 3 | 4 | 3 | 4 |
|
||||
|
||||
## Top Issues
|
||||
|
||||
1. Review readiness needs a first-class summary.
|
||||
2. Customer-safe output state should be obvious.
|
||||
3. Evidence freshness and accepted-risk visibility need consistent patterns.
|
||||
|
||||
## Target Direction
|
||||
|
||||
P1 strategic target paired with the Customer Review Workspace target.
|
||||
@ -0,0 +1,48 @@
|
||||
# UI-012 Finding Exceptions Queue
|
||||
|
||||
| Field | Value |
|
||||
| --- | --- |
|
||||
| Route | `/admin/finding-exceptions/queue` |
|
||||
| Source | `FindingExceptionsQueue` |
|
||||
| Area / scope | Governance / workspace |
|
||||
| Archetype | Exceptions / Accepted Risk |
|
||||
| Design depth | Strategic Surface |
|
||||
| Repo truth | repo-verified |
|
||||
| Screenshot | `../screenshots/desktop/ui-012-finding-exceptions-queue.png` |
|
||||
| Browser status | Reached through workspace route. |
|
||||
|
||||
## First Five Seconds
|
||||
|
||||
The page is an accepted-risk queue. It needs to make risk ownership, expiry, evidence basis, and approval/rejection consequences immediately clear.
|
||||
|
||||
## Productization Review
|
||||
|
||||
- Decision-first: strong candidate.
|
||||
- Evidence-first: exception evidence and linked findings should be visible.
|
||||
- Context: workspace hub with environment-filter possibilities.
|
||||
- Customer/auditor safety: high, because accepted risk is customer-relevant.
|
||||
- Diagnostics: raw finding/provider evidence should be secondary.
|
||||
|
||||
## Information Inventory
|
||||
|
||||
Default content should show exception state, requester/owner, affected environment, expiration, evidence links, decision history, and required action.
|
||||
|
||||
## Dangerous Actions
|
||||
|
||||
Approve exception, reject renewal, revoke exception, and accept risk are high impact. They require explicit confirmation, authorization, audit, and customer-safe explanation.
|
||||
|
||||
## Scores
|
||||
|
||||
| IA | Density | User Clarity | Sellability | Disclosure | Hierarchy | DS Fit | A11y | Responsive | Components | UX Writing | Perf |
|
||||
| ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: |
|
||||
| 3 | 3 | 3 | 4 | 3 | 3 | 4 | 3 | 3 | 4 | 3 | 4 |
|
||||
|
||||
## Top Issues
|
||||
|
||||
1. Risk decision language needs product-target treatment.
|
||||
2. Evidence basis and expiry must be visible before approval.
|
||||
3. Customer-safe accepted-risk wording requires review.
|
||||
|
||||
## Target Direction
|
||||
|
||||
P0/P1 individual target depending on customer-review sequencing. Treat as the accepted-risk decision pattern.
|
||||
@ -0,0 +1,48 @@
|
||||
# UI-013 Environment Backup Sets
|
||||
|
||||
| Field | Value |
|
||||
| --- | --- |
|
||||
| Route | `/admin/workspaces/{workspace}/environments/{environment}/backup-sets` |
|
||||
| Source | `BackupSetResource` |
|
||||
| Area / scope | Backup / restore / environment |
|
||||
| Archetype | Backup / Restore |
|
||||
| Design depth | Strategic Surface |
|
||||
| Repo truth | repo-verified route; browser blocked |
|
||||
| Screenshot | `../screenshots/desktop/ui-013-environment-backup-sets.png` |
|
||||
| Browser status | Local Spec 180 fixture returned Forbidden. |
|
||||
|
||||
## First Five Seconds
|
||||
|
||||
The browser pass could not evaluate the product page because the fixture lacked sufficient capability or state. The route remains strategic because backup sets are recovery evidence and restore-point truth.
|
||||
|
||||
## Productization Review
|
||||
|
||||
- Decision-first: not evaluated in browser.
|
||||
- Evidence-first: expected to be central.
|
||||
- Context: environment-bound route.
|
||||
- Customer/auditor safety: high when used as restore proof.
|
||||
- Diagnostics: raw backup payload must not dominate default view.
|
||||
|
||||
## Information Inventory
|
||||
|
||||
Expected default content should show backup set identity, source environment, capture time, coverage, integrity/fidelity, failure/partial state, and restore readiness.
|
||||
|
||||
## Dangerous Actions
|
||||
|
||||
Create backup, retry, restore from backup, delete/archive, and export evidence are high impact and require confirmation, audit, and OperationRun continuity.
|
||||
|
||||
## Scores
|
||||
|
||||
| IA | Density | User Clarity | Sellability | Disclosure | Hierarchy | DS Fit | A11y | Responsive | Components | UX Writing | Perf |
|
||||
| ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: |
|
||||
| 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
|
||||
|
||||
## Top Issues
|
||||
|
||||
1. Browser review blocked by local capability/data.
|
||||
2. Strategic recovery truth needs individual target mockup.
|
||||
3. Restore-point safety posture must be first-class.
|
||||
|
||||
## Target Direction
|
||||
|
||||
P0 backup/recovery target mockup. Add a seeded/capability-backed browser review in the implementation-wave spec.
|
||||
@ -0,0 +1,48 @@
|
||||
# UI-014 Restore Runs
|
||||
|
||||
| Field | Value |
|
||||
| --- | --- |
|
||||
| Route | `/admin/workspaces/{workspace}/environments/{environment}/restore-runs` |
|
||||
| Source | `RestoreRunResource` |
|
||||
| Area / scope | Backup / restore / environment |
|
||||
| Archetype | Backup / Restore |
|
||||
| Design depth | Strategic Surface |
|
||||
| Repo truth | repo-verified route; browser blocked |
|
||||
| Screenshot | `../screenshots/desktop/ui-014-restore-runs.png` |
|
||||
| Browser status | Local Spec 180 fixture returned Forbidden. |
|
||||
|
||||
## First Five Seconds
|
||||
|
||||
The browser pass could not evaluate the product page because restore capability/state was unavailable. The route is still strategic because restore is the highest-risk operator workflow in the product.
|
||||
|
||||
## Productization Review
|
||||
|
||||
- Decision-first: not evaluated in browser.
|
||||
- Evidence-first: restore preview, request, result, and recovery proof must be central.
|
||||
- Context: environment-bound route.
|
||||
- Customer/auditor safety: high after execution.
|
||||
- Diagnostics: raw provider responses must stay secondary.
|
||||
|
||||
## Information Inventory
|
||||
|
||||
Expected default content should distinguish restore intent, simulation/preview, validation, requested items, execution state, result truth, and recovery evidence.
|
||||
|
||||
## Dangerous Actions
|
||||
|
||||
Restore execution is destructive/high-impact. Target state must include dry-run/preview, explicit confirmation, audit, OperationRun continuity, and post-run evidence.
|
||||
|
||||
## Scores
|
||||
|
||||
| IA | Density | User Clarity | Sellability | Disclosure | Hierarchy | DS Fit | A11y | Responsive | Components | UX Writing | Perf |
|
||||
| ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: |
|
||||
| 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
|
||||
|
||||
## Top Issues
|
||||
|
||||
1. Browser review blocked by local capability/data.
|
||||
2. Restore workflow needs individual target mockup and safety review.
|
||||
3. Preview/result/evidence truth must be separated visually.
|
||||
|
||||
## Target Direction
|
||||
|
||||
P0 restore safety target mockup and implementation-wave smoke with an authorized fixture.
|
||||
@ -0,0 +1,48 @@
|
||||
# UI-015 Baseline Compare
|
||||
|
||||
| Field | Value |
|
||||
| --- | --- |
|
||||
| Route | `/admin/workspaces/{workspace}/environments/{environment}/baseline-compare` |
|
||||
| Source | `BaselineCompareLanding` |
|
||||
| Area / scope | Governance / environment |
|
||||
| Archetype | Drift / Diff |
|
||||
| Design depth | Strategic Surface |
|
||||
| Repo truth | repo-verified route; browser blocked |
|
||||
| Screenshot | `../screenshots/desktop/ui-015-baseline-compare-blocked-404.png` |
|
||||
| Browser status | Route is present in route list, but the local Spec 180 fixture returned 404 for tested environment variants. |
|
||||
|
||||
## First Five Seconds
|
||||
|
||||
The browser pass could not evaluate the actual Baseline Compare page. Spec 319 made this page environment-owned, so it remains strategic even though this fixture could not render it.
|
||||
|
||||
## Productization Review
|
||||
|
||||
- Decision-first: not evaluated in browser.
|
||||
- Evidence-first: expected to show assignment, compare state, evidence gaps, and next action.
|
||||
- Context: environment-bound route required.
|
||||
- Customer/auditor safety: medium/high because compare posture feeds governance decisions.
|
||||
- Diagnostics: raw compare evidence should be progressive.
|
||||
|
||||
## Information Inventory
|
||||
|
||||
Expected default content should show selected environment, assigned baseline, compare readiness, latest result, gaps, operation links, and recommended action.
|
||||
|
||||
## Dangerous Actions
|
||||
|
||||
Compare now and baseline assignment/capture actions are high-impact and must keep confirmation, authorization, audit, and OperationRun links.
|
||||
|
||||
## Scores
|
||||
|
||||
| IA | Density | User Clarity | Sellability | Disclosure | Hierarchy | DS Fit | A11y | Responsive | Components | UX Writing | Perf |
|
||||
| ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: |
|
||||
| 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
|
||||
|
||||
## Top Issues
|
||||
|
||||
1. Browser review blocked for available fixture.
|
||||
2. Environment-owned route must remain visibly route-bound.
|
||||
3. Assignment, compare, and evidence-gap truth need target hierarchy.
|
||||
|
||||
## Target Direction
|
||||
|
||||
P1 individual target mockup after a suitable baseline fixture exists.
|
||||
106
docs/ui-ux-enterprise-audit/route-inventory.md
Normal file
106
docs/ui-ux-enterprise-audit/route-inventory.md
Normal file
@ -0,0 +1,106 @@
|
||||
# Route Inventory
|
||||
|
||||
Source basis: `./vendor/bin/sail artisan route:list --json`, Laravel Boost route listing, Filament provider/page/resource discovery, navigation support files, and the Spec 323 browser pass.
|
||||
|
||||
Rows are route/page audit rows, not target mockups. Dynamic record routes are listed as route families when the same page class and design decision apply to multiple records.
|
||||
|
||||
| ID | Route / URL | Source | Page Name | Area | Scope | Reachability | Auth/RBAC Notes | Primary Archetype | Secondary Archetype | Design Depth | Repo Truth | Screenshot | Page Report | Notes |
|
||||
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
|
||||
| UI-001 | `/admin` -> `/admin/workspaces/{workspace}/overview` | route + `WorkspaceOverview` | Workspace Overview | App shell | workspace | reachable | workspace member | Overview / Dashboard | Workspace / Tenant Context | Strategic Surface | repo-verified | [desktop](screenshots/desktop/ui-001-workspace-overview.png) | [report](page-reports/ui-001-workspace-overview.md) | Redirected from `/admin`; first workspace-level landing page. |
|
||||
| UI-002 | `/admin/workspaces/{workspace}/overview` | route + page class | Workspace Overview direct | App shell | workspace | reachable | workspace member | Overview / Dashboard | Workspace / Tenant Context | Strategic Surface | repo-verified | [desktop](screenshots/desktop/ui-001-workspace-overview.png) | [report](page-reports/ui-001-workspace-overview.md) | Same surface as UI-001, route-owned workspace shell. |
|
||||
| UI-003 | `/admin/choose-workspace` | Filament page | Choose Workspace | App shell | workspace chooser | reachable | authenticated user | Workspace / Tenant Context | Auth / Access | Domain Pattern Surface | repo-verified | - | - | Workspace context entry point; should remain low-friction and explicit. |
|
||||
| UI-004 | `/admin/choose-environment` | Filament page | Choose Environment | App shell | workspace + environment selector | reachable | workspace member | Workspace / Tenant Context | Auth / Access | Domain Pattern Surface | repo-verified | - | - | Explicit environment-context entry point. |
|
||||
| UI-005 | `/admin/no-access` | Filament page | No Access | Auth/access | admin plane | reachable as guard output | authenticated user | Auth / Access | Utility / Internal | Design-System Cleanup Surface | repo-verified | - | - | Customer-safe denial copy should be checked in later copy pass. |
|
||||
| UI-006 | `/admin/login` | Filament auth page | Admin Login | Auth/access | admin plane | reachable when logged out | guest/admin guard | Auth / Access | Utility / Internal | Design-System Cleanup Surface | repo-verified | - | - | Uses custom Login page. |
|
||||
| UI-007 | `/admin/workspaces` | Workspace resource | Manage Workspaces | Settings / admin | workspace | reachable | workspace membership management capability | Settings / Admin | Workspace / Tenant Context | Strategic Surface | repo-verified | - | - | Membership-management surface, high trust/RBAC importance. |
|
||||
| UI-008 | `/admin/workspaces/create` | Workspace resource | Create Workspace | Settings / admin | workspace | route exists | create capability | Settings / Admin | Commercial / Entitlements | Domain Pattern Surface | repo-verified | - | - | Requires form review for entitlement and owner language. |
|
||||
| UI-009 | `/admin/workspaces/{record}` and `/edit` | Workspace resource | Workspace Detail / Edit | Settings / admin | workspace | route exists | workspace view/edit capability | Settings / Admin | Workspace / Tenant Context | Domain Pattern Surface | repo-verified | - | - | Dynamic record routes need seeded workspace context for visual review. |
|
||||
| UI-010 | `/admin/workspaces/{workspace}/environments` | route + `ManagedEnvironmentsLanding` | Managed Environments | Workspace / environment | workspace | route exists | workspace member | Workspace / Tenant Context | Provider / Integration | Strategic Surface | repo-verified | - | - | Portfolio entry point for environments. |
|
||||
| UI-011 | `/admin/workspaces/{workspace}/environments/{environment}` | route + `EnvironmentDashboard` | Environment Dashboard | Workspace / environment | environment-bound | reachable | workspace + environment entitlement | Overview / Dashboard | Workspace / Tenant Context | Strategic Surface | repo-verified | [desktop](screenshots/desktop/ui-002-environment-dashboard.png) | [report](page-reports/ui-002-environment-dashboard.md) | Core environment product surface. |
|
||||
| UI-012 | `/admin/workspaces/{workspace}/environments/{environment}/diagnostics` | route + page | Environment Diagnostics | Support | environment-bound | route exists | environment entitlement | Support / Diagnostics | Provider / Integration | Domain Pattern Surface | repo-verified | - | - | Diagnostics must remain secondary to operator surfaces. |
|
||||
| UI-013 | `/admin/workspaces/{workspace}/environments/{environment}/access-scopes` | resource page | Environment Access Scopes | Settings / admin | environment-bound | route exists | owner/manager capability expected | Settings / Admin | Auth / Access | Strategic Surface | repo-verified | - | - | RBAC-sensitive environment access surface. |
|
||||
| UI-014 | `/admin/onboarding` | route + wizard | Environment Onboarding | Provider / onboarding | workspace | route exists | workspace capability | Provider / Integration | Workspace / Tenant Context | Strategic Surface | repo-verified | - | - | Large wizard; individual target treatment likely needed. |
|
||||
| UI-015 | `/admin/onboarding/{onboardingDraft}` | route + wizard | Onboarding Draft | Provider / onboarding | workspace | route exists | scoped draft resolver | Provider / Integration | Workspace / Tenant Context | Domain Pattern Surface | repo-verified | - | - | Dynamic workflow state requires seeded draft to review. |
|
||||
| UI-016 | `/admin/workspaces/{workspace}/operations` | route + `Operations` | Operations | Monitoring | workspace | reachable | workspace member | Operations / Monitoring | Evidence / Audit | Strategic Surface | repo-verified | [desktop](screenshots/desktop/ui-003-operations.png) | [report](page-reports/ui-003-operations.md) | Canonical OperationRun hub. |
|
||||
| UI-017 | `/admin/workspaces/{workspace}/operations/{run}` | route + viewer | Operation Detail | Monitoring | workspace record | route exists | workspace + run entitlement | Operations / Monitoring | Evidence / Audit | Strategic Surface | repo-verified | - | - | Dynamic record route; requires run fixture for full review. |
|
||||
| UI-018 | `/admin/alerts` | cluster route | Alerts | Monitoring | workspace hub | reachable, redirects/lands on alert deliveries | workspace member | Operations / Monitoring | Evidence / Audit | Strategic Surface | repo-verified | [desktop](screenshots/desktop/ui-007-alerts.png) | [report](page-reports/ui-007-alerts.md) | Browser landed on Alert Deliveries for cluster subnavigation. |
|
||||
| UI-019 | `/admin/alerts/alert-deliveries` | resource | Alert Deliveries | Monitoring | workspace hub | reachable | workspace member | Operations / Monitoring | Evidence / Audit | Domain Pattern Surface | repo-verified | [desktop](screenshots/desktop/ui-007-alerts.png) | [report](page-reports/ui-007-alerts.md) | Table-backed alert signal surface. |
|
||||
| UI-020 | `/admin/alerts/alert-deliveries/{record}` | resource | Alert Delivery Detail | Monitoring | workspace record | route exists | workspace entitlement | Operations / Monitoring | Evidence / Audit | Domain Pattern Surface | repo-verified | - | - | Dynamic record detail requires delivery fixture. |
|
||||
| UI-021 | `/admin/alerts/alert-rules` | resource | Alert Rules | Monitoring | workspace config | route exists | workspace alert config capability | Settings / Admin | Operations / Monitoring | Domain Pattern Surface | repo-verified | - | - | Configuration surface, not environment-owned. |
|
||||
| UI-022 | `/admin/alerts/alert-rules/create` and `/edit` | resource | Alert Rule Create/Edit | Monitoring | workspace config | route exists | config capability | Settings / Admin | Operations / Monitoring | Domain Pattern Surface | repo-verified | - | - | Mutating config form; dangerous-action review in later pattern pass. |
|
||||
| UI-023 | `/admin/alerts/alert-destinations` | resource | Alert Destinations | Monitoring | workspace config | route exists | destination capability | Settings / Admin | Operations / Monitoring | Domain Pattern Surface | repo-verified | - | - | Alert target management. |
|
||||
| UI-024 | `/admin/alerts/alert-destinations/create`, `/view`, `/edit` | resource | Alert Destination Detail/Edit | Monitoring | workspace config | route exists | destination capability | Settings / Admin | Operations / Monitoring | Domain Pattern Surface | repo-verified | - | - | Includes enable/disable/delete semantics; review high-impact actions later. |
|
||||
| UI-025 | `/admin/audit-log` | route + page | Audit Log | Evidence / audit | workspace hub | reachable | workspace member | Evidence / Audit | Operations / Monitoring | Strategic Surface | repo-verified | [desktop](screenshots/desktop/ui-008-audit-log.png) | [report](page-reports/ui-008-audit-log.md) | Core auditability surface. |
|
||||
| UI-026 | `/admin/finding-exceptions/queue` | page | Finding Exceptions Queue | Governance | workspace hub | reachable | workspace member | Exceptions / Accepted Risk | Findings / Inbox | Strategic Surface | repo-verified | [desktop](screenshots/desktop/ui-012-finding-exceptions-queue.png) | [report](page-reports/ui-012-finding-exceptions-queue.md) | Accepted-risk decision surface. |
|
||||
| UI-027 | `/admin/finding-exceptions/open-queue/{environment}` | route/controller | Exception Queue Deep Link | Governance | environment filter link | route exists | environment entitlement | Exceptions / Accepted Risk | Utility / Internal | Domain Pattern Surface | repo-verified | - | - | Navigation helper into queue; not a standalone product page. |
|
||||
| UI-028 | `/admin/governance/inbox` | page | Governance Inbox | Governance | workspace hub | reachable | workspace member | Findings / Inbox | Evidence / Audit | Strategic Surface | repo-verified | [desktop](screenshots/desktop/ui-004-governance-inbox.png) | [report](page-reports/ui-004-governance-inbox.md) | Strategic operator work surface. |
|
||||
| UI-029 | `/admin/governance/decisions` | page | Decision Register | Governance | workspace hub | reachable | capability-gated access | Evidence / Audit | Findings / Inbox | Strategic Surface | repo-verified | [desktop](screenshots/desktop/ui-005-decision-register.png) | [report](page-reports/ui-005-decision-register.md) | Decision and proof-link surface. |
|
||||
| UI-030 | `/admin/findings/my-work` | page | My Findings | Findings | workspace analysis | route exists | workspace member | Findings / Inbox | Operations / Monitoring | Domain Pattern Surface | repo-verified | - | - | Workspace-owned analysis surface with optional environment filtering. |
|
||||
| UI-031 | `/admin/findings/intake` | page | Findings Intake | Findings | workspace analysis | route exists | workspace member | Findings / Inbox | Operations / Monitoring | Domain Pattern Surface | repo-verified | - | - | Intake queue pattern. |
|
||||
| UI-032 | `/admin/findings/hygiene` | page | Findings Hygiene | Findings | workspace analysis | route exists | workspace member | Findings / Inbox | Support / Diagnostics | Domain Pattern Surface | repo-verified | - | - | Hygiene report pattern. |
|
||||
| UI-033 | `/admin/workspaces/{workspace}/environments/{environment}/findings` | resource | Environment Findings | Findings | environment-bound | route exists | environment entitlement | Findings / Inbox | Evidence / Audit | Domain Pattern Surface | repo-verified | - | - | Environment list page. |
|
||||
| UI-034 | `/admin/workspaces/{workspace}/environments/{environment}/findings/{record}` | resource | Finding Detail | Findings | environment record | route exists | environment + record entitlement | Findings / Inbox | Evidence / Audit | Strategic Surface | repo-verified | - | - | Core triage detail route; needs individual review. |
|
||||
| UI-035 | `/admin/workspaces/{workspace}/environments/{environment}/finding-exceptions` | resource | Environment Exceptions | Governance | environment-bound | route exists | environment entitlement | Exceptions / Accepted Risk | Findings / Inbox | Domain Pattern Surface | repo-verified | - | - | Environment-specific exception list. |
|
||||
| UI-036 | `/admin/workspaces/{workspace}/environments/{environment}/finding-exceptions/{record}` | resource | Exception Detail | Governance | environment record | route exists | environment + record entitlement | Exceptions / Accepted Risk | Evidence / Audit | Strategic Surface | repo-verified | - | - | Risk acceptance detail; dangerous-action review needed. |
|
||||
| UI-037 | `/admin/reviews` | page | Review Register | Reviews | workspace hub | reachable | workspace member | Reviews | Evidence / Audit | Strategic Surface | repo-verified | [desktop](screenshots/desktop/ui-011-reviews.png) | [report](page-reports/ui-011-reviews.md) | Review planning and proof surface. |
|
||||
| UI-038 | `/admin/reviews/workspace` | page | Customer Review Workspace | Customer review | workspace hub | reachable | workspace member | Customer Workspace | Reviews | Strategic Surface | repo-verified | [desktop](screenshots/desktop/ui-006-customer-review-workspace.png) | [report](page-reports/ui-006-customer-review-workspace.md) | Highest customer-safe productization surface. |
|
||||
| UI-039 | `/admin/workspaces/{workspace}/environments/{environment}/environment-reviews` | resource | Environment Reviews | Reviews | environment-bound | route exists | environment entitlement | Reviews | Evidence / Audit | Domain Pattern Surface | repo-verified | - | - | Environment-scoped review list. |
|
||||
| UI-040 | `/admin/workspaces/{workspace}/environments/{environment}/environment-reviews/{record}` | resource | Environment Review Detail | Reviews | environment record | route exists | environment + record entitlement | Reviews | Evidence / Audit | Strategic Surface | repo-verified | - | - | Customer/auditor-facing evidence risk. |
|
||||
| UI-041 | `/admin/workspaces/{workspace}/environments/{environment}/review-packs` | resource | Review Packs | Reviews | environment-bound | route exists | environment entitlement | Reviews | Evidence / Audit | Domain Pattern Surface | repo-verified | - | - | Export artifact list. |
|
||||
| UI-042 | `/admin/workspaces/{workspace}/environments/{environment}/review-packs/{record}` | resource | Review Pack Detail | Reviews | environment record | route exists | environment + record entitlement | Reviews | Evidence / Audit | Strategic Surface | repo-verified | - | - | Export/evidence artifact detail. |
|
||||
| UI-043 | `/admin/review-packs/{reviewPack}/download` | controller | Review Pack Download | Reviews | workspace/environment artifact | route exists | download authorization expected | Reviews | Evidence / Audit | Design-System Cleanup Surface | repo-verified | - | - | Action endpoint, not page; include in coverage due customer artifact impact. |
|
||||
| UI-044 | `/admin/evidence/overview` | route + page | Evidence Overview | Evidence / audit | workspace hub | route exists | workspace member | Evidence / Audit | Reviews | Strategic Surface | repo-verified | - | - | Workspace-wide evidence landing. |
|
||||
| UI-045 | `/admin/workspaces/{workspace}/environments/{environment}/evidence` | resource | Evidence Snapshots | Evidence / audit | environment-bound | route exists | environment entitlement | Evidence / Audit | Reviews | Domain Pattern Surface | repo-verified | - | - | Environment evidence list. |
|
||||
| UI-046 | `/admin/workspaces/{workspace}/environments/{environment}/evidence/{record}` | resource | Evidence Snapshot Detail | Evidence / audit | environment record | route exists | environment + record entitlement | Evidence / Audit | Support / Diagnostics | Strategic Surface | repo-verified | - | - | Raw/support evidence must stay progressively disclosed. |
|
||||
| UI-047 | `/admin/workspaces/{workspace}/environments/{environment}/stored-reports` | resource | Stored Reports | Evidence / audit | environment-bound | route exists | environment entitlement | Evidence / Audit | Reviews | Domain Pattern Surface | repo-verified | - | - | Report artifact list. |
|
||||
| UI-048 | `/admin/workspaces/{workspace}/environments/{environment}/stored-reports/{record}` | resource | Stored Report Detail | Evidence / audit | environment record | route exists | environment + record entitlement | Evidence / Audit | Reviews | Strategic Surface | repo-verified | - | - | Customer/auditor readable report review needed. |
|
||||
| UI-049 | `/admin/workspaces/{workspace}/environments/{environment}/backup-schedules` | resource | Backup Schedules | Backup / restore | environment-bound | route exists | environment entitlement + backup capability | Backup / Restore | Operations / Monitoring | Strategic Surface | repo-verified | - | - | Schedule run/retry actions are high impact. |
|
||||
| UI-050 | `/admin/workspaces/{workspace}/environments/{environment}/backup-schedules/create` and `/edit` | resource | Backup Schedule Create/Edit | Backup / restore | environment-bound | route exists | backup schedule capability | Backup / Restore | Settings / Admin | Domain Pattern Surface | repo-verified | - | - | Form state and confirmation copy need later review. |
|
||||
| UI-051 | `/admin/workspaces/{workspace}/environments/{environment}/backup-sets` | resource | Backup Sets | Backup / restore | environment-bound | browser blocked by capability in fixture | environment entitlement + backup capability | Backup / Restore | Evidence / Audit | Strategic Surface | repo-verified | [blocked](screenshots/desktop/ui-013-environment-backup-sets.png) | [report](page-reports/ui-013-environment-backup-sets.md) | Route exists; local fixture returned Forbidden. |
|
||||
| UI-052 | `/admin/workspaces/{workspace}/environments/{environment}/backup-sets/create` and `/view` | resource | Backup Set Create/View | Backup / restore | environment record/workflow | route exists | backup capability | Backup / Restore | Evidence / Audit | Strategic Surface | repo-verified | - | - | Backup creation and restore-point detail require seeded capability/data. |
|
||||
| UI-053 | `/admin/workspaces/{workspace}/environments/{environment}/restore-runs` | resource | Restore Runs | Backup / restore | environment-bound | browser blocked by capability in fixture | environment entitlement + restore capability | Backup / Restore | Operations / Monitoring | Strategic Surface | repo-verified | [blocked](screenshots/desktop/ui-014-restore-runs.png) | [report](page-reports/ui-014-restore-runs.md) | Route exists; local fixture returned Forbidden. |
|
||||
| UI-054 | `/admin/workspaces/{workspace}/environments/{environment}/restore-runs/create` and `/view` | resource | Restore Run Create/View | Backup / restore | environment record/workflow | route exists | restore capability | Backup / Restore | Operations / Monitoring | Strategic Surface | repo-verified | - | - | Destructive/high-impact workflow; individual target spec required. |
|
||||
| UI-055 | `/admin/baseline-profiles` | resource | Baseline Profiles | Governance | workspace analysis | reachable | workspace member | Drift / Diff | Settings / Admin | Strategic Surface | repo-verified | [desktop](screenshots/desktop/ui-010-baseline-profiles.png) | [report](page-reports/ui-010-baseline-profiles.md) | Workspace-owned baseline library. |
|
||||
| UI-056 | `/admin/baseline-profiles/create` | resource | Create Baseline Profile | Governance | workspace analysis | route exists | baseline capability | Drift / Diff | Settings / Admin | Domain Pattern Surface | repo-verified | - | - | Workspace-owned form. |
|
||||
| UI-057 | `/admin/baseline-profiles/{record}` and `/edit` | resource | Baseline Profile Detail/Edit | Governance | workspace record | route exists | baseline capability | Drift / Diff | Evidence / Audit | Strategic Surface | repo-verified | - | - | Capture/compare actions need dangerous-action audit. |
|
||||
| UI-058 | `/admin/baseline-profiles/{record}/compare-matrix` | page | Baseline Compare Matrix | Governance | workspace analysis | route exists | baseline capability | Drift / Diff | Evidence / Audit | Strategic Surface | repo-verified | - | - | Matrix/product hierarchy review needed. |
|
||||
| UI-059 | `/admin/baseline-snapshots` | resource | Baseline Snapshots | Evidence / audit | workspace analysis | route exists | workspace member | Evidence / Audit | Drift / Diff | Domain Pattern Surface | repo-verified | - | - | Workspace-owned evidence library. |
|
||||
| UI-060 | `/admin/baseline-snapshots/{record}` | resource | Baseline Snapshot Detail | Evidence / audit | workspace record | route exists | workspace + record entitlement | Evidence / Audit | Drift / Diff | Domain Pattern Surface | repo-verified | - | - | Snapshot detail may expose raw payloads; review later. |
|
||||
| UI-061 | `/admin/workspaces/{workspace}/environments/{environment}/baseline-compare` | page | Baseline Compare | Governance | environment-bound | browser blocked/404 in fixture | workspace + environment entitlement and baseline state | Drift / Diff | Operations / Monitoring | Strategic Surface | repo-verified | [blocked](screenshots/desktop/ui-015-baseline-compare-blocked-404.png) | [report](page-reports/ui-015-baseline-compare.md) | Route exists in route list; smoke fixture could not render it. |
|
||||
| UI-062 | `/admin/workspaces/{workspace}/environments/{environment}/inventory` | cluster | Inventory Cluster | Inventory | environment-bound | route exists | environment entitlement | Inventory | Workspace / Tenant Context | Domain Pattern Surface | repo-verified | - | - | Cluster landing/navigation surface. |
|
||||
| UI-063 | `/admin/workspaces/{workspace}/environments/{environment}/inventory/inventory-coverage` | page | Inventory Coverage | Inventory | environment-bound | route exists | environment entitlement | Inventory | Evidence / Audit | Strategic Surface | repo-verified | - | - | Coverage truth page; strategic because it gates evidence confidence. |
|
||||
| UI-064 | `/admin/workspaces/{workspace}/environments/{environment}/inventory-items` | resource | Inventory Items | Inventory | environment-bound | route exists | environment entitlement | Inventory | Evidence / Audit | Domain Pattern Surface | repo-verified | - | - | Core observed-state list. |
|
||||
| UI-065 | `/admin/workspaces/{workspace}/environments/{environment}/inventory-items/{record}` | resource | Inventory Item Detail | Inventory | environment record | route exists | environment + record entitlement | Inventory | Evidence / Audit | Domain Pattern Surface | repo-verified | - | - | Detail report should distinguish raw provider payload from decision content. |
|
||||
| UI-066 | `/admin/workspaces/{workspace}/environments/{environment}/policies` | resource | Policies | Inventory | environment-bound | route exists | environment entitlement | Inventory | Drift / Diff | Domain Pattern Surface | repo-verified | - | - | Intune policy inventory list. |
|
||||
| UI-067 | `/admin/workspaces/{workspace}/environments/{environment}/policies/{record}` | resource | Policy Detail | Inventory | environment record | route exists | environment + record entitlement | Inventory | Drift / Diff | Domain Pattern Surface | repo-verified | - | - | Policy detail includes versions/settings. |
|
||||
| UI-068 | `/admin/workspaces/{workspace}/environments/{environment}/policy-versions` | resource | Policy Versions | Inventory | environment-bound | route exists | environment entitlement | Drift / Diff | Evidence / Audit | Domain Pattern Surface | repo-verified | - | - | Immutable policy version list. |
|
||||
| UI-069 | `/admin/workspaces/{workspace}/environments/{environment}/policy-versions/{record}` | resource | Policy Version Detail | Inventory | environment record | route exists | environment + record entitlement | Drift / Diff | Evidence / Audit | Strategic Surface | repo-verified | - | - | Snapshot/diff detail, high evidence value. |
|
||||
| UI-070 | `/admin/workspaces/{workspace}/environments/{environment}/entra-groups` | resource | Entra Groups | Directory | environment-bound | route exists | environment entitlement | Inventory | Provider / Integration | Domain Pattern Surface | repo-verified | - | - | Provider-bound directory cache list. |
|
||||
| UI-071 | `/admin/workspaces/{workspace}/environments/{environment}/entra-groups/{record}` | resource | Entra Group Detail | Directory | environment record | route exists | environment + record entitlement | Inventory | Provider / Integration | Design-System Cleanup Surface | repo-verified | - | - | Detail page likely pattern-covered. |
|
||||
| UI-072 | `/admin/provider-connections` | resource | Provider Connections | Provider / integration | workspace hub | reachable | workspace provider capability | Provider / Integration | Settings / Admin | Strategic Surface | repo-verified | [desktop](screenshots/desktop/ui-009-provider-connections.png) | [report](page-reports/ui-009-provider-connections.md) | Critical integration and credential surface. |
|
||||
| UI-073 | `/admin/provider-connections/create` | resource | Create Provider Connection | Provider / integration | workspace | route exists | provider manage capability | Provider / Integration | Settings / Admin | Strategic Surface | repo-verified | - | - | Credential/consent flow; individual review needed. |
|
||||
| UI-074 | `/admin/provider-connections/{record}` and `/edit` | resource | Provider Connection Detail/Edit | Provider / integration | workspace record | route exists | provider capability | Provider / Integration | Support / Diagnostics | Strategic Surface | repo-verified | - | - | Health/permission details must avoid raw-first UX. |
|
||||
| UI-075 | `/admin/settings/workspace` | page | Workspace Settings | Settings / admin | workspace hub | route exists | workspace settings view/manage capability | Settings / Admin | Commercial / Entitlements | Domain Pattern Surface | repo-verified | - | - | Workspace settings and lifecycle copy. |
|
||||
| UI-076 | `/admin/cross-environment-compare` | page | Cross Environment Compare | Governance | workspace analysis | route exists | workspace member + environment access | Drift / Diff | Workspace / Tenant Context | Strategic Surface | repo-verified | - | - | Portfolio comparison/promotion workflow. |
|
||||
| UI-077 | `/admin/workspaces/{workspace}/environments/{environment}/required-permissions` | page | Required Permissions | Provider / integration | environment-bound | route exists | environment entitlement | Provider / Integration | Support / Diagnostics | Domain Pattern Surface | repo-verified | - | - | Permission explanation/assist surface. |
|
||||
| UI-078 | `/admin/consent/start` and `/admin/consent/callback` | controller/view | Admin Consent Flow | Provider / integration | workspace/onboarding | route exists | auth/onboarding state | Provider / Integration | Auth / Access | Domain Pattern Surface | repo-verified | - | - | External Microsoft consent handshake; not a normal product page. |
|
||||
| UI-079 | `/admin/rbac/start` and `/admin/rbac/callback` | controller | RBAC Delegated Auth Flow | Auth/access | workspace/onboarding | route exists | auth/RBAC state | Auth / Access | Provider / Integration | Domain Pattern Surface | repo-verified | - | - | External auth handshake. |
|
||||
| UI-080 | `BreakGlassRecovery` page class | file discovery | Break-glass Recovery | Support | admin/internal | hidden/unregistered in provider list | privileged use only | Support / Diagnostics | Utility / Internal | Manual Review Required | plausible-existing | - | - | File exists; no confirmed route in current route list. |
|
||||
| UI-081 | `/localization/context`, `/localization/override`, `/users/me/locale-preference` | controllers | Localization Utility | Utility | user/session | route exists | authenticated for preference | Utility / Internal | Settings / Admin | Design-System Cleanup Surface | repo-verified | - | - | API/utility endpoints, not product pages. |
|
||||
| UI-082 | `/` | route/view | Welcome | Public | public | reachable | none | Auth / Access | Utility / Internal | Design-System Cleanup Surface | repo-verified | - | - | Public Laravel welcome-style route; not admin product surface. |
|
||||
| UI-083 | `/auth/entra/redirect` and `/callback` | controller | Entra Login Flow | Auth/access | auth | route exists | external auth | Auth / Access | Provider / Integration | Domain Pattern Surface | repo-verified | - | - | External auth flow. |
|
||||
| UI-084 | `/admin/local/smoke-login`, `/admin/local/backup-health-browser-fixture-login` | local routes | Local Smoke Login | Utility | local/testing | reachable in local | local/testing only | Utility / Internal | Auth / Access | Internal / Deprecated / Hidden | repo-verified | - | - | Browser fixture utility; not product UI. |
|
||||
| UI-085 | `/system` | System panel | System Dashboard | Platform/system | platform | route exists | platform guard + capability | Overview / Dashboard | Support / Diagnostics | Strategic Surface | repo-verified | - | - | Platform control tower landing. |
|
||||
| UI-086 | `/system/login` | System auth page | System Login | Platform/system | platform | route exists | platform guard | Auth / Access | Utility / Internal | Design-System Cleanup Surface | repo-verified | - | - | Separate platform guard/session. |
|
||||
| UI-087 | `/system/directory/tenants` | System page | System Tenant Directory | Platform/system | platform | route exists | platform capability | Settings / Admin | Support / Diagnostics | Domain Pattern Surface | repo-verified | - | - | Platform directory; terminology must stay provider-bound. |
|
||||
| UI-088 | `/system/directory/tenants/{tenant}` | System page | System Tenant Detail | Platform/system | platform record | route exists | platform capability | Settings / Admin | Support / Diagnostics | Domain Pattern Surface | repo-verified | - | - | Dynamic platform detail route. |
|
||||
| UI-089 | `/system/directory/workspaces` | System page | System Workspace Directory | Platform/system | platform | route exists | platform capability | Settings / Admin | Support / Diagnostics | Domain Pattern Surface | repo-verified | - | - | Platform workspace directory. |
|
||||
| UI-090 | `/system/directory/workspaces/{workspace}` | System page | System Workspace Detail | Platform/system | platform record | route exists | platform capability | Settings / Admin | Support / Diagnostics | Domain Pattern Surface | repo-verified | - | - | Dynamic platform detail route. |
|
||||
| UI-091 | `/system/ops/controls` | System page | Operational Controls | Platform/system | platform | route exists | platform capability | Support / Diagnostics | Operations / Monitoring | Strategic Surface | repo-verified | - | - | High-impact platform controls. |
|
||||
| UI-092 | `/system/ops/failures` | System page | Failed Operations | Platform/system | platform | route exists | platform capability | Operations / Monitoring | Support / Diagnostics | Domain Pattern Surface | repo-verified | - | - | Platform failure triage. |
|
||||
| UI-093 | `/system/ops/runbooks` | System page | Runbooks | Platform/system | platform | route exists | platform capability | Support / Diagnostics | Utility / Internal | Domain Pattern Surface | repo-verified | - | - | Internal runbook surface. |
|
||||
| UI-094 | `/system/ops/runs` | System page | System Operations | Platform/system | platform | route exists | platform capability | Operations / Monitoring | Support / Diagnostics | Strategic Surface | repo-verified | - | - | Platform-wide operation monitor. |
|
||||
| UI-095 | `/system/ops/runs/{run}` | System page | System Operation Detail | Platform/system | platform record | route exists | platform capability | Operations / Monitoring | Evidence / Audit | Strategic Surface | repo-verified | - | - | Platform run detail with controls. |
|
||||
| UI-096 | `/system/ops/stuck` | System page | Stuck Operations | Platform/system | platform | route exists | platform capability | Operations / Monitoring | Support / Diagnostics | Domain Pattern Surface | repo-verified | - | - | Platform stalled-run triage. |
|
||||
| UI-097 | `/system/repair-workspace-owners` | System page | Repair Workspace Owners | Platform/system | platform | route exists | platform capability | Support / Diagnostics | Auth / Access | Strategic Surface | repo-verified | - | - | Break-glass repair surface; high-impact. |
|
||||
| UI-098 | `/system/security/access-logs` | System page | Access Logs | Platform/system | platform | route exists | platform capability | Evidence / Audit | Support / Diagnostics | Strategic Surface | repo-verified | - | - | Platform access audit surface. |
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 238 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 166 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 98 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 72 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 72 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 86 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 51 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 89 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 52 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 50 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 68 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 101 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 6.9 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 6.9 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 7.0 KiB |
1
docs/ui-ux-enterprise-audit/screenshots/mobile/.gitkeep
Normal file
1
docs/ui-ux-enterprise-audit/screenshots/mobile/.gitkeep
Normal file
@ -0,0 +1 @@
|
||||
|
||||
1
docs/ui-ux-enterprise-audit/screenshots/tablet/.gitkeep
Normal file
1
docs/ui-ux-enterprise-audit/screenshots/tablet/.gitkeep
Normal file
@ -0,0 +1 @@
|
||||
|
||||
56
docs/ui-ux-enterprise-audit/strategic-surfaces.md
Normal file
56
docs/ui-ux-enterprise-audit/strategic-surfaces.md
Normal file
@ -0,0 +1,56 @@
|
||||
# Strategic Surfaces
|
||||
|
||||
This list is the Spec 323 baseline of inventory rows classified as `Strategic Surface`. Priority reflects design urgency, not implementation sequencing.
|
||||
|
||||
Priority model:
|
||||
|
||||
- P0: customer/operator-critical, dangerous, audit-sensitive, or core first-read surface.
|
||||
- P1: important product surface that needs a target artifact or explicit product decision before major UI work.
|
||||
- P2: platform/internal strategic surface that can follow after customer/admin-facing P0/P1 coverage.
|
||||
|
||||
| Priority | ID | Surface | Route | Why Strategic | Current Risk | Recommended Target Artifact |
|
||||
| --- | --- | --- | --- | --- | --- | --- |
|
||||
| P0 | UI-001 | Workspace Overview | `/admin` -> `/admin/workspaces/{workspace}/overview` | First admin landing after login. | Multiple competing next actions. | Individual target mockup. |
|
||||
| P0 | UI-002 | Workspace Overview Direct | `/admin/workspaces/{workspace}/overview` | Canonical workspace shell route. | Same hierarchy risk as UI-001. | Same target as UI-001. |
|
||||
| P0 | UI-011 | Environment Dashboard | `/admin/workspaces/{workspace}/environments/{environment}` | Core environment decision page. | Status, evidence, and action priority can blur. | Individual target mockup. |
|
||||
| P0 | UI-016 | Operations | `/admin/workspaces/{workspace}/operations` | OperationRun control and observability hub. | Diagnostic events can look like governance health. | Individual target mockup plus status grammar. |
|
||||
| P0 | UI-025 | Audit Log | `/admin/audit-log` | Auditability proof surface. | Raw logs can overpower decision context. | Evidence/audit target pattern. |
|
||||
| P0 | UI-026 | Finding Exceptions Queue | `/admin/finding-exceptions/queue` | Accepted-risk work queue. | Risk acceptance can feel like routine list handling. | Individual accepted-risk target. |
|
||||
| P0 | UI-028 | Governance Inbox | `/admin/governance/inbox` | Strategic operator inbox. | Needs sharp ownership and next-action hierarchy. | Individual target mockup. |
|
||||
| P0 | UI-029 | Decision Register | `/admin/governance/decisions` | Decision/proof register. | Evidence links and decision status need clarity. | Individual target mockup. |
|
||||
| P0 | UI-034 | Finding Detail | `/admin/workspaces/{workspace}/environments/{environment}/findings/{record}` | Core triage detail. | Not browser-reviewed; ownership/close/risk actions unknown. | Individual detail mockup. |
|
||||
| P0 | UI-036 | Exception Detail | `/admin/workspaces/{workspace}/environments/{environment}/finding-exceptions/{record}` | Accepted-risk detail. | Expiry, approver, and audit trail need strong hierarchy. | Individual detail mockup. |
|
||||
| P0 | UI-038 | Customer Review Workspace | `/admin/reviews/workspace` | Customer/auditor-facing workspace. | Customer-safe language and proof context are critical. | Individual target mockup. |
|
||||
| P0 | UI-049 | Backup Schedules | `/admin/workspaces/{workspace}/environments/{environment}/backup-schedules` | Backup readiness and schedule safety. | Run/retry controls are high impact. | Backup pattern target. |
|
||||
| P0 | UI-051 | Backup Sets | `/admin/workspaces/{workspace}/environments/{environment}/backup-sets` | Restore-point truth and recovery evidence. | Browser blocked by capability fixture. | Individual backup set target with fixture. |
|
||||
| P0 | UI-053 | Restore Runs | `/admin/workspaces/{workspace}/environments/{environment}/restore-runs` | Restore execution history. | Browser blocked; destructive workflow context unknown. | Individual restore target with fixture. |
|
||||
| P0 | UI-054 | Restore Run Create/View | `/admin/workspaces/{workspace}/environments/{environment}/restore-runs/create` and `/view` | High-impact restore workflow. | Dry-run, confirmation, partial restore, and audit UX need proof. | Restore workflow target. |
|
||||
| P0 | UI-055 | Baseline Profiles | `/admin/baseline-profiles` | Baseline source of governance truth. | Assignment/capture/compare semantics need hierarchy. | Drift/diff target pattern. |
|
||||
| P0 | UI-061 | Baseline Compare | `/admin/workspaces/{workspace}/environments/{environment}/baseline-compare` | Environment drift decision page. | Browser blocked/404 in fixture. | Individual compare target with seeded state. |
|
||||
| P0 | UI-072 | Provider Connections | `/admin/provider-connections` | Credential and provider health surface. | Permission/connection truth must be trusted. | Individual integration target. |
|
||||
| P0 | UI-073 | Create Provider Connection | `/admin/provider-connections/create` | Consent/credential setup. | Least-privilege, scopes, and handoff copy need review. | Provider onboarding target. |
|
||||
| P1 | UI-007 | Manage Workspaces | `/admin/workspaces` | Workspace administration and membership entry point. | RBAC and entitlement language not browser-reviewed. | Workspace admin target. |
|
||||
| P1 | UI-010 | Managed Environments | `/admin/workspaces/{workspace}/environments` | Environment portfolio entry point. | Needs portfolio-level status and context. | Environment portfolio target. |
|
||||
| P1 | UI-013 | Environment Access Scopes | `/admin/workspaces/{workspace}/environments/{environment}/access-scopes` | Environment RBAC surface. | Access changes need confirmation/audit treatment. | Access-control target. |
|
||||
| P1 | UI-014 | Environment Onboarding | `/admin/onboarding` | Provider/environment setup wizard. | Long workflow and provider scopes need productization. | Wizard target. |
|
||||
| P1 | UI-017 | Operation Detail | `/admin/workspaces/{workspace}/operations/{run}` | OperationRun proof and diagnostics. | Dynamic record state not reviewed. | Operation detail pattern. |
|
||||
| P1 | UI-018 | Alerts | `/admin/alerts` | Alerting entry point. | Cluster redirects to delivery list; target hierarchy unclear. | Monitoring pattern target. |
|
||||
| P1 | UI-037 | Review Register | `/admin/reviews` | Review planning and proof register. | Needs timeline and customer/auditor framing. | Review pattern target. |
|
||||
| P1 | UI-040 | Environment Review Detail | `/admin/workspaces/{workspace}/environments/{environment}/environment-reviews/{record}` | Customer/auditor review detail. | Dynamic detail not reviewed. | Review detail target. |
|
||||
| P1 | UI-042 | Review Pack Detail | `/admin/workspaces/{workspace}/environments/{environment}/review-packs/{record}` | Export/evidence artifact detail. | Export context and proof trust need review. | Review-pack target. |
|
||||
| P1 | UI-044 | Evidence Overview | `/admin/evidence/overview` | Workspace-wide evidence landing. | Not captured; evidence taxonomy unknown. | Evidence overview target. |
|
||||
| P1 | UI-046 | Evidence Snapshot Detail | `/admin/workspaces/{workspace}/environments/{environment}/evidence/{record}` | Raw/support evidence detail. | Raw data exposure risk. | Evidence detail pattern. |
|
||||
| P1 | UI-048 | Stored Report Detail | `/admin/workspaces/{workspace}/environments/{environment}/stored-reports/{record}` | Customer-readable report artifact. | Claims, freshness, and export context need review. | Stored report target. |
|
||||
| P1 | UI-052 | Backup Set Create/View | `/admin/workspaces/{workspace}/environments/{environment}/backup-sets/create` and `/view` | Backup creation and restore-point detail. | Safety and proof state not reviewed. | Backup workflow target. |
|
||||
| P1 | UI-057 | Baseline Profile Detail/Edit | `/admin/baseline-profiles/{record}` and `/edit` | Baseline capture/edit detail. | Capture/compare actions need dangerous-action treatment. | Baseline detail target. |
|
||||
| P1 | UI-058 | Baseline Compare Matrix | `/admin/baseline-profiles/{record}/compare-matrix` | Cross-baseline comparison. | Matrix hierarchy and evidence gaps unknown. | Compare matrix target. |
|
||||
| P1 | UI-063 | Inventory Coverage | `/admin/workspaces/{workspace}/environments/{environment}/inventory/inventory-coverage` | Evidence confidence gate. | Coverage truth and unknown states need target grammar. | Inventory coverage target. |
|
||||
| P1 | UI-069 | Policy Version Detail | `/admin/workspaces/{workspace}/environments/{environment}/policy-versions/{record}` | Immutable snapshot/diff proof. | Snapshot/diff detail not reviewed. | Policy version target. |
|
||||
| P1 | UI-074 | Provider Connection Detail/Edit | `/admin/provider-connections/{record}` and `/edit` | Provider health and permission detail. | Raw/diagnostic data can dominate. | Integration detail target. |
|
||||
| P1 | UI-076 | Cross Environment Compare | `/admin/cross-environment-compare` | Portfolio drift/promotion comparison. | Environment scoping and result hierarchy unknown. | Cross-environment target. |
|
||||
| P2 | UI-085 | System Dashboard | `/system` | Platform control tower. | Separate guard/capability state not reviewed. | System-plane dashboard target. |
|
||||
| P2 | UI-091 | Operational Controls | `/system/ops/controls` | Platform-wide operational control surface. | High-impact controls need confirmation grammar. | System controls pattern. |
|
||||
| P2 | UI-094 | System Operations | `/system/ops/runs` | Platform operation monitor. | System-plane status grammar not reviewed. | System operations pattern. |
|
||||
| P2 | UI-095 | System Operation Detail | `/system/ops/runs/{run}` | Platform run detail and controls. | Dynamic record state not reviewed. | System operation detail target. |
|
||||
| P2 | UI-097 | Repair Workspace Owners | `/system/repair-workspace-owners` | Break-glass ownership repair. | High-impact repair action needs strict confirmation. | Break-glass target. |
|
||||
| P2 | UI-098 | Access Logs | `/system/security/access-logs` | Platform access audit. | Access-log evidence hierarchy not reviewed. | System audit target. |
|
||||
@ -0,0 +1,34 @@
|
||||
# Design Coverage Template
|
||||
|
||||
## Summary
|
||||
|
||||
| Metric | Count | Notes |
|
||||
| --- | ---: | --- |
|
||||
| UI route/page rows | | |
|
||||
| Reviewed pages | | |
|
||||
| Desktop screenshots | | |
|
||||
| Strategic surfaces | | |
|
||||
| Domain pattern surfaces | | |
|
||||
| Design-system cleanup surfaces | | |
|
||||
| Internal/deprecated/hidden surfaces | | |
|
||||
| Manual-review / unresolved surfaces | | |
|
||||
|
||||
## Coverage By Area
|
||||
|
||||
| Area | Rows | Strategic | Domain Pattern | Cleanup | Internal/Hidden | Manual Review | Notes |
|
||||
| --- | ---: | ---: | ---: | ---: | ---: | ---: | --- |
|
||||
|
||||
## Coverage By Archetype
|
||||
|
||||
| Archetype | Rows | Primary design decision | Follow-up |
|
||||
| --- | ---: | --- | --- |
|
||||
|
||||
## Missing Or Unclear Coverage
|
||||
|
||||
| ID / Route | Reason | Required next action |
|
||||
| --- | --- | --- |
|
||||
|
||||
## Recommended Next Specs
|
||||
|
||||
| Priority | Candidate | Covers | Output |
|
||||
| --- | --- | --- | --- |
|
||||
77
docs/ui-ux-enterprise-audit/templates/page-audit-template.md
Normal file
77
docs/ui-ux-enterprise-audit/templates/page-audit-template.md
Normal file
@ -0,0 +1,77 @@
|
||||
# Page Audit Template
|
||||
|
||||
## Metadata
|
||||
|
||||
| Field | Value |
|
||||
| --- | --- |
|
||||
| Audit ID | |
|
||||
| Page / route | |
|
||||
| Source | |
|
||||
| Area | |
|
||||
| Scope | |
|
||||
| Primary archetype | |
|
||||
| Design depth | |
|
||||
| Repo truth | |
|
||||
| Screenshot | |
|
||||
| Browser status | |
|
||||
|
||||
## First Five Seconds
|
||||
|
||||
- Primary audience:
|
||||
- What the page is about:
|
||||
- Why it matters:
|
||||
- Most likely next action:
|
||||
- Ambiguity:
|
||||
|
||||
## Productization Review
|
||||
|
||||
- Decision-first:
|
||||
- Evidence-first:
|
||||
- Workspace/environment context:
|
||||
- Capability/RBAC awareness:
|
||||
- Customer/auditor safety:
|
||||
- Diagnostics/default hierarchy:
|
||||
|
||||
## Information Inventory
|
||||
|
||||
- Default-visible decision content:
|
||||
- Status/trust signals:
|
||||
- Evidence or artifact references:
|
||||
- Diagnostic/raw/support detail:
|
||||
- Empty/loading/error states:
|
||||
|
||||
## Dangerous Actions
|
||||
|
||||
- Dangerous or high-impact actions:
|
||||
- Current confirmation/evidence posture:
|
||||
- Target handling:
|
||||
|
||||
## Enterprise Readiness Scores
|
||||
|
||||
| Dimension | Score |
|
||||
| --- | ---: |
|
||||
| Information Architecture | |
|
||||
| Information Density | |
|
||||
| Target User Clarity | |
|
||||
| Sellability / Platform Feel | |
|
||||
| Progressive Disclosure | |
|
||||
| Layout & Hierarchy | |
|
||||
| Design-System Fit | |
|
||||
| Accessibility | |
|
||||
| Responsive UX | |
|
||||
| Component Quality | |
|
||||
| UX Writing | |
|
||||
| Performance Perception | |
|
||||
|
||||
## Top Issues
|
||||
|
||||
1.
|
||||
2.
|
||||
3.
|
||||
|
||||
## Target Direction
|
||||
|
||||
- Recommended target state:
|
||||
- Pattern reuse:
|
||||
- Individual mockup needed:
|
||||
- Later spec recommendation:
|
||||
@ -0,0 +1,46 @@
|
||||
# Route Inventory Template
|
||||
|
||||
| ID | Route / URL | Source | Page Name | Area | Scope | Reachability | Auth/RBAC Notes | Primary Archetype | Secondary Archetype | Design Depth | Repo Truth | Screenshot | Page Report | Notes |
|
||||
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
|
||||
| UI-000 | `/admin/example` | route:list + class | Example | Example | workspace | reachable | workspace member | Overview / Dashboard | - | Domain Pattern Surface | repo-verified | - | - | |
|
||||
|
||||
## Classification Options
|
||||
|
||||
Primary archetype options:
|
||||
|
||||
- Overview / Dashboard
|
||||
- Findings / Inbox
|
||||
- Evidence / Audit
|
||||
- Backup / Restore
|
||||
- Drift / Diff
|
||||
- Inventory
|
||||
- Reviews
|
||||
- Exceptions / Accepted Risk
|
||||
- Operations / Monitoring
|
||||
- Provider / Integration
|
||||
- Workspace / Tenant Context
|
||||
- Settings / Admin
|
||||
- Support / Diagnostics
|
||||
- Commercial / Entitlements
|
||||
- Customer Workspace
|
||||
- Auth / Access
|
||||
- Utility / Internal
|
||||
- Deprecated / Legacy
|
||||
- Manual Review Required
|
||||
|
||||
Design depth options:
|
||||
|
||||
- Strategic Surface
|
||||
- Domain Pattern Surface
|
||||
- Design-System Cleanup Surface
|
||||
- Internal / Deprecated / Hidden
|
||||
- Manual Review Required
|
||||
|
||||
Repo-truth options:
|
||||
|
||||
- repo-verified
|
||||
- plausible-existing
|
||||
- foundation-only
|
||||
- spec-only
|
||||
- conceptual-future-state
|
||||
- unknown
|
||||
49
docs/ui-ux-enterprise-audit/unresolved-pages.md
Normal file
49
docs/ui-ux-enterprise-audit/unresolved-pages.md
Normal file
@ -0,0 +1,49 @@
|
||||
# Unresolved Pages
|
||||
|
||||
This ledger records high-priority pages that Spec 323 could not fully evaluate in the browser or that need manual review before product-readiness claims. Entries here are not target mockups and do not imply the current UI is approved.
|
||||
|
||||
Summary:
|
||||
|
||||
- High-priority unresolved/manual-review entries: 32.
|
||||
- Capability/fixture blockers with desktop evidence: UI-051, UI-053, UI-061.
|
||||
- Strategic routes not browser-captured in this bounded pass: 28.
|
||||
- Hidden/file-discovered manual-review surface: UI-080.
|
||||
|
||||
| ID | Page | Blocker / Reason | Needed Evidence | Next Action |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| UI-007 | Manage Workspaces | Strategic RBAC/admin page was not captured in browser pass. | Workspace admin fixture with member/owner states. | Include in settings/admin target pass. |
|
||||
| UI-010 | Managed Environments | Environment portfolio route exists but was not captured. | Workspace with multiple environment states. | Include in app-shell/environment target pass. |
|
||||
| UI-013 | Environment Access Scopes | RBAC-sensitive environment route was not captured. | Owner/manager fixture with editable and read-only states. | Include in access-control target pass. |
|
||||
| UI-014 | Environment Onboarding | Provider setup wizard route exists but was not captured. | Draft/onboarding fixture with consent and permission states. | Include in provider onboarding target pass. |
|
||||
| UI-017 | Operation Detail | Dynamic operation record route requires a run fixture. | OperationRun records covering success, failure, running, retryable states. | Add operation detail report later. |
|
||||
| UI-034 | Finding Detail | Dynamic finding detail requires seeded finding state. | Finding records with owner, severity, exception, and close state. | Add strategic finding detail mockup. |
|
||||
| UI-036 | Exception Detail | Accepted-risk detail requires seeded exception record. | Pending, approved, expired, rejected exception states. | Add accepted-risk detail mockup. |
|
||||
| UI-040 | Environment Review Detail | Dynamic customer/auditor review record was not captured. | Review records with evidence/progress states. | Add review detail report later. |
|
||||
| UI-042 | Review Pack Detail | Export/evidence artifact detail requires seeded review pack. | Review pack with files, freshness, and download state. | Add review-pack target artifact. |
|
||||
| UI-044 | Evidence Overview | Workspace evidence landing was not captured. | Workspace with evidence sources, gaps, and stale states. | Add evidence overview report. |
|
||||
| UI-046 | Evidence Snapshot Detail | Dynamic raw/support evidence detail requires snapshot record. | Snapshot with normalized summary and raw payload. | Add progressive-disclosure review. |
|
||||
| UI-048 | Stored Report Detail | Dynamic report artifact requires stored report record. | Stored report with customer-facing summary and export metadata. | Add stored-report target pass. |
|
||||
| UI-049 | Backup Schedules | Strategic backup schedule page was not captured. | Environment with active, paused, failing, and never-run schedules. | Include in backup/restore safety spec. |
|
||||
| UI-051 | Backup Sets | Browser returned Forbidden for the local fixture. | Capability-backed environment with backup-set records. | Re-test with seeded capability; screenshot exists as blocker evidence. |
|
||||
| UI-052 | Backup Set Create/View | Backup workflow/detail route needs capability and backup data. | Create form, backup-set view, partial/failure states. | Add backup workflow target. |
|
||||
| UI-053 | Restore Runs | Browser returned Forbidden for the local fixture. | Capability-backed environment with restore-run records. | Re-test with seeded capability; screenshot exists as blocker evidence. |
|
||||
| UI-054 | Restore Run Create/View | Restore create/view route needs capability and restore data. | Dry-run, validation, partial restore, conflict, and confirmation states. | Add restore workflow target. |
|
||||
| UI-057 | Baseline Profile Detail/Edit | Baseline record detail/edit was not captured. | Baseline profile with assigned environments and compare/capture state. | Add baseline detail target. |
|
||||
| UI-058 | Baseline Compare Matrix | Dynamic compare matrix was not captured. | Baseline compare record with pass/fail/unknown dimensions. | Add compare matrix target. |
|
||||
| UI-061 | Baseline Compare | Tested environment variants returned 404 despite route-list presence. | Valid environment/baseline assignment fixture. | Reconcile route binding/fixture and re-capture. |
|
||||
| UI-063 | Inventory Coverage | Coverage truth page was not captured. | Environment with coverage, unknown, stale, and disconnected provider states. | Add inventory coverage target. |
|
||||
| UI-069 | Policy Version Detail | Dynamic policy version detail was not captured. | Policy version with snapshot and diff/evidence metadata. | Add policy version detail report. |
|
||||
| UI-073 | Create Provider Connection | Credential/consent create flow was not captured. | Provider setup fixture and consent preconditions. | Include in provider onboarding target. |
|
||||
| UI-074 | Provider Connection Detail/Edit | Dynamic provider connection detail/edit was not captured. | Connected, expired, failed, and missing-permission states. | Add provider detail target. |
|
||||
| UI-076 | Cross Environment Compare | Portfolio compare page was not captured. | Workspace with multiple comparable environments. | Add cross-environment compare target. |
|
||||
| UI-080 | Break-glass Recovery | Page class exists but no confirmed route in current route list. | Confirm registration, route, guard, and intended audience. | Manual review before product claims. |
|
||||
| UI-085 | System Dashboard | System panel requires separate guard/capability fixture. | Platform/system admin session. | Include in system-plane target pass. |
|
||||
| UI-091 | Operational Controls | System control surface was not captured. | Platform admin fixture with allowed and denied controls. | Add confirmation/audit review. |
|
||||
| UI-094 | System Operations | System operation monitor was not captured. | Platform operation records across statuses. | Add system operations report. |
|
||||
| UI-095 | System Operation Detail | Dynamic system operation detail requires run fixture. | Platform run detail with retry/cancel controls. | Add system operation detail review. |
|
||||
| UI-097 | Repair Workspace Owners | Break-glass repair page was not captured. | Platform admin fixture and repair scenarios. | Add break-glass target. |
|
||||
| UI-098 | Access Logs | System access-log surface was not captured. | Platform access records with filters and export state. | Add system audit review. |
|
||||
|
||||
## Deferred Responsive Evidence
|
||||
|
||||
Tablet and mobile screenshots were not captured in Spec 323. Later target specs should add responsive screenshots for the app shell, workspace overview, environment dashboard, governance inbox, customer review workspace, operations, evidence, backup/restore, and high-risk forms.
|
||||
104
scripts/check-ui-productization-coverage
Executable file
104
scripts/check-ui-productization-coverage
Executable file
@ -0,0 +1,104 @@
|
||||
#!/usr/bin/env bash
|
||||
|
||||
set -euo pipefail
|
||||
|
||||
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||||
ROOT_DIR="$(cd "${SCRIPT_DIR}/.." && pwd)"
|
||||
BASE_REF="${1:-${GITHUB_BASE_REF:-${GITEA_BASE_REF:-}}}"
|
||||
|
||||
if [[ -z "${BASE_REF}" ]]; then
|
||||
if git -C "${ROOT_DIR}" rev-parse --verify origin/dev >/dev/null 2>&1; then
|
||||
BASE_REF="origin/dev"
|
||||
elif git -C "${ROOT_DIR}" rev-parse --verify HEAD~1 >/dev/null 2>&1; then
|
||||
BASE_REF="HEAD~1"
|
||||
else
|
||||
echo "UI/Productization Coverage guard: no base ref supplied and no fallback ref exists." >&2
|
||||
echo "Usage: scripts/check-ui-productization-coverage <base-ref>" >&2
|
||||
exit 2
|
||||
fi
|
||||
fi
|
||||
|
||||
if ! git -C "${ROOT_DIR}" rev-parse --verify "${BASE_REF}^{commit}" >/dev/null 2>&1; then
|
||||
echo "UI/Productization Coverage guard: base ref '${BASE_REF}' is not available." >&2
|
||||
echo "Fetch the target branch first or pass an available commit/ref." >&2
|
||||
exit 2
|
||||
fi
|
||||
|
||||
if BASE_COMMIT="$(git -C "${ROOT_DIR}" merge-base "${BASE_REF}" HEAD 2>/dev/null)"; then
|
||||
CHANGED_FILES="$(git -C "${ROOT_DIR}" diff --name-only --diff-filter=ACMRT "${BASE_COMMIT}...HEAD")"
|
||||
else
|
||||
CHANGED_FILES="$(git -C "${ROOT_DIR}" diff --name-only --diff-filter=ACMRT "${BASE_REF}..HEAD")"
|
||||
fi
|
||||
|
||||
ui_changes=()
|
||||
coverage_changes=()
|
||||
spec_no_impact_files=()
|
||||
|
||||
while IFS= read -r file; do
|
||||
[[ -z "${file}" ]] && continue
|
||||
|
||||
case "${file}" in
|
||||
apps/platform/app/Filament/*|apps/platform/app/Support/Navigation/*|apps/platform/app/Providers/Filament/*|apps/platform/resources/views/*|apps/platform/app/Livewire/*|apps/platform/routes/*)
|
||||
ui_changes+=("${file}")
|
||||
;;
|
||||
esac
|
||||
|
||||
case "${file}" in
|
||||
docs/ui-ux-enterprise-audit/route-inventory.md|\
|
||||
docs/ui-ux-enterprise-audit/design-coverage-matrix.md|\
|
||||
docs/ui-ux-enterprise-audit/grouped-follow-up-candidates.md|\
|
||||
docs/ui-ux-enterprise-audit/strategic-surfaces.md|\
|
||||
docs/ui-ux-enterprise-audit/unresolved-pages.md|\
|
||||
docs/ui-ux-enterprise-audit/page-reports/*)
|
||||
coverage_changes+=("${file}")
|
||||
;;
|
||||
esac
|
||||
|
||||
if [[ "${file}" == specs/*/spec.md && -f "${ROOT_DIR}/${file}" ]] \
|
||||
&& grep -Eq '^- \[[xX]\] No UI surface impact[[:space:]]*$' "${ROOT_DIR}/${file}"; then
|
||||
spec_no_impact_files+=("${file}")
|
||||
fi
|
||||
done <<< "${CHANGED_FILES}"
|
||||
|
||||
if [[ ${#ui_changes[@]} -eq 0 ]]; then
|
||||
echo "UI/Productization Coverage guard passed: no guarded UI surface paths changed."
|
||||
exit 0
|
||||
fi
|
||||
|
||||
if [[ ${#coverage_changes[@]} -gt 0 || ${#spec_no_impact_files[@]} -gt 0 ]]; then
|
||||
echo "UI/Productization Coverage guard passed."
|
||||
echo "Guarded UI surface changes:"
|
||||
printf ' - %s\n' "${ui_changes[@]}"
|
||||
|
||||
if [[ ${#coverage_changes[@]} -gt 0 ]]; then
|
||||
echo "Coverage artifacts changed:"
|
||||
printf ' - %s\n' "${coverage_changes[@]}"
|
||||
fi
|
||||
|
||||
if [[ ${#spec_no_impact_files[@]} -gt 0 ]]; then
|
||||
echo "No-impact decision found in:"
|
||||
printf ' - %s\n' "${spec_no_impact_files[@]}"
|
||||
fi
|
||||
|
||||
exit 0
|
||||
fi
|
||||
|
||||
cat >&2 <<'EOF'
|
||||
UI/Productization Coverage guard failed.
|
||||
|
||||
Guarded UI surface files changed, but no UI coverage artifact changed and no
|
||||
active spec contains:
|
||||
|
||||
- [x] No UI surface impact
|
||||
|
||||
Required: update at least one relevant artifact under
|
||||
docs/ui-ux-enterprise-audit/ (route inventory, design coverage matrix, page
|
||||
reports, grouped follow-up candidates, strategic surfaces, or unresolved
|
||||
pages), or document the checked no-impact decision in the active spec.
|
||||
|
||||
Guarded UI surface changes:
|
||||
EOF
|
||||
|
||||
printf ' - %s\n' "${ui_changes[@]}" >&2
|
||||
|
||||
exit 1
|
||||
@ -0,0 +1,82 @@
|
||||
# Specification Quality Checklist: Tenantial Enterprise UI Audit Foundation
|
||||
|
||||
**Purpose**: Validate specification completeness, preparation quality, and readiness before implementation.
|
||||
**Created**: 2026-05-17
|
||||
**Feature**: `specs/323-tenantial-enterprise-ui-audit-foundation/spec.md`
|
||||
|
||||
## Candidate Selection Gate
|
||||
|
||||
- [x] Explicit user-provided Spec 323 request was selected as the source of truth for this preparation pass.
|
||||
- [x] The additional user requirement that 323 becomes an ongoing Design Coverage Gate baseline is included.
|
||||
- [x] Completed-spec guardrail checked that no existing `specs/323-*` package or `323-*` branch was present before generation.
|
||||
- [x] Specs 318, 319, 320, 321, and 322 were treated as dependency/historical context and not rewritten.
|
||||
- [x] Roadmap/spec-candidate queue was reviewed; active auto-prep queue is empty, so this package proceeds only because the user directly supplied/promoted Spec 323.
|
||||
- [x] Close alternatives were deferred to Specs 324, 325, 326, and 327.
|
||||
- [x] The selected slice is docs-first UI audit foundation plus ongoing registry gate only.
|
||||
|
||||
## Content Quality
|
||||
|
||||
- [x] Problem statement is product-visible and tied to route/page design-coverage debt.
|
||||
- [x] User value is clear: every reachable page receives a design decision or an explicit unresolved/internal/deprecated marker.
|
||||
- [x] Scope is bounded to audit docs, screenshots, page reports, matrix, follow-up grouping, registry gate, Spec Kit process templates/prompts, PR template, and PR guard script.
|
||||
- [x] No runtime redesign or application implementation is included in preparation artifacts.
|
||||
- [x] No migration, seeder, package, env var, queue, scheduler, storage, route, auth, runtime deployment, or deployment asset change is planned.
|
||||
- [x] No unresolved `[NEEDS CLARIFICATION]` markers remain.
|
||||
- [x] Mandatory Spec Candidate Check is complete.
|
||||
- [x] Spec includes explicit non-goals and stop conditions.
|
||||
|
||||
## Requirement Completeness
|
||||
|
||||
- [x] Functional requirements are testable and unambiguous.
|
||||
- [x] Requirements cover audit structure, route inventory, screenshots, page reports, coverage matrix, strategic surfaces, grouped follow-ups, unresolved pages, dangerous actions, customer-safe review, context ambiguity, misleading status, ongoing gate, Constitution principle, Spec Kit templates, implementation prompts, PR template, and PR guard script.
|
||||
- [x] Non-functional requirements cover repo truth, Markdown stability, screenshot naming, bounded responsive review, no runtime frameworking, and validation.
|
||||
- [x] Success criteria are measurable by artifact existence, counts, links, and validation result.
|
||||
- [x] User stories include independent test descriptions and acceptance scenarios.
|
||||
- [x] Edge cases cover auth blocks, seeded-data needs, provider connection needs, redirect loops, runtime errors, hidden routes, legacy ambiguity, and screenshot blockers.
|
||||
- [x] Dependencies and assumptions are identified.
|
||||
|
||||
## Plan Quality
|
||||
|
||||
- [x] Laravel, Filament, Livewire, Pest, PostgreSQL, Sail, and docs/browser-audit context is recorded.
|
||||
- [x] Livewire v4.0+ compliance is explicitly noted through Livewire 4.1.4.
|
||||
- [x] Laravel 12 panel provider location remains `apps/platform/bootstrap/providers.php`.
|
||||
- [x] Global search impact is assessed as unchanged because no Resource code changes are planned.
|
||||
- [x] Destructive/high-impact action handling is audit-only and does not change action behavior.
|
||||
- [x] Asset strategy is assessed as no new Filament assets/no new `filament:assets` step.
|
||||
- [x] Existing repo seams and discovery paths are named.
|
||||
- [x] Browser audit/screenshot plan is concrete and bounded.
|
||||
- [x] Test governance classifies the change as Markdown/browser-audit only.
|
||||
|
||||
## Task Quality
|
||||
|
||||
- [x] Tasks are ordered from guardrails through structure, discovery, browser screenshots, reports, matrix, gate documentation, and validation.
|
||||
- [x] Task IDs follow the required checkbox format.
|
||||
- [x] File paths are concrete where repo surfaces and audit artifacts are known.
|
||||
- [x] Tasks include explicit route discovery and file-based discovery steps.
|
||||
- [x] Tasks include the ongoing Design Coverage Gate, later UI spec DoD, Spec Kit template updates, agent prompt guardrail, PR template checkbox, and CI/review guard.
|
||||
- [x] Tasks include validation and final reporting obligations.
|
||||
- [x] Non-goals and stop conditions prevent runtime implementation.
|
||||
|
||||
## Constitution / Repo Alignment
|
||||
|
||||
- [x] Workspace/environment/tenant context is audited but not changed.
|
||||
- [x] RBAC, dangerous actions, and customer-safe exposure are reviewed but not changed.
|
||||
- [x] Proportionality review covers docs-only classification ownership cost.
|
||||
- [x] No runtime taxonomy, enum, persisted entity, or UI framework is introduced.
|
||||
- [x] Test governance names no-runtime-impact, UI/Productization Coverage guard validation, and no full-suite requirement.
|
||||
- [x] Filament v5 / Livewire v4 compliance is explicitly addressed.
|
||||
- [x] Provider-boundary terminology is flagged as audit concern only, not changed.
|
||||
|
||||
## Preparation Analysis Outcome
|
||||
|
||||
- [x] Preparation artifacts are internally consistent after manual `/speckit.analyze`-style review.
|
||||
- [x] Every functional requirement maps to one or more tasks.
|
||||
- [x] Every task maps to Spec 323 audit scope or stop-condition enforcement.
|
||||
- [x] No preparation issue requires application implementation.
|
||||
- [x] Candidate Selection Gate result: PASS.
|
||||
- [x] Spec Readiness Gate result: PASS for later docs/browser-audit implementation.
|
||||
|
||||
## Notes
|
||||
|
||||
- Repository has prompt/agent definitions for `speckit.tasks` and `speckit.analyze`, but no local executable Bash command for those phases. Tasks and analysis were therefore produced repo-conformantly from the templates and checked manually in this checklist.
|
||||
- Full suite is intentionally not part of preparation or later Markdown-only validation unless runtime changes are introduced, which would violate this spec's scope.
|
||||
365
specs/323-tenantial-enterprise-ui-audit-foundation/plan.md
Normal file
365
specs/323-tenantial-enterprise-ui-audit-foundation/plan.md
Normal file
@ -0,0 +1,365 @@
|
||||
# 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/<audit-id>-<page-slug>.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/<audit-id>-<page-slug>.png
|
||||
docs/ui-ux-enterprise-audit/screenshots/tablet/<audit-id>-<page-slug>.png
|
||||
docs/ui-ux-enterprise-audit/screenshots/mobile/<audit-id>-<page-slug>.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.
|
||||
715
specs/323-tenantial-enterprise-ui-audit-foundation/spec.md
Normal file
715
specs/323-tenantial-enterprise-ui-audit-foundation/spec.md
Normal file
@ -0,0 +1,715 @@
|
||||
# Feature Specification: Tenantial Enterprise UI Audit Foundation
|
||||
|
||||
**Feature Branch**: `323-tenantial-enterprise-ui-audit-foundation`
|
||||
**Created**: 2026-05-17
|
||||
**Status**: Draft
|
||||
**Input**: User supplied full Spec 323 draft, plus the follow-up requirement that Spec 323 becomes the ongoing Design Coverage Gate baseline for future UI features.
|
||||
**Type**: Docs-first / browser-audit / productization inventory / UI Design Registry baseline
|
||||
**Runtime Posture**: Read-only audit first. No runtime UI redesign, feature implementation, route behavior change, authorization change, schema change, or business-logic change.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Spec 318: Admin Surface Scope and Shell Context Audit
|
||||
- Spec 319: Environment-Owned Surface Routing and Shell Context Contract
|
||||
- Spec 320: Workspace-Owned Analysis Surface Registration and Shell Cutover
|
||||
- Spec 321: Alerts / Audit Log Environment Filter Contract Decision
|
||||
- Spec 322: Browser No-Drift Regression Guard
|
||||
- Current `platform-dev` repo truth after Spec 322 validation
|
||||
|
||||
## Candidate Source And Guardrail Result
|
||||
|
||||
**Candidate source**: Direct user-provided manual promotion for Spec 323. The active auto-prep queue in `docs/product/spec-candidates.md` is intentionally empty, so this package proceeds only because the user supplied a complete explicit candidate.
|
||||
|
||||
**Completed-spec guardrail**: No existing `specs/323-*` package or `323-*` branch was present before generation. Specs 318 through 322 were inspected as dependency and historical context only; their completed task markers, close-out notes, validation results, screenshots, and review evidence remain untouched.
|
||||
|
||||
**Close alternatives deferred**:
|
||||
|
||||
- `324-tenantial-strategic-surface-target-mockups`: deep target mockups for P0/P1 strategic pages after the inventory exists.
|
||||
- `325-tenantial-design-system-and-state-patterns`: shared component/state cleanup rules after current UI debt is classified.
|
||||
- `326-tenantial-domain-pattern-coverage-pass`: grouped domain pattern coverage after route/page archetypes are known.
|
||||
- `327-tenantial-enterprise-ui-implementation-wave-1`: runtime UI implementation after design decisions and mockups/patterns exist.
|
||||
|
||||
## Spec Candidate Check
|
||||
|
||||
- **Problem**: Tenantial has many reachable product, admin, workspace, environment, customer, monitoring, review, provider, support, and settings surfaces, but there is no complete design-coverage registry proving every route has a product role and target-state decision.
|
||||
- **Today's failure**: Later design work can improve only obvious pages while leaving hidden or direct-route surfaces raw, technical, misclassified, customer-unsafe, or unassigned to any target mockup/pattern/design-system cleanup path.
|
||||
- **User-visible improvement**: Operators, customer reviewers, auditors, and product reviewers get a route/page inventory that says what exists, what each page is for, how product-ready it is, and what design treatment it needs next.
|
||||
- **Smallest enterprise-capable version**: Create a docs-only audit structure; discover routes and page classes; capture feasible desktop screenshots for strategic/domain surfaces; classify every discovered page into archetype, design depth, repo truth, and coverage decision; record unresolved pages; and establish the ongoing Design Coverage Gate.
|
||||
- **Explicit non-goals**: No runtime redesign, no Blade/Filament/Livewire edits, no route rewrites, no permissions changes, no migrations, no feature creation, no high-fidelity mockups for every page, no per-page follow-up spec explosion, no product claims not backed by repo truth.
|
||||
- **Permanent complexity imported**: A maintained documentation registry, page archetype labels, design-depth labels, repo-truth labels, page report templates, screenshot artifacts, coverage-matrix updates, and an ongoing feature DoD for UI coverage. No runtime enum, database, service, or UI framework is introduced.
|
||||
- **Why now**: Specs 318 through 322 stabilized route/shell/context correctness. The next bottleneck is productization coverage: every reachable page needs a design decision before strategic mockups or implementation waves start.
|
||||
- **Why not local**: A local audit of one page or domain would miss hidden/direct routes and would not create the durable gate that prevents future UI debt.
|
||||
- **Approval class**: Core Enterprise
|
||||
- **Red flags triggered**: Foundation terminology and classification system. Defense: the classification is docs-only audit metadata with no runtime semantic layer, and it directly prevents customer-facing and operator-facing trust gaps.
|
||||
- **Score**: Nutzen 2 | Dringlichkeit 2 | Scope 2 | Komplexitaet 1 | Produktnaehe 2 | Wiederverwendung 2 | **Gesamt: 11/12**
|
||||
- **Decision**: approve
|
||||
|
||||
## Summary
|
||||
|
||||
Establish the first Tenantial Enterprise UI/UX Audit foundation.
|
||||
|
||||
This spec discovers the reachable product UI surface, captures screenshots where feasible, classifies every page into a product/page archetype, evaluates each page against Tenantial enterprise-product expectations, and creates a design-coverage inventory that drives later mockup, pattern, and implementation specs.
|
||||
|
||||
This is not a redesign implementation spec.
|
||||
|
||||
The goal is to answer, repo-based:
|
||||
|
||||
- Which pages/routes currently exist?
|
||||
- Which pages are reachable in normal workspace, environment, customer, and operator flows?
|
||||
- Which pages are strategic product surfaces?
|
||||
- Which pages are utility/admin/supporting surfaces?
|
||||
- Which pages feel too technical, admin-like, or implementation-driven?
|
||||
- Which pages need individual target mockups later?
|
||||
- Which pages can be covered by shared page patterns later?
|
||||
- Which pages are deprecated, hidden, internal-only, or require manual review?
|
||||
|
||||
Spec 323 also establishes the ongoing UI Design Registry rule: future UI-relevant specs must not create reachable unclassified page debt.
|
||||
|
||||
## Product Context
|
||||
|
||||
Tenantial/TenantPilot is moving from a technically strong governance/admin product toward a sellable Enterprise SaaS platform experience.
|
||||
|
||||
The repo already contains strong foundations around:
|
||||
|
||||
- OperationRun truth
|
||||
- Evidence
|
||||
- Reviews
|
||||
- Review Packs
|
||||
- Drift findings
|
||||
- Restore safety
|
||||
- Provider health
|
||||
- Workspace entitlements
|
||||
- Capability-first RBAC
|
||||
- Audit foundations
|
||||
- Supportability
|
||||
- Customer health
|
||||
- Operational controls
|
||||
|
||||
The current bottleneck is not only backend capability. The larger productization gap is whether users can understand, trust, consume, and act on those capabilities through calm, decision-first, customer-safe surfaces.
|
||||
|
||||
## Problem Statement
|
||||
|
||||
The product has accumulated many pages, panels, routes, resources, dashboards, detail pages, settings surfaces, and operational views. Some likely already feel product-shaped. Others may still feel like raw Filament/admin resources, technical diagnostics, implementation artifacts, or internal tooling exposed as product UI.
|
||||
|
||||
Without a full route/page inventory, later design work risks:
|
||||
|
||||
- improving only the obvious pages
|
||||
- missing hidden but reachable pages
|
||||
- over-designing small utility pages
|
||||
- creating too many isolated mockups
|
||||
- creating inconsistent follow-up specs
|
||||
- redesigning pages without knowing their user, purpose, or product role
|
||||
- implementing brand styling without fixing information architecture
|
||||
|
||||
## Objective
|
||||
|
||||
Create a complete Tenantial Enterprise UI Audit Foundation that:
|
||||
|
||||
1. Discovers all relevant UI pages/routes.
|
||||
2. Captures current-state screenshots where feasible.
|
||||
3. Classifies every page into a page archetype.
|
||||
4. Assigns every page a design depth.
|
||||
5. Evaluates every page using a common enterprise readiness rubric.
|
||||
6. Identifies strategic surfaces requiring individual target mockups.
|
||||
7. Identifies domain pages that should use shared patterns.
|
||||
8. Identifies small utility/admin pages that should use design-system cleanup rules.
|
||||
9. Produces a master design-coverage inventory.
|
||||
10. Creates a backlog of later specs without implementing UI changes.
|
||||
11. Establishes an ongoing Design Coverage Gate for future UI-relevant specs.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
This spec must not:
|
||||
|
||||
- redesign runtime pages
|
||||
- change Blade views
|
||||
- change Filament resources
|
||||
- change Livewire components
|
||||
- change navigation behavior
|
||||
- change route behavior
|
||||
- change authorization behavior
|
||||
- change business logic
|
||||
- change database schema
|
||||
- introduce new product capabilities
|
||||
- create high-fidelity SVG mockups for every page
|
||||
- create individual follow-up specs for every small page
|
||||
- rename product concepts in runtime
|
||||
- remove pages
|
||||
- modify tenant/workspace/environment context behavior
|
||||
- run broad refactors
|
||||
- run destructive commands
|
||||
|
||||
Mockups, design-system work, and implementation changes belong to later specs.
|
||||
|
||||
## Core Principle
|
||||
|
||||
The full product environment is considered designed only when every discovered route is either:
|
||||
|
||||
1. covered by an individual target experience mockup,
|
||||
2. mapped to an approved domain-level page pattern,
|
||||
3. mapped to a reusable design-system/component pattern,
|
||||
4. or explicitly marked as deprecated, hidden, internal-only, out of scope, or requiring manual review.
|
||||
|
||||
No reachable page may remain unclassified, undesigned, or without a recommended target state.
|
||||
|
||||
Spec 323 creates the first inventory and classification layer for this rule.
|
||||
|
||||
## Ongoing Feature Design Coverage Gate
|
||||
|
||||
After Spec 323, every new feature that introduces or changes a reachable UI surface must update the UI/UX audit coverage artifacts.
|
||||
|
||||
A feature is not UI-complete if it adds a reachable page, action, modal, drawer, form, table, state, or customer-facing surface without a design coverage decision.
|
||||
|
||||
Required for every new UI surface:
|
||||
|
||||
- Add or update entry in `docs/ui-ux-enterprise-audit/route-inventory.md`
|
||||
- Assign primary page archetype
|
||||
- Assign design depth
|
||||
- Assign repo-truth level
|
||||
- Link to existing domain pattern or component pattern
|
||||
- Add screenshot if the surface is strategic or materially different
|
||||
- Add page report if the surface introduces a new product decision, workflow, dangerous action, or customer-facing experience
|
||||
- Add to `docs/ui-ux-enterprise-audit/unresolved-pages.md` if the surface cannot be reviewed yet
|
||||
- Update `docs/ui-ux-enterprise-audit/design-coverage-matrix.md`
|
||||
|
||||
New features must not create unclassified UI debt.
|
||||
|
||||
## UI/UX Coverage Requirements For Later Specs
|
||||
|
||||
Every future UI-relevant spec should carry this standard DoD:
|
||||
|
||||
- [ ] Route/page is added to the UI audit inventory.
|
||||
- [ ] Page archetype is assigned.
|
||||
- [ ] Design depth is assigned.
|
||||
- [ ] Existing pattern is reused or a new pattern need is documented.
|
||||
- [ ] Strategic surfaces have screenshot or target mockup follow-up.
|
||||
- [ ] Dangerous actions have impact/confirmation/evidence review.
|
||||
- [ ] Customer-facing surfaces are checked for customer-safe language and data exposure.
|
||||
- [ ] No new page remains unclassified.
|
||||
|
||||
Not every new feature needs a new mockup:
|
||||
|
||||
- New strategic page -> individual target image/mockup/follow-up UI spec.
|
||||
- New normal domain page -> existing domain pattern.
|
||||
- New small admin/utility page -> design-system cleanup rules.
|
||||
- New modal/drawer/action -> component/state pattern review.
|
||||
- Experimental or internal feature -> internal/manual-review marker.
|
||||
|
||||
## Future Feature Coverage Guardrail
|
||||
|
||||
Spec 323 establishes the UI/Productization Coverage baseline.
|
||||
|
||||
After this spec, every future feature spec that adds, removes, renames, or materially changes a reachable UI surface must update or explicitly acknowledge the UI coverage artifacts.
|
||||
|
||||
A UI surface includes:
|
||||
|
||||
- page
|
||||
- route
|
||||
- navigation item
|
||||
- table
|
||||
- form
|
||||
- modal
|
||||
- drawer
|
||||
- wizard step
|
||||
- action
|
||||
- dangerous action confirmation
|
||||
- empty/loading/error state
|
||||
- customer-facing view
|
||||
- operator workflow surface
|
||||
|
||||
Required decision for every affected surface:
|
||||
|
||||
- page archetype
|
||||
- design depth
|
||||
- repo-truth level
|
||||
- target pattern or mockup need
|
||||
- customer-safe review need
|
||||
- dangerous-action review need
|
||||
|
||||
A feature must not be considered complete if it creates unclassified UI debt.
|
||||
|
||||
## Ongoing DoD Addition for Future Specs
|
||||
|
||||
If a spec changes reachable UI:
|
||||
|
||||
- [ ] UI Surface Impact section completed.
|
||||
- [ ] Route/page inventory updated or no-impact rationale documented.
|
||||
- [ ] Design coverage matrix updated where needed.
|
||||
- [ ] Existing pattern reused or missing pattern documented.
|
||||
- [ ] Dangerous actions reviewed where applicable.
|
||||
- [ ] Customer-facing surfaces reviewed where applicable.
|
||||
- [ ] No new reachable UI surface remains unclassified.
|
||||
|
||||
## Tenantial Brand / UX Direction
|
||||
|
||||
Use the Tenantial brand and UX context as the product lens.
|
||||
|
||||
Tenantial should feel:
|
||||
|
||||
- calm
|
||||
- precise
|
||||
- premium
|
||||
- operator-first
|
||||
- evidence-first
|
||||
- enterprise-grade
|
||||
- workspace-aware
|
||||
- trustworthy
|
||||
- controlled
|
||||
|
||||
Tenantial must not feel like:
|
||||
|
||||
- generic blue SaaS
|
||||
- playful startup UI
|
||||
- raw admin console
|
||||
- debug dashboard
|
||||
- helpdesk clone
|
||||
- Microsoft admin center mirror
|
||||
- noisy cybersecurity dashboard
|
||||
- overconfident compliance marketing
|
||||
|
||||
For every page, answer:
|
||||
|
||||
> Can a non-technical decision-maker, customer stakeholder, auditor, or operator understand within five seconds what this page is about, why it matters, and what should happen next?
|
||||
|
||||
## Product UX Rules
|
||||
|
||||
Every audited page must be evaluated against these principles:
|
||||
|
||||
- decision-first
|
||||
- evidence-first
|
||||
- source-of-truth first
|
||||
- workspace-first
|
||||
- capability-aware
|
||||
- RBAC-aware
|
||||
- progressive disclosure
|
||||
- no misleading status
|
||||
- clear next action
|
||||
- customer-safe where applicable
|
||||
- diagnostics second
|
||||
- evidence third
|
||||
- technical depth available but not dominant
|
||||
|
||||
## Required Truth-Layer Distinctions
|
||||
|
||||
The audit must distinguish between these truth layers:
|
||||
|
||||
| Truth Layer | Question | Examples |
|
||||
| --- | --- | --- |
|
||||
| Execution Truth | What actually ran? | OperationRun state, timestamps, actor, failure reason, run result |
|
||||
| Artifact Truth | What object/configuration/report exists? | baseline profile, backup snapshot, stored report, evidence artifact |
|
||||
| Backup Truth | What was backed up, when, and from which source? | restore point, backup version, object coverage, scope |
|
||||
| Recovery Evidence | What was restored, from what source, by whom, and with what result? | restore run, restore proof, safety gate result, recovery evidence snapshot |
|
||||
| Operator Next Action | What should the user do next? | review finding, accept risk, assign owner, export evidence, inspect failed run, reconnect provider, verify permissions |
|
||||
|
||||
Pages that mix these layers without hierarchy must be flagged.
|
||||
|
||||
## Page Archetypes
|
||||
|
||||
Every page must be classified into one primary archetype and optionally one secondary archetype.
|
||||
|
||||
Allowed archetypes:
|
||||
|
||||
1. `Overview / Dashboard`
|
||||
2. `Findings / Inbox`
|
||||
3. `Evidence / Audit`
|
||||
4. `Backup / Restore`
|
||||
5. `Drift / Diff`
|
||||
6. `Inventory`
|
||||
7. `Reviews`
|
||||
8. `Exceptions / Accepted Risk`
|
||||
9. `Operations / Monitoring`
|
||||
10. `Provider / Integration`
|
||||
11. `Workspace / Tenant Context`
|
||||
12. `Settings / Admin`
|
||||
13. `Support / Diagnostics`
|
||||
14. `Commercial / Entitlements`
|
||||
15. `Customer Workspace`
|
||||
16. `Auth / Access`
|
||||
17. `Utility / Internal`
|
||||
18. `Deprecated / Legacy`
|
||||
19. `Manual Review Required`
|
||||
|
||||
If a page cannot be confidently classified, mark it as `Manual Review Required` and explain why.
|
||||
|
||||
## Design Depth Classification
|
||||
|
||||
Every page must receive one design-depth classification.
|
||||
|
||||
| Design Depth | Use For | Later Output |
|
||||
| --- | --- | --- |
|
||||
| Strategic Surface | Pages central to demo, sellability, customer experience, operator workflow, product positioning, or dangerous/high-impact actions | Individual target experience, individual Dark/Light SVG or mockup, individual follow-up spec |
|
||||
| Domain Pattern Surface | Important but repeatable domain pages | Shared domain pattern, grouped follow-up spec, optional pattern mockup |
|
||||
| Design-System Cleanup Surface | Smaller utility/admin pages | Shared table/form/state/action patterns; no individual mockup unless unusually important |
|
||||
| Internal / Deprecated / Hidden | Pages not treated as product surfaces | Reason and decision to hide, retire, protect, or leave internal |
|
||||
| Manual Review Required | Route/page cannot be safely evaluated | Human inspection before design claims |
|
||||
|
||||
## Repo-Truth Classification
|
||||
|
||||
Every page and recommendation must mark product truth level.
|
||||
|
||||
Allowed values:
|
||||
|
||||
- `repo-verified`
|
||||
- `plausible-existing`
|
||||
- `foundation-only`
|
||||
- `spec-only`
|
||||
- `conceptual-future-state`
|
||||
- `unknown`
|
||||
|
||||
Hard rule:
|
||||
|
||||
> Do not present conceptual or spec-only UI as implemented product truth.
|
||||
|
||||
## Scope
|
||||
|
||||
### In Scope
|
||||
|
||||
- Laravel/Filament admin pages
|
||||
- workspace-level pages
|
||||
- environment/tenant-scoped pages
|
||||
- monitoring pages
|
||||
- operations pages
|
||||
- governance pages
|
||||
- review pages
|
||||
- customer-facing review surfaces if present
|
||||
- provider/integration pages
|
||||
- settings/admin pages
|
||||
- support/diagnostic pages
|
||||
- auth/access/no-access pages where reachable
|
||||
- navigation and shell structure
|
||||
- page screenshots
|
||||
- current copy/labels
|
||||
- page purpose
|
||||
- primary actions
|
||||
- dangerous actions
|
||||
- empty/loading/error states where visible
|
||||
- responsive notes where feasible
|
||||
- design coverage matrix
|
||||
- recommended follow-up spec grouping
|
||||
- ongoing Design Coverage Gate for future UI specs
|
||||
- Constitution principle for UI/Productization Coverage
|
||||
- Spec template UI Surface Impact and UI/Productization Coverage blocks
|
||||
- Agent implementation prompt guardrail
|
||||
- CI/review script guard for UI surface changes
|
||||
|
||||
### Out of Scope
|
||||
|
||||
- Runtime UI changes
|
||||
- component implementation
|
||||
- CSS/theme implementation
|
||||
- route rewrites
|
||||
- localization implementation
|
||||
- database changes
|
||||
- auth/RBAC changes
|
||||
- feature creation
|
||||
- code cleanup unrelated to audit docs
|
||||
- runtime deployment behavior changes
|
||||
- full suite stabilization
|
||||
- high-fidelity SVG target mockups for all pages
|
||||
|
||||
## Required Output Structure
|
||||
|
||||
Implementation of this spec must create:
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
If `docs/brand/tenantial-brand-context.md` does not exist, implementation must create a minimal placeholder reference file or document that it is required before later mockup specs.
|
||||
|
||||
Do not invent final brand assets if official assets are missing.
|
||||
|
||||
Spec 323 must also update the process guardrail surfaces that make the registry durable:
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
## User Scenarios & Testing
|
||||
|
||||
### User Story 1 - Discover the reachable UI surface (Priority: P1)
|
||||
|
||||
As a product reviewer, I need a repo-based inventory of reachable UI pages/routes so later design work covers the actual application rather than only obvious navigation entries.
|
||||
|
||||
**Independent Test**: A reviewer can open `docs/ui-ux-enterprise-audit/route-inventory.md` and see every discovered UI route/page assigned an audit ID, source, reachability, scope, archetype, design depth, repo truth, and target coverage decision or unresolved marker.
|
||||
|
||||
**Acceptance Scenarios**:
|
||||
|
||||
1. Given the repo has Filament resources, pages, routes, and navigation definitions, when the audit runs discovery, then each discovered UI surface appears in `route-inventory.md` or `unresolved-pages.md`.
|
||||
2. Given a page is hidden, guarded, redirect-only, or browser-blocked, when it cannot be fully inspected, then it is still inventoried with a reason and no unsupported design claim.
|
||||
|
||||
### User Story 2 - Classify pages into product/design coverage decisions (Priority: P1)
|
||||
|
||||
As a product/design lead, I need each page classified by archetype, design depth, and repo truth so strategic mockups and pattern specs can be scoped without over-designing utility pages.
|
||||
|
||||
**Independent Test**: A reviewer can filter the inventory and coverage matrix to identify strategic, domain-pattern, cleanup, internal/deprecated, and manual-review pages.
|
||||
|
||||
**Acceptance Scenarios**:
|
||||
|
||||
1. Given a page is central to sellability or a core workflow, when it is reviewed, then it is marked as Strategic Surface and appears in `strategic-surfaces.md`.
|
||||
2. Given a page is a repeatable list/detail/admin surface, when it is reviewed, then it is assigned to a domain pattern or design-system cleanup path rather than receiving an unnecessary individual mockup requirement.
|
||||
|
||||
### User Story 3 - Capture current state and page-level findings (Priority: P1)
|
||||
|
||||
As a future implementation agent, I need current screenshots and concise page reports so follow-up specs can see current-state problems without rediscovering every surface.
|
||||
|
||||
**Independent Test**: Every reviewed page has a page report under `docs/ui-ux-enterprise-audit/page-reports/`, and every reachable strategic page has a desktop screenshot or a documented reason why no screenshot exists.
|
||||
|
||||
**Acceptance Scenarios**:
|
||||
|
||||
1. Given a strategic page is reachable in the browser, when the audit reviews it, then a desktop screenshot is saved under `screenshots/desktop/` and linked from inventory/report files.
|
||||
2. Given a page exposes dangerous actions, customer-facing language, misleading status, or workspace/environment ambiguity, when it is reviewed, then the page report flags the issue and recommends target handling.
|
||||
|
||||
### User Story 4 - Establish future Design Coverage Gate (Priority: P2)
|
||||
|
||||
As an engineering reviewer, I need a lightweight ongoing gate so future features do not add reachable UI surfaces without design classification.
|
||||
|
||||
**Independent Test**: `README.md`, `route-inventory.md`, templates, the coverage matrix, Spec Kit templates, agent implement prompts, PR template, and CI guard document/enforce how future specs update the registry when adding or changing reachable pages, modals, drawers, tables, forms, actions, or customer-facing states.
|
||||
|
||||
**Acceptance Scenarios**:
|
||||
|
||||
1. Given a future feature adds a new reachable page, when its spec closes, then it has updated inventory, archetype, design depth, repo truth, pattern/mockup decision, and matrix counts.
|
||||
2. Given a future feature adds a modal/drawer/action rather than a page, when it is UI-relevant, then it is mapped to a component/state pattern or documented as manual review/internal if not reviewable yet.
|
||||
3. Given a future PR changes guarded UI surface files without updating coverage artifacts, when the PR fast-feedback guard runs, then it fails unless the active spec contains a checked `No UI surface impact` decision.
|
||||
|
||||
## Edge Cases
|
||||
|
||||
- Route exists in `route:list` but redirects before rendering.
|
||||
- Route is guarded by auth, workspace membership, capability, or platform-plane access.
|
||||
- Page requires seeded data, provider connection, review pack, operation run, or customer-facing context to render meaningfully.
|
||||
- Page throws a runtime error during browser audit.
|
||||
- Page is reachable only through direct URL, global search, row action, modal, nested resource, or cluster navigation.
|
||||
- Route exists for legacy/deprecated behavior but should not be treated as product UI.
|
||||
- Page exposes old `tenant` terminology where workspace/environment language should be checked.
|
||||
- Screenshot capture is blocked by local browser instability, missing app server, auth fixture, or required provider state.
|
||||
- A future feature changes only a modal/drawer/action/state; it must still receive a design coverage decision even if no new route exists.
|
||||
|
||||
## Requirements
|
||||
|
||||
### Functional Requirements
|
||||
|
||||
- **FR-323-001**: The audit must create the required `docs/ui-ux-enterprise-audit/` structure and template files.
|
||||
- **FR-323-002**: The audit must discover UI surfaces using multiple methods: route discovery, file-based Filament/Livewire/view discovery, navigation/provider inspection, and browser navigation where feasible.
|
||||
- **FR-323-003**: The route inventory must include the required columns: ID, Route / URL, Source, Page Name, Area, Scope, Reachability, Auth/RBAC Notes, Primary Archetype, Secondary Archetype, Design Depth, Repo Truth, Screenshot, Page Report, and Notes.
|
||||
- **FR-323-004**: Every discovered page/route must receive a primary archetype or be listed in unresolved pages with a reason.
|
||||
- **FR-323-005**: Every discovered page/route must receive a design-depth classification or be listed in unresolved pages with a reason.
|
||||
- **FR-323-006**: Every discovered page/route must receive a repo-truth classification or be listed in unresolved pages with a reason.
|
||||
- **FR-323-007**: Every reachable strategic page must have a desktop screenshot or a documented blocker in `unresolved-pages.md`.
|
||||
- **FR-323-008**: Every reviewed page must have a page report using the page audit template.
|
||||
- **FR-323-009**: The design coverage matrix must summarize totals, coverage by area, coverage by archetype, missing/unclear coverage, and recommended next specs.
|
||||
- **FR-323-010**: Strategic surfaces must be listed with P0/P1/P2 priority, route, reason, current risk, and recommended target artifact.
|
||||
- **FR-323-011**: Grouped follow-up candidates must avoid one spec per page and must group later work by domain, shared problem, spec type, mockup need, pattern sufficiency, and priority.
|
||||
- **FR-323-012**: Unresolved pages must record the reason using one of the required reason categories: route not reachable, auth blocked, requires seeded data, requires provider connection, throws runtime error, redirect loop, unclear ownership, legacy/deprecated ambiguity, or manual browser inspection required.
|
||||
- **FR-323-013**: Page reports must review the first-five-seconds test, productization issues, information inventory, status/trust signals, dangerous actions, enterprise readiness scores, top issues, target direction, and later spec recommendation.
|
||||
- **FR-323-014**: Dangerous-action pages must be flagged for restore, delete, approve exception, accept risk, close finding, rerun backup, export evidence, change RBAC, disconnect integration, change entitlement, suspend workspace, invite user, or remove user actions.
|
||||
- **FR-323-015**: Customer-facing or auditor-facing pages must be flagged for customer-safe language and data exposure risks.
|
||||
- **FR-323-016**: Workspace/environment context ambiguity must be flagged where route, shell, breadcrumbs, filter chips, or terminology conflict.
|
||||
- **FR-323-017**: Misleading status or false-success states must be flagged; unknown, stale, pending, unconfirmed, not scanned, not reviewed, not connected, or not evaluated must not be treated as verified success.
|
||||
- **FR-323-018**: The README must explain purpose, what was done, what was not done, how to read the inventory/reports, classification models, and recommended next specs.
|
||||
- **FR-323-019**: The audit must establish the ongoing Feature Design Coverage Gate in README/template guidance so future UI features update the registry.
|
||||
- **FR-323-020**: If `docs/brand/tenantial-brand-context.md` is missing, the implementation must create a minimal placeholder reference or document the missing brand context as a blocker for later mockup specs.
|
||||
- **FR-323-021**: No runtime UI, route, auth, database, or business-logic files may be changed by this spec.
|
||||
- **FR-323-022**: The Constitution must include UI/Productization Coverage as a durable product principle requiring explicit coverage decisions for reachable UI surfaces.
|
||||
- **FR-323-023**: The Spec Kit templates and implementation prompts must require a UI Surface Impact decision and UI/Productization Coverage details for future UI-relevant specs.
|
||||
- **FR-323-024**: PR fast-feedback must include a mechanical guard that fails when guarded UI surface files change without either coverage artifact updates or a checked `No UI surface impact` decision in a changed spec.
|
||||
|
||||
### Non-Functional Requirements
|
||||
|
||||
- **NFR-323-001**: The audit must be repo-based and must not present conceptual/spec-only UI as implemented product truth.
|
||||
- **NFR-323-002**: Markdown artifacts must be reviewable, stable, and useful for follow-up implementation agents without requiring the full browser session to be replayed.
|
||||
- **NFR-323-003**: Screenshot naming must use stable audit IDs and slugs.
|
||||
- **NFR-323-004**: The audit must keep browser work bounded and document missing tablet/mobile coverage rather than blocking the spec on exhaustive responsive review.
|
||||
- **NFR-323-005**: The audit must avoid creating new runtime taxonomy, enum, database, UI framework, or code layer.
|
||||
- **NFR-323-006**: Validation must include `git diff --check` and the UI/Productization Coverage guard script.
|
||||
- **NFR-323-007**: Full runtime suite must not be run unless future implementation discovers runtime changes, which are out of scope for this spec.
|
||||
|
||||
## Data / Truth-Source Requirements
|
||||
|
||||
- **Runtime truth**: `apps/platform` routes, Filament resources/pages/clusters/providers, Livewire components, Blade views, and reachable browser pages.
|
||||
- **Documentation truth**: Specs 318 through 322, product roadmap/spec-candidates, current UI standards, and the generated audit artifacts.
|
||||
- **Screenshot truth**: Browser-captured current-state PNGs under the audit screenshots directory.
|
||||
- **No new persisted product truth**: No migrations, tables, models, enums, or runtime registries.
|
||||
|
||||
## UI / Surface Guardrail Impact
|
||||
|
||||
| Surface / Change | Operator-facing surface change? | Native vs Custom | Shared-Family Relevance | State Layers Touched | Exception Needed? | Low-Impact / N/A Note |
|
||||
| --- | --- | --- | --- | --- | --- | --- |
|
||||
| Current-state audit of existing pages | no runtime change | Existing Filament/native/custom surfaces are only observed | navigation, shell, tables, forms, modals, page state | route, query, shell, page, screenshot artifacts | no | Documentation-only audit |
|
||||
| UI Design Registry baseline | no runtime change | N/A | future spec DoD and review workflow | documentation artifacts | no | Future UI specs update registry |
|
||||
|
||||
## Cross-Cutting / Shared Pattern Reuse
|
||||
|
||||
- **Cross-cutting feature?**: yes, documentation and audit governance only
|
||||
- **Interaction classes observed**: navigation, status messaging, action hierarchy, dangerous actions, table/form states, empty states, evidence/report viewers, provider/onboarding surfaces, customer review surfaces
|
||||
- **Existing standards reused**: `docs/ui/tenantpilot-enterprise-ui-standards.md`, `docs/ui/operator-ux-surface-standards.md`, `docs/product/standards/filament-native-enterprise-ui.md`, Filament v5 blueprint rules, Specs 318 through 322 context/shell coverage
|
||||
- **New runtime abstraction introduced?**: no
|
||||
- **Bounded deviation / spread control**: The audit may introduce docs-only classification metadata. It must not become runtime code or a mandatory UI presenter/registry.
|
||||
|
||||
## OperationRun UX Impact
|
||||
|
||||
- **Touches OperationRun start/completion/link UX?**: no runtime change
|
||||
- **Central contract reused**: N/A
|
||||
- **Delegated UX behaviors**: N/A
|
||||
- **Surface-owned behavior kept local**: Existing OperationRun surfaces may be audited as pages only.
|
||||
- **Queued DB-notification policy**: N/A
|
||||
- **Terminal notification path**: N/A
|
||||
- **Exception path**: none
|
||||
|
||||
## Provider Boundary / Platform Core Check
|
||||
|
||||
- **Shared provider/platform boundary touched?**: observation only
|
||||
- **Provider-owned seams**: Provider/Graph/Microsoft/Entra Tenant terminology where it is genuinely external-provider identity.
|
||||
- **Platform-core seams**: Workspace, Managed Environment, Environment route/shell/filter behavior, customer review workspace, provider connection product surfaces.
|
||||
- **Neutral terms preserved**: Workspace, Environment, Managed Environment, Provider Connection, Operation, Evidence, Review.
|
||||
- **Retained provider-specific semantics and why**: The audit must not relabel runtime copy, but it must flag where provider or legacy tenant wording leaks into customer/operator product language.
|
||||
- **Follow-up path**: Product language findings go into grouped follow-up candidates or manual-review notes, not runtime changes in this spec.
|
||||
|
||||
## Proportionality Review
|
||||
|
||||
- **New source of truth?**: no runtime source of truth; yes, docs-only audit registry truth for design coverage.
|
||||
- **New persisted entity/table/artifact?**: no persisted runtime entity/table; yes Markdown docs and screenshot artifacts.
|
||||
- **New abstraction?**: no runtime abstraction.
|
||||
- **New enum/state/reason family?**: no runtime enum/state; docs-only page archetype, design-depth, and repo-truth labels.
|
||||
- **New cross-domain UI framework/taxonomy?**: no runtime framework; docs-only coverage taxonomy.
|
||||
- **Current operator problem**: Pages can remain reachable without product role, decision hierarchy, customer-safe review, or target-state decision.
|
||||
- **Existing structure is insufficient because**: Existing specs and standards define principles and route/shell contracts, but no artifact inventories every route/page and assigns design coverage.
|
||||
- **Narrowest correct implementation**: Markdown registry plus screenshots/page reports; no runtime registry, no component library, no redesign.
|
||||
- **Ownership cost**: Future UI specs must update the registry.
|
||||
- **Alternative intentionally rejected**: Building all target mockups or implementation changes in this spec.
|
||||
- **Current-release truth**: Productization audit over existing repo/runtime surfaces.
|
||||
|
||||
## Testing / Lane / Runtime Impact
|
||||
|
||||
- **Runtime impact**: none expected.
|
||||
- **Test purpose / classification**: Documentation/process guardrail validation plus optional Browser audit session; no Pest runtime tests required because app runtime behavior is unchanged.
|
||||
- **Affected validation lanes**: docs/prep validation plus PR guard script; browser session if app is opened for screenshots.
|
||||
- **Narrowest proving commands**: `git diff --check` and `bash scripts/check-ui-productization-coverage HEAD`.
|
||||
- **Fixture/helper/factory/seed/context cost risks**: none; browser screenshots should use existing local app state and document blockers instead of adding seeders.
|
||||
- **Heavy-family additions**: none.
|
||||
- **Browser coverage**: Manual/browser audit screenshots only, not automated browser tests.
|
||||
- **Full suite**: Not run for Markdown-only implementation.
|
||||
|
||||
## Discovery Requirements
|
||||
|
||||
Implementation must use multiple discovery methods:
|
||||
|
||||
- `cd apps/platform && ./vendor/bin/sail artisan route:list`
|
||||
- Fallback if Sail is unavailable: `cd apps/platform && php artisan route:list`
|
||||
- File-based discovery in:
|
||||
- `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`
|
||||
- Navigation discovery through current navigation definitions, clusters, resource registration, page registration, and panel providers.
|
||||
- Browser discovery where feasible for reachable pages.
|
||||
|
||||
## Screenshot Requirements
|
||||
|
||||
- Every reachable strategic page requires a desktop screenshot.
|
||||
- Every reachable domain pattern page should have a desktop screenshot when feasible.
|
||||
- Utility/admin screenshots are optional if the page is simple and covered by inventory/page report.
|
||||
- Tablet/mobile screenshots are optional and should be captured for app shell, dashboard/overview, customer review workspace, governance inbox, operations, evidence overview, and critical forms when feasible.
|
||||
|
||||
Use stable paths:
|
||||
|
||||
```text
|
||||
docs/ui-ux-enterprise-audit/screenshots/desktop/<audit-id>-<page-slug>.png
|
||||
docs/ui-ux-enterprise-audit/screenshots/tablet/<audit-id>-<page-slug>.png
|
||||
docs/ui-ux-enterprise-audit/screenshots/mobile/<audit-id>-<page-slug>.png
|
||||
```
|
||||
|
||||
## Enterprise Readiness Rubric
|
||||
|
||||
Each reviewed page receives scores from 0 to 5 for:
|
||||
|
||||
- Information Architecture
|
||||
- Information Density
|
||||
- Target User Clarity
|
||||
- Sellability / Platform Feel
|
||||
- Progressive Disclosure
|
||||
- Layout & Hierarchy
|
||||
- Design-System Fit
|
||||
- Accessibility
|
||||
- Responsive UX
|
||||
- Component Quality
|
||||
- UX Writing
|
||||
- Performance Perception
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- **SC-323-001**: `docs/ui-ux-enterprise-audit/README.md` exists and documents audit purpose, scope, classifications, and next specs.
|
||||
- **SC-323-002**: `route-inventory.md` exists and all discovered UI routes/pages are classified or listed in `unresolved-pages.md`.
|
||||
- **SC-323-003**: Every discovered page has a primary archetype, design-depth classification, and repo-truth classification unless unresolved with reason.
|
||||
- **SC-323-004**: Every reachable strategic page has a desktop screenshot or documented screenshot blocker.
|
||||
- **SC-323-005**: Every reviewed page has a page report.
|
||||
- **SC-323-006**: `design-coverage-matrix.md` summarizes total coverage.
|
||||
- **SC-323-007**: `strategic-surfaces.md` identifies P0/P1/P2 strategic surfaces.
|
||||
- **SC-323-008**: `grouped-follow-up-candidates.md` groups later specs instead of creating one spec per page.
|
||||
- **SC-323-009**: Dangerous-action pages, customer-facing pages, workspace/environment ambiguity, and misleading status risks are flagged.
|
||||
- **SC-323-010**: Ongoing Feature Design Coverage Gate is documented in the audit README/templates.
|
||||
- **SC-323-011**: No runtime UI, route, auth, DB, or business-logic changes are made.
|
||||
- **SC-323-012**: Constitution, Spec Kit templates, implementation prompts, PR template, and PR fast-feedback guard make the future UI Surface Impact decision explicit.
|
||||
- **SC-323-013**: `git diff --check` passes.
|
||||
- **SC-323-014**: `bash scripts/check-ui-productization-coverage HEAD` passes for the current non-runtime guardrail change.
|
||||
- **SC-323-015**: Final implementation report explicitly states full suite was not run.
|
||||
|
||||
## Assumptions
|
||||
|
||||
- The app can be opened locally through Sail or an existing local dev server for at least some screenshots.
|
||||
- Some pages require auth, seeded data, provider connection, operation/review/evidence fixtures, or platform-plane access and may be unresolved.
|
||||
- Desktop screenshots are the minimum useful baseline for strategic surfaces; tablet/mobile coverage can be deferred when costly.
|
||||
- The audit may use Tenantial naming as the product lens while preserving TenantPilot/TenantAtlas repo terminology where runtime truth still uses it.
|
||||
- Future specs can update the audit registry without making Spec 323 a runtime dependency.
|
||||
|
||||
## Open Questions
|
||||
|
||||
No open question blocks preparation. Implementation should document any route/page that cannot be safely classified as `Manual Review Required`.
|
||||
|
||||
## Recommended Next Specs
|
||||
|
||||
1. `324-tenantial-strategic-surface-target-mockups`
|
||||
2. `325-tenantial-design-system-and-state-patterns`
|
||||
3. `326-tenantial-domain-pattern-coverage-pass`
|
||||
4. `327-tenantial-enterprise-ui-implementation-wave-1`
|
||||
|
||||
Spec 323 must not implement those specs.
|
||||
|
||||
## Required Final Report Shape
|
||||
|
||||
The implementation final response for Spec 323 must include:
|
||||
|
||||
- changed/created files
|
||||
- route/page count
|
||||
- screenshot count
|
||||
- strategic surface count
|
||||
- unresolved page count
|
||||
- validation commands run
|
||||
- explicit note that no runtime code was changed
|
||||
- explicit note that full suite was not run
|
||||
153
specs/323-tenantial-enterprise-ui-audit-foundation/tasks.md
Normal file
153
specs/323-tenantial-enterprise-ui-audit-foundation/tasks.md
Normal file
@ -0,0 +1,153 @@
|
||||
# Tasks: Tenantial Enterprise UI Audit Foundation
|
||||
|
||||
**Input**: Spec artifacts from `specs/323-tenantial-enterprise-ui-audit-foundation/`
|
||||
**Prerequisites**: `spec.md`, `plan.md`
|
||||
**Runtime posture**: Documentation/browser-audit only. No runtime UI, route, auth, DB, or business-logic changes.
|
||||
|
||||
## Phase 1: Guardrails And Repo Context
|
||||
|
||||
- [x] T001 Re-read `specs/323-tenantial-enterprise-ui-audit-foundation/spec.md`, `plan.md`, and `tasks.md` before implementation starts.
|
||||
- [x] T002 Re-read `AGENTS.md`, `.specify/memory/constitution.md`, `docs/ai-coding-rules.md`, and relevant `docs/*-guidelines.md` files before making audit artifacts.
|
||||
- [x] T003 Re-read `docs/ui/tenantpilot-enterprise-ui-standards.md`, `docs/ui/operator-ux-surface-standards.md`, and `docs/product/standards/filament-native-enterprise-ui.md` for the audit lens.
|
||||
- [x] T004 Re-read Specs 318 through 322 as historical/context dependencies without editing their completed artifacts.
|
||||
- [x] T005 Verify the implementation starts from branch `323-tenantial-enterprise-ui-audit-foundation` and the working tree has no unrelated user changes.
|
||||
- [x] T006 Confirm the implementation diff remains limited to audit docs, Spec 323 artifacts, Spec Kit process templates/prompts, PR template/workflow guardrails, and `scripts/check-ui-productization-coverage`; no app runtime files are changed.
|
||||
|
||||
## Phase 2: Audit Structure And Templates
|
||||
|
||||
- [x] T007 Create `docs/ui-ux-enterprise-audit/` and subdirectories `screenshots/desktop/`, `screenshots/tablet/`, `screenshots/mobile/`, `page-reports/`, and `templates/`.
|
||||
- [x] T008 Create `docs/ui-ux-enterprise-audit/templates/page-audit-template.md` with the full page audit structure from `specs/323-tenantial-enterprise-ui-audit-foundation/spec.md`.
|
||||
- [x] T009 Create `docs/ui-ux-enterprise-audit/templates/route-inventory-template.md` with required inventory columns and classification options.
|
||||
- [x] T010 Create `docs/ui-ux-enterprise-audit/templates/design-coverage-template.md` with summary, coverage by area, coverage by archetype, missing coverage, and next spec sections.
|
||||
- [x] T011 Create `docs/ui-ux-enterprise-audit/README.md` explaining audit purpose, what Spec 323 did, what it did not do, how to read inventory/reports, classification models, the ongoing Design Coverage Gate, and recommended next specs.
|
||||
- [x] T012 If `docs/brand/tenantial-brand-context.md` is missing, create a minimal placeholder reference explaining that official Tenantial brand assets/context are required before later mockup specs.
|
||||
|
||||
## Phase 3: Route And File-Based Discovery
|
||||
|
||||
- [x] T013 Run `cd apps/platform && ./vendor/bin/sail artisan route:list` and use `cd apps/platform && php artisan route:list` only if Sail is unavailable.
|
||||
- [x] T014 Inspect `apps/platform/app/Filament/Pages/` and record discovered pages in `docs/ui-ux-enterprise-audit/route-inventory.md`.
|
||||
- [x] T015 Inspect `apps/platform/app/Filament/Resources/` and record list/create/edit/view/custom pages in `docs/ui-ux-enterprise-audit/route-inventory.md`.
|
||||
- [x] T016 Inspect `apps/platform/app/Filament/Clusters/` and record cluster navigation/page implications in `docs/ui-ux-enterprise-audit/route-inventory.md`.
|
||||
- [x] T017 Inspect `apps/platform/app/Livewire/`, `apps/platform/resources/views/`, and `apps/platform/routes/` for reachable UI surfaces not obvious from Filament resources.
|
||||
- [x] T018 Inspect `apps/platform/app/Providers/Filament/` and `apps/platform/bootstrap/providers.php` to identify panel paths, registered discovery locations, and admin/system plane boundaries.
|
||||
- [x] T019 Inspect current navigation and shell support files related to workspace hubs, environment-owned surfaces, alerts/audit, provider connections, operations, reviews, evidence, settings, and support.
|
||||
- [x] T020 Assign stable sequential audit IDs (`UI-001`, `UI-002`, ...) for every discovered UI route/page in `docs/ui-ux-enterprise-audit/route-inventory.md`.
|
||||
- [x] T021 For every discovered row in `docs/ui-ux-enterprise-audit/route-inventory.md`, fill source, page name, area, scope, reachability, auth/RBAC notes, primary archetype, design depth, repo truth, screenshot link if available, page report link, and notes.
|
||||
- [x] T022 Add any route/page that cannot be safely evaluated to `docs/ui-ux-enterprise-audit/unresolved-pages.md` with one required blocker reason.
|
||||
|
||||
## Phase 4: Browser Pass And Screenshots
|
||||
|
||||
- [x] T023 Determine the local app URL and auth/browser feasibility without changing runtime configuration.
|
||||
- [x] T024 Open reachable strategic candidate pages in the browser and capture required desktop screenshots under `docs/ui-ux-enterprise-audit/screenshots/desktop/`.
|
||||
- [x] T025 Capture preferred desktop screenshots for reachable domain pattern pages under `docs/ui-ux-enterprise-audit/screenshots/desktop/` when feasible.
|
||||
- [x] T026 Capture optional tablet screenshots under `docs/ui-ux-enterprise-audit/screenshots/tablet/` for app shell, overview/dashboard, customer review workspace, governance inbox, operations, evidence overview, and critical forms when feasible.
|
||||
- [x] T027 Capture optional mobile screenshots under `docs/ui-ux-enterprise-audit/screenshots/mobile/` for the same high-risk surfaces when feasible.
|
||||
- [x] T028 Record screenshot blockers in `docs/ui-ux-enterprise-audit/unresolved-pages.md` for routes blocked by auth, missing data, provider connection, runtime errors, redirect loops, or manual inspection needs.
|
||||
- [x] T029 Do not add seeders, factories, fixtures, runtime routes, or UI changes to make screenshots easier.
|
||||
|
||||
## Phase 5: Page Reports And Classification
|
||||
|
||||
- [x] T030 Create one page report in `docs/ui-ux-enterprise-audit/page-reports/` for each reviewed page using the page audit template.
|
||||
- [x] T031 [P] For each strategic candidate report, evaluate first-five-seconds test, productization review, enterprise readiness scores, top issues, target direction, and later spec recommendation.
|
||||
- [x] T032 [P] For each domain pattern report, document shared pattern fit, repeated information architecture problems, and whether a grouped follow-up spec is enough.
|
||||
- [x] T033 [P] For each design-system cleanup report, document table/form/state/action cleanup needs without requiring an individual mockup.
|
||||
- [x] T034 [P] For each internal/deprecated/hidden/manual-review route, document reason and do not make product-readiness claims.
|
||||
- [x] T035 Flag dangerous actions in relevant page reports, including restore, delete, approve exception, accept risk, close finding, rerun backup, export evidence, RBAC changes, disconnect integration, entitlement changes, workspace suspension, invites, and user removal.
|
||||
- [x] T036 Flag customer-facing or auditor-facing pages for customer-safe language, raw-data exposure, unsupported compliance claims, evidence clarity, and review-pack/export context.
|
||||
- [x] T037 Flag workspace/environment context ambiguity in page reports where shell, route, query, breadcrumbs, copy, or chips conflict.
|
||||
- [x] T038 Flag misleading status states where unknown, stale, pending, unconfirmed, not scanned, not reviewed, not connected, or not evaluated appear as healthy/successful.
|
||||
- [x] T039 Link every created page report back from `docs/ui-ux-enterprise-audit/route-inventory.md`.
|
||||
|
||||
## Phase 6: Coverage Matrix And Follow-Up Grouping
|
||||
|
||||
- [x] T040 Create `docs/ui-ux-enterprise-audit/design-coverage-matrix.md` with total routes discovered, pages reviewed, screenshots captured, strategic surfaces, domain pattern surfaces, cleanup surfaces, internal/deprecated surfaces, and manual-review counts.
|
||||
- [x] T041 Populate coverage by area in `docs/ui-ux-enterprise-audit/design-coverage-matrix.md`.
|
||||
- [x] T042 Populate coverage by archetype in `docs/ui-ux-enterprise-audit/design-coverage-matrix.md`.
|
||||
- [x] T043 Populate missing/unclear coverage and recommended next specs in `docs/ui-ux-enterprise-audit/design-coverage-matrix.md`.
|
||||
- [x] T044 Create `docs/ui-ux-enterprise-audit/strategic-surfaces.md` with P0/P1/P2 strategic surfaces, route, why strategic, current risk, and recommended target artifact.
|
||||
- [x] T045 Create `docs/ui-ux-enterprise-audit/grouped-follow-up-candidates.md` grouped by customer review workspace, governance inbox, operations, evidence, reviews, drift/findings, backup/restore, provider/onboarding, inventory, settings/admin, support/diagnostics, commercial/entitlements, auth/access, app shell/navigation, and global tables/forms/states.
|
||||
- [x] T046 Ensure grouped follow-up candidates state covered pages, shared problem, recommended later spec type, individual mockup need, domain-pattern sufficiency, and priority.
|
||||
|
||||
## Phase 7: Ongoing Design Coverage Gate Baseline
|
||||
|
||||
- [x] T047 Add the Ongoing Feature Design Coverage Gate guidance to `docs/ui-ux-enterprise-audit/README.md`.
|
||||
- [x] T048 Add the standard UI/UX Coverage Requirements checklist for later UI specs to `docs/ui-ux-enterprise-audit/README.md` or a template file.
|
||||
- [x] T049 Document the decision model for new strategic pages, normal domain pages, small admin/utility pages, modals/drawers/actions, and internal/manual-review features.
|
||||
- [x] T050 Ensure `docs/ui-ux-enterprise-audit/route-inventory.md` and `design-coverage-matrix.md` explain how future features update counts, pattern links, screenshot links, and unresolved entries.
|
||||
- [x] T056 Add UI/Productization Coverage as a durable principle in `.specify/memory/constitution.md`.
|
||||
- [x] T057 Add mandatory UI Surface Impact and UI/Productization Coverage blocks to `.specify/templates/spec-template.md`.
|
||||
- [x] T058 Add UI coverage planning, task, and checklist guardrails to `.specify/templates/plan-template.md`, `.specify/templates/tasks-template.md`, and `.specify/templates/checklist-template.md`.
|
||||
- [x] T059 Add the pre-implementation UI/Productization Coverage guardrail to `.codex/prompts/speckit.implement.md` and `.github/agents/speckit.implement.agent.md`.
|
||||
- [x] T060 Add a UI Surface Impact checkbox to `.gitea/pull_request_template.md`.
|
||||
- [x] T061 Add `scripts/check-ui-productization-coverage` and wire it into `.gitea/workflows/test-pr-fast-feedback.yml`.
|
||||
|
||||
## Phase 8: Validation And Close-Out
|
||||
|
||||
- [x] T051 Review the final diff and confirm no app runtime files under `apps/platform/app/`, `apps/platform/config/`, `apps/platform/database/`, `apps/platform/resources/`, `apps/platform/routes/`, or runtime tests were changed.
|
||||
- [x] T052 Run `git diff --check` and `bash scripts/check-ui-productization-coverage HEAD` from the repository root.
|
||||
- [x] T053 Record exact route/page count, pages reviewed, screenshot count, strategic surface count, unresolved page count, guardrail updates, and validation result for the final response.
|
||||
- [x] T054 Record that the work was browser audit / Markdown only and no runtime code was changed.
|
||||
- [x] T055 Record that the full suite was not run because no runtime code changed.
|
||||
|
||||
## Non-Goals / Stop Conditions
|
||||
|
||||
- [x] NT001 Do not modify runtime UI, Blade views, Filament resources/pages, Livewire components, routes, auth, policies, services, jobs, models, migrations, config, or tests.
|
||||
- [x] NT002 Do not rename runtime product concepts or change workspace/environment/tenant context behavior.
|
||||
- [x] NT003 Do not add packages, env vars, queues, scheduler changes, storage configuration, or deployment scripts.
|
||||
- [x] NT004 Do not create high-fidelity target mockups in Spec 323.
|
||||
- [x] NT005 Do not create one follow-up spec per small page.
|
||||
- [x] NT006 Do not present spec-only or conceptual UI as repo-verified product truth.
|
||||
- [x] NT007 Stop and update `spec.md` and `plan.md` before any application implementation becomes necessary.
|
||||
|
||||
## Requirement Coverage Map
|
||||
|
||||
| Requirement(s) | Task Coverage |
|
||||
| --- | --- |
|
||||
| FR-323-001, FR-323-018, FR-323-019 | T007-T012, T047-T050 |
|
||||
| FR-323-022, FR-323-023, FR-323-024 | T056-T061 |
|
||||
| FR-323-002 | T013-T019 |
|
||||
| FR-323-003, FR-323-004, FR-323-005, FR-323-006 | T020-T022, T040-T043 |
|
||||
| FR-323-007 | T023-T028 |
|
||||
| FR-323-008, FR-323-013 | T030-T039 |
|
||||
| FR-323-009 | T040-T043 |
|
||||
| FR-323-010 | T044 |
|
||||
| FR-323-011 | T045-T046 |
|
||||
| FR-323-012 | T022, T028 |
|
||||
| FR-323-014, FR-323-015, FR-323-016, FR-323-017 | T035-T038 |
|
||||
| FR-323-020 | T012 |
|
||||
| FR-323-021, NFR-323-005, NFR-323-007 | T006, T029, T051, T054-T055, NT001-NT007 |
|
||||
| NFR-323-001, NFR-323-002, NFR-323-003, NFR-323-004 | T008-T011, T020-T028, T030-T050 |
|
||||
| NFR-323-006 | T052 |
|
||||
|
||||
## Dependencies
|
||||
|
||||
1. Phase 1 must complete before audit artifacts are created.
|
||||
2. Phase 2 must complete before discovery data is recorded.
|
||||
3. Phase 3 must produce the first route inventory before browser screenshots and page reports are finalized.
|
||||
4. Phase 4 screenshots can run in parallel with Phase 5 page reports once audit IDs are assigned.
|
||||
5. Phase 6 depends on completed classifications from Phases 3 through 5.
|
||||
6. Phase 7 depends on the final classification model used in the artifacts.
|
||||
7. Phase 8 depends on all docs and screenshots being final.
|
||||
|
||||
## MVP Scope
|
||||
|
||||
The minimum viable Spec 323 implementation is:
|
||||
|
||||
1. Required audit directory structure and templates.
|
||||
2. Route inventory with every discovered page classified or unresolved.
|
||||
3. Desktop screenshots for reachable strategic pages or documented blockers.
|
||||
4. Page reports for reviewed pages.
|
||||
5. Coverage matrix, strategic surfaces, grouped follow-up candidates, and unresolved pages.
|
||||
6. Ongoing Design Coverage Gate documentation.
|
||||
7. `git diff --check` passing with no runtime code changes.
|
||||
|
||||
## Parallel Work Examples
|
||||
|
||||
```text
|
||||
Agent A: Route/file/navigation discovery and route-inventory.md.
|
||||
Agent B: Browser screenshots for strategic/domain pages.
|
||||
Agent C: Page reports for customer/review/evidence/governance surfaces.
|
||||
Agent D: Coverage matrix, strategic-surfaces.md, and grouped-follow-up-candidates.md.
|
||||
```
|
||||
|
||||
Parallel workers must not edit the same Markdown file at the same time.
|
||||
Loading…
Reference in New Issue
Block a user