ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity

Spec 325: add screenshot-anchored strategic target images #385

Merged
ahmido merged 1 commits from 325-screenshot-anchored-strategic-target-images into platform-dev 2026-05-18 07:18:15 +00:00
Conversation 0 Commits 1 Files Changed 56 +3105
56 changed files with 3105 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

17
docs/ui-ux-enterprise-audit/README.md
View File

@ -15,6 +15,23 @@ ## Outputs
- `screenshots/desktop/`: desktop current-state screenshots and blocker evidence from the local browser pass.
- `templates/`: reusable templates for future UI audit updates.
## Spec 325 Target Experience Artifacts
Spec 325 adds screenshot-anchored strategic target direction without changing runtime UI.
- `target-experience-briefs/README.md`: entry point for selected surface briefs.
- `target-experience-briefs/strategic-target-image-shortlist.md`: proportional 9-surface shortlist, selected/deferred rationale, and source links.
- `target-images/README.md`: accepted target images and sidecar index.
- `target-images/target/`: dark/light PNG target images plus sidecar Markdown files.
- `target-images/reference/spec-325-premium-reference/`: user-accepted premium visual reference set used to calibrate the regenerated target images.
- `target-images/source/README.md`: source screenshot reuse policy.
- `target-images/problem-annotations/README.md`: annotation policy for future waves.
- `follow-up-specs/325-strategic-target-image-implementation-candidates.md`: grouped runtime implementation candidates derived from the target artifacts.
Spec 325 selected Workspace Overview, Environment Dashboard, Operations Hub, Governance Inbox, Customer Review Workspace, Audit Log, Restore Safety Workflow, Provider Readiness, and Baseline Compare / Drift. Runtime implemented remains `No` for every Spec 325 artifact.
The Spec 325 dark target PNGs are the primary premium visual target direction. Light variants remain support artifacts because Filament includes light mode by default.
## Discovery Basis
Spec 323 used multiple repo-based discovery methods:

26
docs/ui-ux-enterprise-audit/design-coverage-matrix.md
View File

@ -18,6 +18,32 @@ ## Summary
| 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`. |
## Spec 325 Target Image Coverage
Spec 325 adds target-image and target-brief coverage for 9 selected P0/P1 strategic surface groups. This is documentation and visual direction only. Runtime implemented remains `No`.
| Metric | Count | Notes |
| --- | ---: | --- |
| Selected target surface groups | 9 | Proportional shortlist from 44 strategic rows. |
| Target experience briefs | 9 | Stored in `target-experience-briefs/`. |
| Target image sidecars | 9 | Stored in `target-images/target/`. |
| Dark target PNGs | 9 | 1600 x 900 PNG files. |
| Light target PNGs | 9 | 1600 x 900 PNG files for review/customer/auditor/management-safe variants and consistency. |
| Premium visual reference images | 4 | User-accepted calibration images stored in `target-images/reference/spec-325-premium-reference/`. |
| Runtime UI implemented | 0 | Spec 325 does not change product runtime surfaces. |
| Selected surface group | Source row(s) | Target brief | Runtime implemented |
| --- | --- | --- | --- |
| Workspace Overview | UI-001, UI-002 | `target-experience-briefs/workspace-overview.md` | No |
| Environment Dashboard | UI-011 | `target-experience-briefs/environment-dashboard.md` | No |
| Operations Hub | UI-016 | `target-experience-briefs/operations-hub.md` | No |
| Governance Inbox | UI-028 | `target-experience-briefs/governance-inbox.md` | No |
| Customer Review Workspace | UI-038 | `target-experience-briefs/customer-review-workspace.md` | No |
| Audit Log | UI-025 | `target-experience-briefs/audit-log.md` | No |
| Restore Safety Workflow | UI-053, UI-054 | `target-experience-briefs/restore-safety-workflow.md` | No |
| Provider Readiness | UI-072, UI-073 | `target-experience-briefs/provider-readiness.md` | No |
| Baseline Compare / Drift | UI-061 | `target-experience-briefs/baseline-compare-drift.md` | No |
## Coverage By Area
| Area | Rows | Coverage Notes |

46
docs/ui-ux-enterprise-audit/follow-up-specs/325-strategic-target-image-implementation-candidates.md Normal file
View File

@ -0,0 +1,46 @@
# Spec 325 Strategic Target Image Implementation Candidates
Spec 325 creates target artifacts only. These candidates group later runtime implementation work proportionally so the project does not create one implementation spec per small page.
## Recommended Order
| Order | Candidate lane | Source target artifacts | Why this group is proportional |
| ---: | --- | --- | --- |
| 1 | Customer Review Workspace productization | `../target-experience-briefs/customer-review-workspace.md`, `../target-images/target/customer-review-workspace-target.md` | Highest sellability and customer-safe review impact. |
| 2 | Governance Inbox decision experience | `../target-experience-briefs/governance-inbox.md`, `../target-images/target/governance-inbox-target.md` | Central operator human-in-the-loop workflow; can absorb decision register and exception detail patterns later. |
| 3 | Operations Hub productization | `../target-experience-briefs/operations-hub.md`, `../target-images/target/operations-hub-target.md` | Establishes execution truth and OperationRun outcome grammar before related alert/run detail work. |
| 4 | Evidence and review pack consumption productization | `../target-experience-briefs/audit-log.md`, `../target-experience-briefs/customer-review-workspace.md` | Provides customer-safe proof and audit/export language without overloading runtime pages with raw diagnostics. |
| 5 | Restore safety UX productization | `../target-experience-briefs/restore-safety-workflow.md`, `../target-images/target/restore-safety-workflow-target.md` | Highest destructive-action risk; needs seeded capability/browser fixture and strict audit/OperationRun tests. |
| 6 | Provider onboarding/readiness UX cleanup | `../target-experience-briefs/provider-readiness.md`, `../target-images/target/provider-readiness-target.md` | Trust-critical setup and recovery surface; can later extend to create/detail/onboarding wizard states. |
| 7 | Drift/Baseline decision experience | `../target-experience-briefs/baseline-compare-drift.md`, `../target-images/target/baseline-compare-drift-target.md` | Requires seeded baseline/compare data; target first defines assignment, evidence gaps, and decision hierarchy. |
| 8 | Workspace and Environment dashboard productization | `../target-experience-briefs/workspace-overview.md`, `../target-experience-briefs/environment-dashboard.md` | High first-read value; can be implemented after decision/action hierarchy is agreed. |
## Shared Pattern Dependencies
Spec 326 Tenantial Pattern Library & State System should be prepared before broad implementation if multiple lanes begin to repeat:
- status/trust badges
- evidence summary strips
- OperationRun outcome strips
- dangerous-action confirmation grammar
- customer-safe review cards
- detail drawer disclosure levels
- empty/loading/error state grammar
- workspace/environment context headers
Do not turn these into a runtime framework inside a single page implementation. Extract only after real repeated cases prove the need.
## Conceptual Elements Requiring Repo Verification
| Element | Why verification is required |
| --- | --- |
| Recommended next action copy | Must come from real policy/capability/operation state, not target-image prose. |
| Evidence completeness and freshness labels | Must map to existing evidence snapshots, review packs, reports, or explicit new spec scope. |
| Restore safety gate steps | Must map to actual restore dry-run, validation, confirmation, audit, and OperationRun behavior. |
| Provider permission readiness | Must map to provider connection state, required permissions, and safe diagnostic disclosure. |
| Drift impact summaries | Must map to assigned baseline, latest compare result, evidence gaps, and tenant/environment scope. |
| Customer-safe export/share actions | Must be authorized, audited, scoped, and redacted before becoming runtime UI. |
## Do Not Implement Yet
Do not implement every visual tile, label, drawer, or action shown in target PNGs as a literal UI requirement. Later specs must first confirm data availability, RBAC, workspace/environment entitlement, audit logging, OperationRun semantics, customer-safe disclosure, and dangerous-action confirmation behavior.

17
docs/ui-ux-enterprise-audit/grouped-follow-up-candidates.md
View File

@ -2,6 +2,23 @@ # Grouped Follow-Up Candidates
Spec 323 intentionally avoids one follow-up spec per small page. These groups define the next practical design lanes.
## Spec 325 Target Image Lane Mapping
Spec 325 adds target artifacts for selected surfaces and maps them to grouped implementation lanes. Runtime implementation remains deferred.
| Spec 325 implementation lane | Target artifacts | Related existing group |
| --- | --- | --- |
| Customer Review Workspace productization | `target-experience-briefs/customer-review-workspace.md`, `target-images/target/customer-review-workspace-target.md` | Customer review workspace |
| Governance Inbox decision experience | `target-experience-briefs/governance-inbox.md`, `target-images/target/governance-inbox-target.md` | Governance inbox |
| Operations Hub productization | `target-experience-briefs/operations-hub.md`, `target-images/target/operations-hub-target.md` | Operations |
| Evidence and review pack consumption productization | `target-experience-briefs/audit-log.md`, `target-experience-briefs/customer-review-workspace.md` | Evidence, Reviews |
| Restore safety UX productization | `target-experience-briefs/restore-safety-workflow.md`, `target-images/target/restore-safety-workflow-target.md` | Backup / restore |
| Provider onboarding/readiness UX cleanup | `target-experience-briefs/provider-readiness.md`, `target-images/target/provider-readiness-target.md` | Provider / onboarding |
| Drift/Baseline decision experience | `target-experience-briefs/baseline-compare-drift.md`, `target-images/target/baseline-compare-drift-target.md` | Drift / findings |
| Workspace and Environment dashboard productization | `target-experience-briefs/workspace-overview.md`, `target-experience-briefs/environment-dashboard.md` | App shell / navigation |
The dedicated follow-up candidate register is `follow-up-specs/325-strategic-target-image-implementation-candidates.md`.
| 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 |

30
docs/ui-ux-enterprise-audit/strategic-surfaces.md
View File

@ -8,6 +8,36 @@ # Strategic Surfaces
- 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.
## Spec 325 Target Image Selection Overlay
Spec 325 selected 9 P0/P1 surface groups for screenshot-anchored target briefs and dark/light target images. The table below marks selected and deferred decisions without removing or rewriting the original Spec 323 baseline rows.
### Selected For Spec 325 Target Image
| Surface group | Covered strategic rows | Target brief | Target sidecar |
| --- | --- | --- | --- |
| Workspace Overview | UI-001, UI-002 | `target-experience-briefs/workspace-overview.md` | `target-images/target/workspace-overview-target.md` |
| Environment Dashboard | UI-011 | `target-experience-briefs/environment-dashboard.md` | `target-images/target/environment-dashboard-target.md` |
| Operations Hub | UI-016 | `target-experience-briefs/operations-hub.md` | `target-images/target/operations-hub-target.md` |
| Governance Inbox | UI-028 | `target-experience-briefs/governance-inbox.md` | `target-images/target/governance-inbox-target.md` |
| Customer Review Workspace | UI-038 | `target-experience-briefs/customer-review-workspace.md` | `target-images/target/customer-review-workspace-target.md` |
| Audit Log | UI-025 | `target-experience-briefs/audit-log.md` | `target-images/target/audit-log-target.md` |
| Restore Safety Workflow | UI-053, UI-054 | `target-experience-briefs/restore-safety-workflow.md` | `target-images/target/restore-safety-workflow-target.md` |
| Provider Readiness | UI-072, UI-073 | `target-experience-briefs/provider-readiness.md` | `target-images/target/provider-readiness-target.md` |
| Baseline Compare / Drift | UI-061 | `target-experience-briefs/baseline-compare-drift.md` | `target-images/target/baseline-compare-drift-target.md` |
### Deferred By Spec 325
| Deferred rows | Deferral reason | Later coverage |
| --- | --- | --- |
| UI-029, UI-034, UI-036, UI-076 | Governance/detail variants need seeded records after inbox pattern is accepted. | Governance Inbox decision experience and Drift/Baseline decision experience. |
| UI-037, UI-040, UI-042, UI-044, UI-046, UI-048 | Evidence/review detail and export surfaces need customer-safe pattern work after the customer workspace and audit anchors. | Evidence and review pack consumption productization. |
| UI-049, UI-051, UI-052 | Backup pages need capability-backed fixtures; restore safety is the first high-risk anchor. | Backup/Restore safety workflow spec. |
| UI-055, UI-057, UI-058, UI-063, UI-069 | Baseline/library/inventory detail pages should follow after baseline compare/drift hierarchy is verified. | Drift/Baseline and inventory proof patterns. |
| UI-007, UI-010, UI-013, UI-014 | Admin/access/onboarding surfaces are important but outside the first target-image wave. | Admin/settings and provider onboarding specs. |
| UI-017, UI-018 | Operation detail and alerting follow the Operations Hub target grammar. | Operations and alerting pattern spec. |
| UI-085, UI-091, UI-094, UI-095, UI-097, UI-098 | System-plane P2 surfaces require separate platform auth/capability fixture. | System-plane controls target spec. |
| 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. |

46
docs/ui-ux-enterprise-audit/target-experience-briefs/README.md Normal file
View File

@ -0,0 +1,46 @@
# Spec 325 Target Experience Briefs
Spec 325 adds screenshot-anchored target experience direction for a proportional set of strategic UI surfaces. These briefs are design and implementation guidance only. They are not runtime implementation truth and do not change product UI.
## Selected Surfaces
| Surface | Source report | Target brief | Target sidecar |
| --- | --- | --- | --- |
| Workspace Overview | `../page-reports/ui-001-workspace-overview.md` | `workspace-overview.md` | `../target-images/target/workspace-overview-target.md` |
| Environment Dashboard | `../page-reports/ui-002-environment-dashboard.md` | `environment-dashboard.md` | `../target-images/target/environment-dashboard-target.md` |
| Operations Hub | `../page-reports/ui-003-operations.md` | `operations-hub.md` | `../target-images/target/operations-hub-target.md` |
| Governance Inbox | `../page-reports/ui-004-governance-inbox.md` | `governance-inbox.md` | `../target-images/target/governance-inbox-target.md` |
| Customer Review Workspace | `../page-reports/ui-006-customer-review-workspace.md` | `customer-review-workspace.md` | `../target-images/target/customer-review-workspace-target.md` |
| Audit Log | `../page-reports/ui-008-audit-log.md` | `audit-log.md` | `../target-images/target/audit-log-target.md` |
| Restore Safety Workflow | `../page-reports/ui-014-restore-runs.md` | `restore-safety-workflow.md` | `../target-images/target/restore-safety-workflow-target.md` |
| Provider Readiness | `../page-reports/ui-009-provider-connections.md` | `provider-readiness.md` | `../target-images/target/provider-readiness-target.md` |
| Baseline Compare / Drift | `../page-reports/ui-015-baseline-compare.md` | `baseline-compare-drift.md` | `../target-images/target/baseline-compare-drift-target.md` |
## Reading Order
1. Start with `strategic-target-image-shortlist.md` for selection rationale and deferred surfaces.
2. Review the premium reference set in `../target-images/reference/spec-325-premium-reference/`.
3. Read the brief for the selected surface.
4. Review the target image sidecar before looking at the PNG target image.
5. Treat conceptual target elements as follow-up verification requirements, not as implemented product claims.
## Premium Visual Direction
The accepted visual direction is the user-provided reference set plus the regenerated premium dark target PNGs. The first generated target images should be treated as structure/content scaffolding only, not the final product look.
Light mode remains expected because Filament supports it by default; the dark target images carry the primary premium visual direction for Spec 325.
## Repo-Truth Labels
Briefs and image sidecars use the Spec 325 allowed labels only:
- `repo-verified`
- `plausible-existing`
- `foundation-only`
- `spec-only`
- `conceptual-future-state`
- `unknown`
## Runtime Posture
No Filament, Livewire, Blade, route, provider, policy, migration, test, queue, scheduler, storage, or business-logic behavior is changed by these artifacts.

134
docs/ui-ux-enterprise-audit/target-experience-briefs/audit-log.md Normal file
View File

@ -0,0 +1,134 @@
# Audit Log Target Experience Brief
## Metadata
| Field | Value |
| --- | --- |
| Surface ID | UI-025 |
| Route | `/admin/audit-log` |
| Source screenshot | `../screenshots/desktop/ui-008-audit-log.png` |
| Source page report | `../page-reports/ui-008-audit-log.md` |
| Target sidecar | `../target-images/target/audit-log-target.md` |
| Primary persona | Auditor / security reviewer |
| Secondary personas | Workspace owner, support reviewer, compliance reviewer |
| Repo-truth posture | Source route and screenshot are `repo-verified`; target composition is direction only. |
## Current-State Snapshot
The page is clearly an audit log. The report says its product role should be audit evidence first and diagnostics second, with explicit filters and no raw payload dominance.
## Current-State Productization Problems
- Event history can read as raw logs instead of proof.
- Selected-event detail must respect active workspace/environment filters.
- Customer/auditor export language requires dedicated review.
## Target User Promise
In five seconds, an auditor can see what happened, who did it, when it happened, what scope it affected, and where the evidence detail is.
## First-Five-Seconds Target
Show audit proof posture, filter scope, selected event summary, and evidence detail path before raw metadata.
## Primary Decision
Does the current audit scope contain the event proof needed for review?
## Primary Action
Inspect event proof.
## Secondary Actions
Filter events, export scoped audit evidence, open affected record, reveal raw metadata.
## Target Information Hierarchy
1. Workspace/environment filter scope.
2. Audit event proof summary.
3. Actor/action/target/outcome/timestamp.
4. Selected event evidence.
5. Export/share safety.
6. Raw metadata.
## Main-View Keep / Promote / Simplify
| Treatment | Elements |
| --- | --- |
| Keep | Action, actor, target, workspace/environment, timestamp, outcome. |
| Promote | Filter scope, selected event proof, export-readiness note. |
| Simplify | Raw metadata, dense payload fields, debug-only identifiers. |
## Detail Drawer Treatment
Event drawer should show human-readable proof first, scope and entitlement context second, and raw metadata in a collapsed support section.
## Advanced/Admin Treatment
Export and raw inspection require explicit scope and capability review. Support-only details should remain gated.
## Hidden/Removed Default Elements
Hide raw payloads, fingerprints, provider internal errors, and unsupported customer-facing claims.
## Target Layout Direction
Use a proof ledger layout: filter bar, event timeline/list, selected proof panel, and evidence/export rail.
## Visual Target Direction
Dark audit surface with high text contrast, sand dividers, violet evidence links, amber for attention, and neutral outcome labels until verified.
## Status/Trust Model
Separate event outcome, export readiness, data completeness, and scope filter state. Do not imply compliance certification.
## Dangerous Actions
No destructive action should be visible. Export requires tenant-safe filtering, authorization, redaction, and audit in later implementation.
## Customer-Safe Review Notes
Auditor-facing variants must avoid raw diagnostics and unsupported compliance language. Customer exports must be scoped and redacted.
## Workspace/Environment Context
Workspace is explicit. Environment filter state must remain visible in list and selected detail.
## Empty / Loading / Error States
Empty state should say no audit events match the active scope. Loading should preserve filters. Error state should avoid leaking raw exception detail.
## Accessibility Notes
Event status and scope must be text-readable. Timeline order must be understandable by screen readers.
## Repo-Truth Classification
| Target element | Classification | Notes |
| --- | --- | --- |
| Audit route and screenshot | repo-verified | Spec 323 browser pass reached the route. |
| AuditLog fields | repo-verified | Existing model and page report concepts. |
| Selected proof panel | plausible-existing | Uses current event data with new hierarchy. |
| Export readiness | foundation-only | Must be verified against existing export/report behavior. |
| Compliance-ready claims | unknown | Must not be stated without separate proof. |
## Screenshot-Anchored Image Prompt
Start from `ui-008-audit-log.png`. Create a target design direction, not runtime implementation. Preserve audit event review. Show workspace/environment scope, selected event proof, actor/action/target/outcome/time, evidence link, export-scope note, and collapsed raw metadata. Keep customer/auditor language safe. Avoid generic SaaS dashboards, fake compliance claims, green success without verification, placeholder text, raw metadata dominance, and runtime implementation claims.
## Implementation Pattern Requirements
- Scope filters remain visible.
- Event proof is human-readable first.
- Raw metadata is progressive disclosure.
- Export/share actions are authorized, scoped, redacted, and audited.
## Later Implementation Candidate
Evidence and review pack consumption productization.
## Non-Goals For Later Implementation
Do not introduce compliance certification language or broad audit export behavior without separate requirements.

134
docs/ui-ux-enterprise-audit/target-experience-briefs/baseline-compare-drift.md Normal file
View File

@ -0,0 +1,134 @@
# Baseline Compare / Drift Target Experience Brief
## Metadata
| Field | Value |
| --- | --- |
| Surface ID | UI-061 |
| Route | `/admin/workspaces/{workspace}/environments/{environment}/baseline-compare` |
| Source screenshot | `../screenshots/desktop/ui-015-baseline-compare-blocked-404.png` |
| Source page report | `../page-reports/ui-015-baseline-compare.md` |
| Target sidecar | `../target-images/target/baseline-compare-drift-target.md` |
| Primary persona | Governance operator |
| Secondary personas | Environment operator, manager, auditor |
| Repo-truth posture | Route is `repo-verified`; browser review was blocked by fixture state. Target composition is direction only. |
## Current-State Snapshot
The route is present but local fixture variants returned 404, so the actual page was not evaluated in browser. The page remains strategic because it should show assignment, compare state, evidence gaps, and required governance action.
## Current-State Productization Problems
- Actual compare state was not browser-reviewed.
- Assignment, latest result, evidence gaps, and next action need a target hierarchy.
- Drift decision content must avoid raw diff noise as the first read.
## Target User Promise
In five seconds, an operator knows what baseline this environment is compared against, what drift matters, and what decision is required.
## First-Five-Seconds Target
Show assigned baseline, compare freshness, drift impact summary, evidence gaps, and one primary decision action.
## Primary Decision
Review drift, accept exception, assign owner, or run compare.
## Primary Action
Review drift impact.
## Secondary Actions
Run compare, open baseline profile, inspect evidence gaps, create exception, open operation.
## Target Information Hierarchy
1. Environment and assigned baseline.
2. Compare freshness and readiness.
3. Drift impact summary.
4. Required decision.
5. Evidence gaps.
6. Diff details and raw payloads.
## Main-View Keep / Promote / Simplify
| Treatment | Elements |
| --- | --- |
| Keep | Environment route, baseline assignment, compare result, operation link. |
| Promote | Drift impact, evidence gap, owner/action, compare recency. |
| Simplify | Raw diff rows, low-level setting IDs, generic success/failure badges. |
## Detail Drawer Treatment
Drift drawer should show affected policy/control, expected vs observed, impact, evidence, owner, and decision actions. Raw diff JSON stays collapsed.
## Advanced/Admin Treatment
Baseline reassignment, capture, compare now, and exception actions need authorization, confirmation where high impact, audit, and OperationRun continuity.
## Hidden/Removed Default Elements
Hide raw JSON diffs, internal setting IDs, provider payloads, and unsupported compliance claims from first view.
## Target Layout Direction
Use a drift decision workbench: baseline context header, compare readiness strip, impact clusters, evidence gaps, and detail drawer.
## Visual Target Direction
Dark governance surface with amber for review-needed drift, coral for blocked/unsafe gaps, violet evidence links, and mint only for verified compare readiness or permitted actions.
## Status/Trust Model
Separate assignment state, compare freshness, drift severity, evidence completeness, and operation execution state.
## Dangerous Actions
Compare now, capture baseline, assign baseline, or accept exception are high impact. Later implementation must enforce authorization, confirmation where required, audit, and OperationRun links.
## Customer-Safe Review Notes
Customer-facing summaries should explain impact and accepted risk without raw diff details or internal reason families.
## Workspace/Environment Context
Workspace and environment are visible. The target baseline and source of comparison must be explicit before actions.
## Empty / Loading / Error States
Empty state should explain that no baseline assignment or compare result is available and offer one safe setup or compare action. Loading preserves environment context. Error state distinguishes unauthorized/not-found from missing compare data.
## Accessibility Notes
Drift severity and evidence gap state need text labels. Diff drawers must preserve keyboard navigation.
## Repo-Truth Classification
| Target element | Classification | Notes |
| --- | --- | --- |
| Baseline compare route | repo-verified | Route is present, fixture returned 404. |
| BaselineProfile and OperationRun concepts | repo-verified | Existing model inventory includes both. |
| Drift impact clusters | plausible-existing | Must map to actual compare output later. |
| Evidence gap scoring | foundation-only | Product direction only until data mapping is verified. |
| Exception workflow from compare drawer | conceptual-future-state | Must be separately specified. |
## Screenshot-Anchored Image Prompt
Start from `ui-015-baseline-compare-blocked-404.png` as blocked current evidence. Create a target design direction, not runtime implementation. Preserve environment baseline compare purpose. Show assigned baseline, compare freshness, drift impact, evidence gaps, primary Review drift impact action, secondary Run compare action, OperationRun proof link, and collapsed raw diff detail. Avoid generic SaaS dashboards, fake compliance claims, green success without verification, placeholder text, raw diff noise as default, and runtime implementation claims.
## Implementation Pattern Requirements
- Environment and assigned baseline are visible before actions.
- Drift impact appears before raw diff.
- Compare/run links use OperationRun patterns.
- Customer-safe summaries hide raw provider payloads.
## Later Implementation Candidate
Drift/Baseline decision experience.
## Non-Goals For Later Implementation
Do not invent new drift states, evidence scores, or exception workflows without repo/data verification and a separate spec if needed.

134
docs/ui-ux-enterprise-audit/target-experience-briefs/customer-review-workspace.md Normal file
View File

@ -0,0 +1,134 @@
# Customer Review Workspace Target Experience Brief
## Metadata
| Field | Value |
| --- | --- |
| Surface ID | UI-038 |
| Route | `/admin/reviews/workspace` |
| Source screenshot | `../screenshots/desktop/ui-006-customer-review-workspace.png` |
| Source page report | `../page-reports/ui-006-customer-review-workspace.md` |
| Target sidecar | `../target-images/target/customer-review-workspace-target.md` |
| Primary persona | Customer reviewer / auditor |
| Secondary personas | MSP manager, workspace owner, evidence reviewer |
| Repo-truth posture | Source route and screenshot are `repo-verified`; target composition is direction only. |
## Current-State Snapshot
This is the highest customer-safe productization candidate. The report says it must answer what the customer can trust, what changed, which risks are accepted, which evidence supports the state, and what happens next.
## Current-State Productization Problems
- Customer-safe language and data exposure need an explicit target.
- Evidence and accepted-risk meaning need first-read clarity without raw diagnostics.
- Review-pack and decision outputs need proof context and shareability boundaries.
## Target User Promise
In five seconds, a customer or auditor knows whether the review is ready to trust, what needs attention, and where the evidence can be inspected.
## First-Five-Seconds Target
Show review readiness, evidence freshness, accepted-risk summary, management-readable next action, and review pack availability.
## Primary Decision
Is this workspace review ready to share, or does it need operator follow-up?
## Primary Action
Open review pack.
## Secondary Actions
Review accepted risks, inspect evidence, view decision history, request update.
## Target Information Hierarchy
1. Customer-safe review posture.
2. Evidence freshness and coverage.
3. Accepted risk summary.
4. Review pack and export readiness.
5. Management-readable next action.
6. Operator diagnostics hidden by default.
## Main-View Keep / Promote / Simplify
| Treatment | Elements |
| --- | --- |
| Keep | Review readiness, evidence basis, accepted risks, review-pack/download concepts. |
| Promote | Customer-safe summary, evidence freshness, safe share/export state. |
| Simplify | Internal IDs, raw OperationRuns, provider diagnostics, low-level reason ownership. |
## Detail Drawer Treatment
Evidence drawer should show customer-readable proof first, operator diagnostics second, and raw/support details only behind explicit capability-gated disclosure.
## Advanced/Admin Treatment
Publish, export, regenerate, and diagnostic actions stay behind authorized operator modes, not default customer review.
## Hidden/Removed Default Elements
Hide raw JSON, run payloads, provider error details, internal fingerprints, and support-only terminology.
## Target Layout Direction
Use a bright/light review-consumption variant and a dark operator companion. The first viewport should read like an audit-ready workspace summary, not an admin list.
## Visual Target Direction
Light variant uses ivory surface, graphite text, sand dividers, mint for verified evidence readiness only when backed by proof, amber for attention, and violet for evidence paths. Dark variant preserves the same hierarchy for operator review.
## Status/Trust Model
Separate review readiness, evidence freshness, accepted risk, and export/share state. No green success unless proof is verified.
## Dangerous Actions
Export, publish, regenerate, or share actions require scope explanation, authorization, audit logging, and customer-safe redaction in later implementation.
## Customer-Safe Review Notes
This is customer/auditor-facing. Default copy must be plain language, evidence-backed, and free of raw provider diagnostics or implementation terms.
## Workspace/Environment Context
Workspace scope is explicit. Environment-specific evidence summaries must show environment names and must not leak inaccessible tenants.
## Empty / Loading / Error States
Empty state should explain that no review pack is ready and offer an operator follow-up path. Loading should show review context. Error state must avoid exposing internal diagnostics to customer mode.
## Accessibility Notes
Evidence freshness, accepted risk, and readiness must have text labels. Export/share controls must be clear about file/action scope.
## Repo-Truth Classification
| Target element | Classification | Notes |
| --- | --- | --- |
| Customer review route and screenshot | repo-verified | Spec 323 browser pass reached the route. |
| Review/evidence/accepted-risk concepts | plausible-existing | Models exist, exact surface mapping needs later spec. |
| Customer-safe review pack card | foundation-only | Review pack concepts exist but exact export UX needs validation. |
| Customer mode separation | spec-only | Required target direction, not current runtime proof. |
| External customer share workflow | conceptual-future-state | Must be separately specified before implementation. |
## Screenshot-Anchored Image Prompt
Start from `ui-006-customer-review-workspace.png`. Create a target design direction, not runtime implementation. Preserve customer review consumption. Show review readiness, evidence freshness, accepted-risk summary, review-pack availability, management-readable next action, and hidden diagnostics. Use customer-safe language. Provide dark and light review variants. Avoid generic SaaS dashboards, fake compliance claims, green success without verified evidence, placeholder text, raw OperationRun/provider diagnostics, and runtime implementation claims.
## Implementation Pattern Requirements
- Customer-readable decision content first.
- Operator diagnostics second.
- Raw/support evidence third and gated.
- Export/share actions authorized, audited, and redacted.
## Later Implementation Candidate
Customer Review Workspace productization.
## Non-Goals For Later Implementation
Do not create public customer portals, external sharing, or compliance claims without a separate product/security spec.

134
docs/ui-ux-enterprise-audit/target-experience-briefs/environment-dashboard.md Normal file
View File

@ -0,0 +1,134 @@
# Environment Dashboard Target Experience Brief
## Metadata
| Field | Value |
| --- | --- |
| Surface ID | UI-011 |
| Route | `/admin/workspaces/{workspace}/environments/{environment}` |
| Source screenshot | `../screenshots/desktop/ui-002-environment-dashboard.png` |
| Source page report | `../page-reports/ui-002-environment-dashboard.md` |
| Target sidecar | `../target-images/target/environment-dashboard-target.md` |
| Primary persona | Environment operator |
| Secondary personas | Manager, governance reviewer, support reviewer |
| Repo-truth posture | Source route and screenshot are `repo-verified`; target composition is direction only. |
## Current-State Snapshot
The page makes environment context visible and exposes backup, recovery, verification, reporting, operations, and navigation widgets. The report says too many posture and evidence signals compete for the first decision.
## Current-State Productization Problems
- Backup truth, recovery readiness, verification, and operations sit at similar visual weight.
- Dangerous downstream actions do not have a single visible safety hierarchy from this landing state.
- Evidence proof exists conceptually but is not separated from health and navigation.
## Target User Promise
In five seconds, an operator knows whether this environment is ready, what blocks readiness, and which safe next action is appropriate.
## First-Five-Seconds Target
Show environment posture, blocking reason, latest proof, and one recommended next action before secondary domain cards.
## Primary Decision
Is this environment ready, blocked, stale, or requiring review?
## Primary Action
Review readiness blockers.
## Secondary Actions
Open backup sets, open restore runs, compare baseline, inspect operations, review provider readiness.
## Target Information Hierarchy
1. Environment context and readiness posture.
2. Blocking reason and impact.
3. Primary next action.
4. Backup/recovery proof.
5. Governance and operation drilldowns.
6. Diagnostics.
## Main-View Keep / Promote / Simplify
| Treatment | Elements |
| --- | --- |
| Keep | Environment name, workspace context, backup health, recovery readiness, operations. |
| Promote | Readiness blocker, evidence freshness, mutation scope note for high-impact actions. |
| Simplify | Equal-weight widgets, repeated links, dense verification diagnostics. |
## Detail Drawer Treatment
Selected blocker drawer should show scope, reason, affected evidence, latest run, and remediation path. Raw Graph/provider diagnostics remain collapsed.
## Advanced/Admin Treatment
Provider diagnostics, raw report payloads, and advanced permission checks stay secondary and capability-gated where needed.
## Hidden/Removed Default Elements
Hide raw IDs, provider payloads, and low-level verification details from first view.
## Target Layout Direction
Use an environment command header, a readiness decision lane, and compact proof cards. Domain modules sit below as action-oriented summaries.
## Visual Target Direction
Dark operational surface with warm neutral panels, amber/coral for blocked or risky posture, mint only for verified safe actions, and violet evidence links.
## Status/Trust Model
Separate readiness, backup recency, recovery evidence, execution state, and governance result. Do not collapse them into one health badge.
## Dangerous Actions
Backup, restore, provider fixes, and compare actions must show whether they change TenantPilot only, the Microsoft tenant, or simulation-only state before execution.
## Customer-Safe Review Notes
Operator-facing default. Customer-safe exports must hide raw diagnostics and explain evidence freshness in plain language.
## Workspace/Environment Context
Both workspace and environment are visible in the header and on every actionable blocker.
## Empty / Loading / Error States
Empty state should explain that no environment evidence is available yet and offer one setup/check action. Loading state should keep context visible. Error state distinguishes data load failure from provider verification failure.
## Accessibility Notes
Status labels need text and icon support. Readiness blockers must be navigable as list items, not only cards.
## Repo-Truth Classification
| Target element | Classification | Notes |
| --- | --- | --- |
| Environment route and screenshot | repo-verified | Spec 323 browser pass reached the route. |
| Backup and recovery widgets | repo-verified | Present in report. |
| Readiness blocker lane | plausible-existing | Synthesizes existing signals into target hierarchy. |
| Mutation-scope labels | foundation-only | Required by constitution, exact runtime copy needs later spec. |
| Detailed provider diagnostics | conceptual-future-state | Must be verified before implementation. |
## Screenshot-Anchored Image Prompt
Start from `ui-002-environment-dashboard.png`. Create a target design direction, not runtime implementation. Preserve the environment command-surface purpose. Show environment readiness, blocker reason, primary action, backup/recovery proof, operation traceability, and secondary domain drilldowns. Keep technical diagnostics secondary. Show workspace and environment context. Avoid generic SaaS dashboards, fake compliance claims, green success without verification, placeholder text, decorative charts, and runtime implementation claims.
## Implementation Pattern Requirements
- One readiness decision header.
- Distinct status dimensions for readiness, backup, recovery, operation, and governance.
- Mutation scope visible for high-impact actions.
- Evidence and OperationRun links use shared patterns.
## Later Implementation Candidate
Workspace and Environment dashboard productization.
## Non-Goals For Later Implementation
Do not create new environment readiness persistence or status families unless a separate spec proves behavioral consequence.

134
docs/ui-ux-enterprise-audit/target-experience-briefs/governance-inbox.md Normal file
View File

@ -0,0 +1,134 @@
# Governance Inbox Target Experience Brief
## Metadata
| Field | Value |
| --- | --- |
| Surface ID | UI-028 |
| Route | `/admin/governance/inbox` |
| Source screenshot | `../screenshots/desktop/ui-004-governance-inbox.png` |
| Source page report | `../page-reports/ui-004-governance-inbox.md` |
| Target sidecar | `../target-images/target/governance-inbox-target.md` |
| Primary persona | Governance operator |
| Secondary personas | Manager, auditor, support reviewer |
| Repo-truth posture | Source route and screenshot are `repo-verified`; target composition is direction only. |
## Current-State Snapshot
The page is positioned as a decision queue. The report says it must make pending work, reason, owner, impact, and next action unmistakable.
## Current-State Productization Problems
- Queue-clearing action model is not sharp enough.
- Evidence and decision status can blend with diagnostics.
- Customer-safe downstream wording needs review before outputs feed reviews.
## Target User Promise
In five seconds, an operator knows which governance decision is waiting, why it matters, and which action resolves it.
## First-Five-Seconds Target
Show decision categories, overdue/age posture, one selected priority decision, evidence basis, and the recommended next action.
## Primary Decision
Approve, reject, accept risk, assign, or escalate the highest-priority decision item.
## Primary Action
Review decision.
## Secondary Actions
Assign owner, request evidence, open finding, open review context, filter by due state.
## Target Information Hierarchy
1. Governance queue posture.
2. Priority decision item.
3. Reason, impact, owner, due state.
4. Evidence basis.
5. Action options.
6. Diagnostics and history.
## Main-View Keep / Promote / Simplify
| Treatment | Elements |
| --- | --- |
| Keep | Pending decision type, impact, scope, owner, age, evidence links. |
| Promote | Recommended next action and why this item is first. |
| Simplify | Raw reason ownership, payload detail, and equal approve/reject/action buttons. |
## Detail Drawer Treatment
Decision drawer should show the item summary, evidence basis, actor history, customer-safe summary, and action consequences before any confirmation.
## Advanced/Admin Treatment
Policy, internal reason ownership, and raw payload diagnostics stay secondary and support-gated where needed.
## Hidden/Removed Default Elements
Hide raw JSON, fingerprints, internal reason families, and provider diagnostics from the default queue.
## Target Layout Direction
Use a decision workbench: queue filters on top, priority decision column, evidence/context column, and action drawer.
## Visual Target Direction
Dark decision surface with precise spacing, amber for due/attention, coral for blocked or risky decisions, mint only for verified permitted next action, and violet for evidence links.
## Status/Trust Model
Separate decision status, evidence completeness, risk/impact, and lifecycle age. Do not use a single "good/bad" badge.
## Dangerous Actions
Approve, reject, accept risk, close, or escalate actions must be authorized server-side, confirmation-gated where high impact, and audit logged in later implementation.
## Customer-Safe Review Notes
Queue copy can feed customer review summaries, but default operator diagnostics must remain hidden from customer-readable outputs.
## Workspace/Environment Context
Workspace context is visible. Environment-bound decisions must show environment and tenant-safe scope.
## Empty / Loading / Error States
Empty state should say no governance decisions need action and offer one link to decision register. Loading preserves filters. Error state states whether the queue, evidence, or entitlement context failed.
## Accessibility Notes
Decision priority must not rely on color. Action consequences should be screen-reader readable before confirmation.
## Repo-Truth Classification
| Target element | Classification | Notes |
| --- | --- | --- |
| Governance inbox route and screenshot | repo-verified | Spec 323 browser pass reached the route. |
| Decision queue concept | repo-verified | Page report confirms intent. |
| Recommended next action | plausible-existing | Needs domain mapping in later implementation. |
| Customer-safe summary | foundation-only | Required by product direction, exact copy needs validation. |
| Unified decision taxonomy | conceptual-future-state | Must not be created in this spec. |
## Screenshot-Anchored Image Prompt
Start from `ui-004-governance-inbox.png`. Create a target design direction, not runtime implementation. Preserve the governance decision queue. Show pending decision posture, selected priority item, reason, impact, owner, due state, evidence basis, and one primary Review decision action. Keep diagnostics secondary and customer-safe language visible. Avoid generic SaaS dashboard layouts, fake compliance claims, green success without verification, placeholder text, raw debug defaults, and runtime implementation claims.
## Implementation Pattern Requirements
- One dominant decision action.
- Evidence-first decision drawer.
- Capability-aware and audit-backed mutations.
- Customer-safe summary separated from operator diagnostics.
## Later Implementation Candidate
Governance Inbox decision experience.
## Non-Goals For Later Implementation
Do not implement a broad governance taxonomy or status framework unless later specs prove behavioral consequences.

134
docs/ui-ux-enterprise-audit/target-experience-briefs/operations-hub.md Normal file
View File

@ -0,0 +1,134 @@
# Operations Hub Target Experience Brief
## Metadata
| Field | Value |
| --- | --- |
| Surface ID | UI-016 |
| Route | `/admin/workspaces/{workspace}/operations` |
| Source screenshot | `../screenshots/desktop/ui-003-operations.png` |
| Source page report | `../page-reports/ui-003-operations.md` |
| Target sidecar | `../target-images/target/operations-hub-target.md` |
| Primary persona | Operations responder |
| Secondary personas | Manager, support reviewer, auditor |
| Repo-truth posture | Source route and screenshot are `repo-verified`; target composition is direction only. |
## Current-State Snapshot
The page reads as an operations monitor and exposes OperationRun execution truth. The page report says active work, terminal follow-up, and diagnostic history need a sharper split.
## Current-State Productization Problems
- Chronological run history can overpower the current operational decision.
- Execution state can be confused with governance health.
- Run detail, evidence, and result links need consistent hierarchy.
## Target User Promise
In five seconds, an operator knows what is running, what failed or needs follow-up, and where the run proof lives.
## First-Five-Seconds Target
Show an operation status strip for active, failed, partial, and completed runs, then a prioritized follow-up queue.
## Primary Decision
Which operation needs attention now?
## Primary Action
Open failed run.
## Secondary Actions
Filter runs, open related artifact, inspect diagnostics, retry where authorized and confirmed.
## Target Information Hierarchy
1. Workspace operations posture.
2. Attention-needed run queue.
3. Active run progress.
4. Recent terminal outcomes.
5. Evidence/artifact links.
6. Raw diagnostics.
## Main-View Keep / Promote / Simplify
| Treatment | Elements |
| --- | --- |
| Keep | Run list, status, timestamps, source workflow, links to run detail. |
| Promote | Failed/blocked follow-up, reason, affected environment, next action. |
| Simplify | Pure chronological table, raw events as first-read content, equal action buttons. |
## Detail Drawer Treatment
Run drawer should show status, outcome, summary counts, artifact links, initiator, tenant/environment scope, and diagnostics collapsed behind support detail.
## Advanced/Admin Treatment
Retry/cancel actions require capability-aware visibility, confirmation where high impact, and audit continuity. Raw logs stay support-gated.
## Hidden/Removed Default Elements
Hide copied payloads, provider raw errors, stack traces, and internal reason ownership from the default table.
## Target Layout Direction
Use a monitoring header, a left attention queue, an active-run progress area, and a right proof/diagnostics rail.
## Visual Target Direction
Dark operational console with subdued panels, amber/coral for follow-up states, violet proof links, and mint only for verified safe terminal outcomes or permitted actions.
## Status/Trust Model
Keep execution status, operation outcome, data completeness, and governance result separate.
## Dangerous Actions
Retry, cancel, rerun, or execute-related actions must use action handlers, authorization, confirmation where relevant, and OperationRun/audit continuity in later implementation.
## Customer-Safe Review Notes
Not customer-facing by default. Customer-readable operation summaries must hide raw diagnostics and use evidence/result links.
## Workspace/Environment Context
Workspace context is visible. Environment-bound runs must show environment and entitlement-safe links.
## Empty / Loading / Error States
Empty state should say no operations are currently recorded and link to relevant workflow start points only when permitted. Loading should preserve filters. Error state distinguishes failed run loading from app runtime failure.
## Accessibility Notes
Run status must be text-readable, sortable, and not color-only. Focus order should prioritize attention-needed runs.
## Repo-Truth Classification
| Target element | Classification | Notes |
| --- | --- | --- |
| Operations route and screenshot | repo-verified | Spec 323 browser pass reached the route. |
| OperationRun records | repo-verified | Existing model and source surface. |
| Attention-needed grouping | plausible-existing | Derived from run status/outcome, exact grouping needs later spec. |
| Artifact proof rail | foundation-only | OperationRun links exist, exact artifact mapping needs verification. |
| Retry/cancel action set | unknown | Must be verified per operation family. |
## Screenshot-Anchored Image Prompt
Start from `ui-003-operations.png`. Create a target design direction, not runtime implementation. Preserve operations monitoring. Show active runs, failed/partial follow-up, reason, environment scope, primary open-run action, and evidence/artifact links. Keep raw diagnostics secondary. Make execution truth visibly separate from governance health. Avoid generic blue SaaS, fake compliance claims, green success without verification, placeholder text, decorative charts, and runtime implementation claims.
## Implementation Pattern Requirements
- Reuse central OperationRun UX contracts.
- Use consistent run status and outcome grammar.
- Keep progress in widgets/run detail, not as broad product health.
- Hide raw/support diagnostics by default.
## Later Implementation Candidate
Operations Hub productization.
## Non-Goals For Later Implementation
Do not create a separate operation notification or run-link language outside the shared OperationRun UX path.

134
docs/ui-ux-enterprise-audit/target-experience-briefs/provider-readiness.md Normal file
View File

@ -0,0 +1,134 @@
# Provider Readiness Target Experience Brief
## Metadata
| Field | Value |
| --- | --- |
| Surface IDs | UI-072, UI-073 |
| Route | `/admin/provider-connections` plus create/detail family |
| Source screenshot | `../screenshots/desktop/ui-009-provider-connections.png` |
| Source page report | `../page-reports/ui-009-provider-connections.md` |
| Target sidecar | `../target-images/target/provider-readiness-target.md` |
| Primary persona | Provider administrator |
| Secondary personas | Workspace owner, support reviewer, security reviewer |
| Repo-truth posture | Source route and screenshot are `repo-verified`; target composition is direction only. |
## Current-State Snapshot
Provider Connections is the main integration authority. The report says it should make connection health, scope, credentials/consent state, and safe next action legible without exposing secrets or raw provider errors by default.
## Current-State Productization Problems
- Health and permission readiness need stronger hierarchy than raw integration detail.
- Dangerous provider actions need confirmation and audit treatment.
- Provider-specific terms must not become platform-core truth.
## Target User Promise
In five seconds, an admin knows whether the provider connection is ready, what permission or verification gap exists, and which safe next action resolves it.
## First-Five-Seconds Target
Show provider readiness posture, target scope, missing permission or verification gap, last verification, and a single safe action.
## Primary Decision
Is the provider connection ready for TenantPilot operations?
## Primary Action
Resolve readiness gap.
## Secondary Actions
Verify connection, review permissions, rotate credential, open diagnostics, create connection.
## Target Information Hierarchy
1. Workspace-owned provider context.
2. Readiness posture.
3. Required permission or verification gap.
4. Safe next action.
5. Last verification and audit trace.
6. Diagnostics and raw provider detail.
## Main-View Keep / Promote / Simplify
| Treatment | Elements |
| --- | --- |
| Keep | Provider, connection type, target scope, health, permissions, last verification. |
| Promote | Readiness gap, safe next action, credential/consent boundary. |
| Simplify | Raw provider names as platform truth, secrets, raw errors, equal destructive actions. |
## Detail Drawer Treatment
Readiness drawer should show missing scope, affected TenantPilot capability, last verification, safe remediation path, and audit trace. Raw provider diagnostics stay secondary.
## Advanced/Admin Treatment
Credential rotation, disconnect, disable, delete, and re-consent actions require capability-aware visibility, confirmation, audit, and recovery guidance.
## Hidden/Removed Default Elements
Hide secrets, raw credential payloads, raw provider errors, tenant IDs, and debug-only claims from the first view.
## Target Layout Direction
Use a readiness workbench: connection summary, permissions/gaps, safe action, verification history, and diagnostics drawer.
## Visual Target Direction
Dark trust surface with warm panels, amber for missing permission, coral for disconnected/unsafe state, mint only for verified readiness, and no vendor-brand domination.
## Status/Trust Model
Separate connection reachability, permission completeness, credential lifecycle, verification freshness, and TenantPilot capability readiness.
## Dangerous Actions
Rotate credential, disconnect/disable, delete, and re-consent are high impact. Later implementation must include authorization, confirmation, audit, and redacted logging.
## Customer-Safe Review Notes
Internal/operator surface. Customer-facing evidence can state readiness summary only, not secrets, raw scopes, or provider errors.
## Workspace/Environment Context
Workspace ownership is explicit. Environment impact should be shown only when repo-verified.
## Empty / Loading / Error States
Empty state should explain no provider connection exists and offer one setup action. Loading preserves workspace context. Error state separates TenantPilot validation failure from provider response failure.
## Accessibility Notes
Readiness and permission gaps require text labels. Dangerous actions need clear modal headings and descriptions.
## Repo-Truth Classification
| Target element | Classification | Notes |
| --- | --- | --- |
| Provider connection route and screenshot | repo-verified | Spec 323 browser pass reached the route. |
| ProviderConnection model | repo-verified | Existing model inventory includes it. |
| Permission readiness summary | plausible-existing | Must map to existing required permissions/contracts. |
| Capability impact copy | foundation-only | Constitution requires deterministic capabilities; exact mapping needs later spec. |
| Multi-provider neutrality in visuals | spec-only | Direction to avoid provider leakage. |
## Screenshot-Anchored Image Prompt
Start from `ui-009-provider-connections.png`. Create a target design direction, not runtime implementation. Preserve provider connection management. Show provider readiness, target scope, missing permission or verification gap, last verification, safe next action, audit trace, and collapsed diagnostics. Avoid exposing secrets. Avoid generic SaaS dashboards, fake compliance claims, green success without verification, placeholder text, raw provider errors by default, Microsoft-shaped platform-core claims, and runtime implementation claims.
## Implementation Pattern Requirements
- Separate reachability, permission, credential, and verification state.
- Capability-aware next action.
- Dangerous provider actions confirmed, authorized, audited, and redacted.
- Provider-specific semantics stay bounded to provider-owned seams.
## Later Implementation Candidate
Provider onboarding/readiness UX cleanup.
## Non-Goals For Later Implementation
Do not create a generic provider framework or new provider taxonomy unless at least two real providers require it.

135
docs/ui-ux-enterprise-audit/target-experience-briefs/restore-safety-workflow.md Normal file
View File

@ -0,0 +1,135 @@
# Restore Safety Workflow Target Experience Brief
## Metadata
| Field | Value |
| --- | --- |
| Surface IDs | UI-053, UI-054 |
| Route | `/admin/workspaces/{workspace}/environments/{environment}/restore-runs` plus create/view family |
| Source screenshot | `../screenshots/desktop/ui-014-restore-runs.png` |
| Source page report | `../page-reports/ui-014-restore-runs.md` |
| Target sidecar | `../target-images/target/restore-safety-workflow-target.md` |
| Primary persona | Restore operator / approver |
| Secondary personas | Workspace owner, auditor, support reviewer |
| Repo-truth posture | Route is `repo-verified`; browser review was blocked by capability/state. Target composition is direction only. |
## Current-State Snapshot
The browser pass could not evaluate the product page because restore capability/state was unavailable. The page remains strategic because restore is the highest-risk operator workflow in the product.
## Current-State Productization Problems
- Actual workflow hierarchy was not reviewed in browser.
- Preview, validation, execution, result, and evidence truth need separation.
- Restore must not look like an ordinary create/list action.
## Target User Promise
In five seconds, a restore operator understands the restore source, affected scope, safety gate state, risk, required confirmation, and proof trail.
## First-Five-Seconds Target
Show a safety workflow with source backup, target environment, simulation/preview state, blockers, explicit confirmation state, and OperationRun/evidence result.
## Primary Decision
Is this restore safe and authorized to execute?
## Primary Action
Review restore preview.
## Secondary Actions
Adjust scope, run validation, open source backup, open operation, inspect evidence, cancel request.
## Target Information Hierarchy
1. Restore scope and mutation target.
2. Source backup and target environment.
3. Safety gates and validation.
4. Preview impact.
5. Confirmation requirements.
6. Execution result and evidence.
7. Raw diagnostics.
## Main-View Keep / Promote / Simplify
| Treatment | Elements |
| --- | --- |
| Keep | Restore run history, source backup, target environment, status, operation link. |
| Promote | Mutation scope, safety gates, preview result, hard confirmation. |
| Simplify | Generic list/create framing, raw provider responses, equal execute/navigation buttons. |
## Detail Drawer Treatment
Restore drawer should show safety gate evidence, item-level preview summary, conflict warnings, confirmation text, and post-run evidence. Diagnostics remain collapsed.
## Advanced/Admin Treatment
Raw provider results, retry controls, override paths, and partial-failure diagnostics are support/operator-only and capability-gated.
## Hidden/Removed Default Elements
Hide raw payloads, provider response dumps, and debug-only IDs from first view.
## Target Layout Direction
Use a stepper/wizard-like safety flow: configure scope, run validation, review preview, hard confirm, execute, inspect evidence.
## Visual Target Direction
Dark high-friction workflow with coral for irreversible risk, amber for validation gaps, mint only for simulation-safe or verified allowed steps, and strong scope callouts.
## Status/Trust Model
Separate simulation/preview state, validation completeness, execution status, result truth, and evidence availability.
## Dangerous Actions
Restore execution is destructive/high-impact. Later implementation must include dry-run/preview, explicit confirmation, authorization, audit logging, OperationRun continuity, and post-run evidence.
## Customer-Safe Review Notes
Post-restore evidence summaries may be customer/auditor-facing, but raw provider diagnostics and internal remediation notes must remain hidden.
## Workspace/Environment Context
Workspace and target environment are always visible. The source backup and affected resource scope must be visible before execution.
## Empty / Loading / Error States
Empty state should explain no restore runs exist and show safe prerequisites, not a casual execute CTA. Loading preserves scope. Error state distinguishes validation failure from execution failure.
## Accessibility Notes
The safety stepper must expose step state in text. Confirmation copy must be readable before the irreversible action.
## Repo-Truth Classification
| Target element | Classification | Notes |
| --- | --- | --- |
| Restore route family | repo-verified | Route exists, browser fixture blocked. |
| RestoreRun model and OperationRun relation | repo-verified | Existing model inventory includes RestoreRun and OperationRun. |
| Safety gate stepper | foundation-only | Required by product safety rules, exact runtime steps need later spec. |
| Hard confirmation copy | spec-only | Target direction only. |
| Partial restore conflict model | conceptual-future-state | Must be verified before implementation. |
## Screenshot-Anchored Image Prompt
Start from `ui-014-restore-runs.png` as blocked current evidence. Create a target design direction, not runtime implementation. Preserve restore execution history and restore-create/view workflow purpose. Show source backup, target environment, mutation scope, safety gates, preview impact, confirmation requirement, OperationRun link, and evidence result. Make restore visibly high-friction. Avoid generic SaaS dashboards, fake compliance claims, green success without verification, placeholder text, casual destructive actions, raw diagnostics by default, and runtime implementation claims.
## Implementation Pattern Requirements
- Restore flow uses configuration, safety checks/simulation, preview, hard confirmation, execute, evidence result.
- Authorization and audit are server-side.
- OperationRun continuity is visible but not the only proof.
- Customer-safe post-result summary separates diagnostics.
## Later Implementation Candidate
Restore safety UX productization.
## Non-Goals For Later Implementation
Do not implement restore execution semantics, provider writes, or compatibility behavior from this target artifact alone.

66
docs/ui-ux-enterprise-audit/target-experience-briefs/strategic-target-image-shortlist.md Normal file
View File

@ -0,0 +1,66 @@
# Strategic Target Image Shortlist
| Field | Value |
| --- | --- |
| Spec | Spec 325 - Screenshot-Anchored Strategic Target Images & Experience Briefs |
| Selection date | 2026-05-17 |
| Branch | `325-screenshot-anchored-strategic-target-images` |
| Base commit inspected | `e35706b8` |
| Source baseline | Spec 323 audit artifacts and Spec 324 UI coverage guardrails |
| Runtime posture | Docs/image artifacts only |
| Premium visual reference | `../target-images/reference/spec-325-premium-reference/` |
## Selection Rationale
The shortlist selects 9 P0/P1 surfaces from the 44 strategic rows in `../strategic-surfaces.md`. This stays within the Spec 325 maximum of 10 surfaces while covering the highest-value product narratives: workspace entry, environment posture, operations truth, governance decisions, customer-safe review, audit proof, restore safety, provider readiness, and drift/baseline decisions.
All 44 strategic rows are not covered because many rows are detail variants, CRUD-adjacent pages, repeated domain lists, system-plane surfaces, or pages that require a separate seeded fixture or pattern-library pass. Spec 325 is a target-image direction wave, not an all-surface redesign.
## Premium Visual Reference Decision
The user accepted four premium visual references as final enough for the Tenantial target direction:
- `../target-images/reference/spec-325-premium-reference/platform-overview-premium-reference.png`
- `../target-images/reference/spec-325-premium-reference/governance-inbox-premium-reference.png`
- `../target-images/reference/spec-325-premium-reference/backup-restore-premium-reference.png`
- `../target-images/reference/spec-325-premium-reference/evidence-audit-premium-reference.png`
These references supersede the first generated Spec 325 PNGs as visual-quality calibration. The earlier generated images remain useful as IA/content scaffolds only. The accepted reference direction is dark, dense, calm, premium, enterprise-grade, sidebar/topbar anchored, and workbench-oriented.
Runtime implementation must not copy the reference images blindly. Concrete metrics, dates, entities, success states, dangerous-action affordances, and shown actions are conceptual until repo-verified.
## Selected Surfaces
| ID | Surface | Priority | Persona | Source screenshot | Source report | Target brief | Target images | Repo-truth notes |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| UI-001/UI-002 | Workspace Overview | P0 | Workspace owner / MSP operator | `../screenshots/desktop/ui-001-workspace-overview.png` | `../page-reports/ui-001-workspace-overview.md` | `workspace-overview.md` | `../target-images/target/workspace-overview-target-dark.png`, `../target-images/target/workspace-overview-target-light.png` | Repo-verified route and screenshot; target simplifies competing next actions. |
| UI-011 | Environment Dashboard | P0 | Environment operator | `../screenshots/desktop/ui-002-environment-dashboard.png` | `../page-reports/ui-002-environment-dashboard.md` | `environment-dashboard.md` | `../target-images/target/environment-dashboard-target-dark.png`, `../target-images/target/environment-dashboard-target-light.png` | Repo-verified route and screenshot; target separates posture, proof, and diagnostics. |
| UI-016 | Operations Hub | P0 | Operations responder | `../screenshots/desktop/ui-003-operations.png` | `../page-reports/ui-003-operations.md` | `operations-hub.md` | `../target-images/target/operations-hub-target-dark.png`, `../target-images/target/operations-hub-target-light.png` | Repo-verified route and screenshot; target keeps execution truth separate from governance health. |
| UI-028 | Governance Inbox | P0 | Governance operator | `../screenshots/desktop/ui-004-governance-inbox.png` | `../page-reports/ui-004-governance-inbox.md` | `governance-inbox.md` | `../target-images/target/governance-inbox-target-dark.png`, `../target-images/target/governance-inbox-target-light.png` | Repo-verified route and screenshot; target makes the human decision moment explicit. |
| UI-038 | Customer Review Workspace | P0 | Customer reviewer / auditor | `../screenshots/desktop/ui-006-customer-review-workspace.png` | `../page-reports/ui-006-customer-review-workspace.md` | `customer-review-workspace.md` | `../target-images/target/customer-review-workspace-target-dark.png`, `../target-images/target/customer-review-workspace-target-light.png` | Repo-verified route and screenshot; target is customer-safe and evidence-first. |
| UI-025 | Audit Log | P0 | Auditor / security reviewer | `../screenshots/desktop/ui-008-audit-log.png` | `../page-reports/ui-008-audit-log.md` | `audit-log.md` | `../target-images/target/audit-log-target-dark.png`, `../target-images/target/audit-log-target-light.png` | Repo-verified route and screenshot; target turns raw event history into audit proof. |
| UI-053/UI-054 | Restore Safety Workflow | P0 | Restore operator / approver | `../screenshots/desktop/ui-014-restore-runs.png` | `../page-reports/ui-014-restore-runs.md` | `restore-safety-workflow.md` | `../target-images/target/restore-safety-workflow-target-dark.png`, `../target-images/target/restore-safety-workflow-target-light.png` | Route repo-verified but browser blocked by capability/state; target is constrained to safety workflow guidance. |
| UI-072/UI-073 | Provider Readiness | P0 | Provider administrator | `../screenshots/desktop/ui-009-provider-connections.png` | `../page-reports/ui-009-provider-connections.md` | `provider-readiness.md` | `../target-images/target/provider-readiness-target-dark.png`, `../target-images/target/provider-readiness-target-light.png` | Repo-verified route and screenshot; target focuses on connection health and permission readiness. |
| UI-061 | Baseline Compare / Drift | P0 | Governance operator | `../screenshots/desktop/ui-015-baseline-compare-blocked-404.png` | `../page-reports/ui-015-baseline-compare.md` | `baseline-compare-drift.md` | `../target-images/target/baseline-compare-drift-target-dark.png`, `../target-images/target/baseline-compare-drift-target-light.png` | Route repo-verified but browser blocked; target stays bounded to compare/readiness hierarchy. |
## Deferred Strategic Surfaces
| Deferred set | Reason | Recommended later coverage |
| --- | --- | --- |
| Decision Register, Exception Detail, Finding Detail | Closely related to governance inbox but require detail-state records. | Governance implementation wave after inbox pattern is accepted. |
| Review Register, Review Pack Detail, Stored Report Detail, Evidence Overview | Customer/evidence family needs customer-safe review pattern, but Customer Review Workspace and Audit Log provide first anchors. | Evidence/Review Pack consumption productization. |
| Backup Schedules, Backup Sets, Backup Set Create/View | Restore Runs selected as the highest-risk restore anchor; backup set pages need capability-backed fixtures. | Backup/Restore safety workflow spec with seeded browser proof. |
| Baseline Profiles, Baseline Profile Detail/Edit, Baseline Compare Matrix, Policy Version Detail | Baseline Compare selected as drift decision anchor; library/detail pages can follow after pattern validation. | Drift/Baseline decision experience. |
| Environment Access Scopes, Manage Workspaces, Managed Environments | Important RBAC/admin surfaces, but less central to first target-image wave than workspace/environment dashboards. | Admin/settings and access-control pattern spec. |
| Alerts and alert delivery/config pages | Operations Hub selected as the monitoring anchor; alert subresources can reuse the operations status grammar later. | Operations and alerting domain pattern. |
| Provider Connection Detail/Edit, Environment Onboarding, Required Permissions | Provider Connections selected as readiness anchor; forms and wizard need a later provider onboarding pass. | Provider onboarding/readiness UX cleanup. |
| System-plane dashboard, operations, repair, access logs | Platform/internal P2 surfaces and different auth plane. | System-plane controls target spec after admin-plane patterns settle. |
| Inventory coverage and policy version detail | Strategic but better handled with drift/evidence patterns and seeded records. | Inventory coverage and snapshot proof pattern. |
## Rejected Mockup Handling
No previous rejected Spec 325 SVG mockup artifacts were present in the working tree. `docs/ui-ux-enterprise-audit/mockups/.DS_Store` is an operating-system metadata file, not a mockup artifact. The rejected target-image folder still contains a README so future rejected explorations have a documented landing place.
## Not Implementation Truth
The target images linked from this shortlist are visual direction artifacts only. Later implementation specs must verify route reality, data availability, authorization, workspace/environment isolation, OperationRun semantics, auditability, dangerous-action behavior, and customer-safe visibility before coding.

133
docs/ui-ux-enterprise-audit/target-experience-briefs/workspace-overview.md Normal file
View File

@ -0,0 +1,133 @@
# Workspace Overview Target Experience Brief
## Metadata
| Field | Value |
| --- | --- |
| Surface IDs | UI-001, UI-002 |
| Route | `/admin` -> `/admin/workspaces/{workspace}/overview` |
| Source screenshot | `../screenshots/desktop/ui-001-workspace-overview.png` |
| Source page report | `../page-reports/ui-001-workspace-overview.md` |
| Target sidecar | `../target-images/target/workspace-overview-target.md` |
| Primary persona | Workspace owner / MSP operator |
| Secondary personas | Manager, support reviewer |
| Repo-truth posture | Source route and screenshot are `repo-verified`; target composition is direction only. |
## Current-State Snapshot
The page already reads as a calm workspace home with operational and governance attention cards. The current page report says several valuable paths compete at the same level: choose environment, operations, alerts, backup attention, recovery attention, findings, and hygiene.
## Current-State Productization Problems
- Primary next action is not singular enough for a first landing page.
- Backup, recovery, alerts, and assigned work compete instead of laddering from posture to next action.
- Evidence and diagnostics are present, but the proof path is not visually distinct from navigation.
## Target User Promise
In five seconds, a workspace owner knows whether the workspace needs action, which environment needs attention first, and where the evidence trail lives.
## First-Five-Seconds Target
Show a single workspace posture band, one dominant "Review priority environment" action, and a short attention queue with reason and evidence link.
## Primary Decision
Which workspace-level item needs operator attention first?
## Primary Action
Review priority environment.
## Secondary Actions
Open operations, review governance inbox, inspect backup readiness, review audit trail.
## Target Information Hierarchy
1. Workspace context and posture.
2. One priority decision with reason and impact.
3. Environment attention list.
4. Evidence and OperationRun traceability.
5. Secondary diagnostic summaries.
## Main-View Keep / Promote / Simplify
| Treatment | Elements |
| --- | --- |
| Keep | Workspace name, environment count, governance/backup/recovery attention, active operations. |
| Promote | Priority environment, reason, impact, evidence link, primary action. |
| Simplify | Equal-weight card grid, repeated navigation links, diagnostic counts without a decision role. |
## Detail Drawer Treatment
Use a right-side detail drawer for selected environment attention. It should show reason, evidence basis, recent runs, and diagnostics in separate sections.
## Advanced/Admin Treatment
Workspace settings, member management, raw health diagnostics, and configuration shortcuts stay behind secondary links or menus.
## Hidden/Removed Default Elements
Hide raw operation payloads, provider error IDs, and repeated "open" links from the default view.
## Target Layout Direction
Use a wide decision header, left priority queue, right evidence/operations strip, and lower secondary domain summaries. Avoid decorative dashboard charts.
## Visual Target Direction
Calm dark command surface with ivory text, warm graphite panels, mint as a narrow action accent, amber for attention, and restrained violet for evidence links.
## Status/Trust Model
No green success state unless the underlying state is verified. Separate execution state, governance attention, and backup/recovery posture.
## Dangerous Actions
No destructive action should be primary on the workspace home. Downstream backup/restore/provider actions must disclose mutation scope before execution.
## Customer-Safe Review Notes
Not customer-facing by default. Any customer-shareable summary must hide diagnostics and raw provider details.
## Workspace/Environment Context
Workspace is explicit in the header. Environment-specific items must show the environment name before any action link.
## Empty / Loading / Error States
Empty state should say no environments are ready for review and offer one setup action. Loading should preserve the workspace shell. Error state should explain whether workspace context, environment data, or operations data failed.
## Accessibility Notes
Priority items need visible labels beyond color. The primary action must be reachable by keyboard before secondary links.
## Repo-Truth Classification
| Target element | Classification | Notes |
| --- | --- | --- |
| Workspace route and source screenshot | repo-verified | Spec 323 browser pass reached the route. |
| Workspace attention cards | repo-verified | Present in page report as current content class. |
| Priority environment queue | plausible-existing | Derived from existing attention concepts, needs runtime data verification. |
| Evidence strip | foundation-only | Audit/evidence surfaces exist, but exact workspace aggregate needs later spec. |
| Final brand tokens | spec-only | Spec 325 direction, not final brand governance. |
## Screenshot-Anchored Image Prompt
Start from `ui-001-workspace-overview.png`. Create a target design direction, not runtime implementation. Preserve the workspace-home purpose. Fix competing next actions by showing workspace posture, one primary priority-environment action, reason/impact, evidence link, and secondary operations/governance/backup summaries. Keep diagnostics secondary. Use calm dark enterprise styling with Tenantial mint as an accent. Avoid generic blue SaaS, fake compliance claims, green success without verification, placeholder nonsense text, decorative charts, and runtime implementation claims.
## Implementation Pattern Requirements
- Use an explicit workspace context header.
- Keep one dominant next action.
- Separate governance, operation, and backup/recovery state.
- Link evidence and OperationRun proof without making diagnostics primary.
## Later Implementation Candidate
Workspace and Environment dashboard productization.
## Non-Goals For Later Implementation
Do not add new workspace metrics, new persisted posture truth, or a dashboard framework without a separate spec.

43
docs/ui-ux-enterprise-audit/target-images/README.md Normal file
View File

@ -0,0 +1,43 @@
# Spec 325 Target Images
This folder contains screenshot-anchored target images and sidecars for the Spec 325 strategic surface shortlist.
## Structure
| Path | Purpose |
| --- | --- |
| `target/` | Accepted PNG target images and required sidecar Markdown files. |
| `source/` | Source screenshot policy notes. Current Spec 323 screenshots are reused by link instead of duplicated. |
| `problem-annotations/` | Reserved for future annotation images when a later spec needs them. Not used in Spec 325. |
| `reference/spec-325-premium-reference/` | User-accepted premium visual reference set used to calibrate the regenerated target PNGs. |
| `rejected/spec-325-initial-svg-pass/` | Rejected mockup policy and future rejected exploration holding area. |
## Premium Visual Reference
The accepted visual direction for Spec 325 is documented in `reference/spec-325-premium-reference/README.md`. The four reference images establish the premium dark shell, dense enterprise panel rhythm, table/detail workbench layout, and evidence/restore/governance visual language.
Those reference images are not implementation truth. They calibrate visual quality only; concrete data, dates, metrics, actions, and green success states still require repo verification before runtime implementation.
## Accepted Target Images
| Surface | Dark target | Light target | Sidecar |
| --- | --- | --- | --- |
| Workspace Overview | `target/workspace-overview-target-dark.png` | `target/workspace-overview-target-light.png` | `target/workspace-overview-target.md` |
| Environment Dashboard | `target/environment-dashboard-target-dark.png` | `target/environment-dashboard-target-light.png` | `target/environment-dashboard-target.md` |
| Operations Hub | `target/operations-hub-target-dark.png` | `target/operations-hub-target-light.png` | `target/operations-hub-target.md` |
| Governance Inbox | `target/governance-inbox-target-dark.png` | `target/governance-inbox-target-light.png` | `target/governance-inbox-target.md` |
| Customer Review Workspace | `target/customer-review-workspace-target-dark.png` | `target/customer-review-workspace-target-light.png` | `target/customer-review-workspace-target.md` |
| Audit Log | `target/audit-log-target-dark.png` | `target/audit-log-target-light.png` | `target/audit-log-target.md` |
| Restore Safety Workflow | `target/restore-safety-workflow-target-dark.png` | `target/restore-safety-workflow-target-light.png` | `target/restore-safety-workflow-target.md` |
| Provider Readiness | `target/provider-readiness-target-dark.png` | `target/provider-readiness-target-light.png` | `target/provider-readiness-target.md` |
| Baseline Compare / Drift | `target/baseline-compare-drift-target-dark.png` | `target/baseline-compare-drift-target-light.png` | `target/baseline-compare-drift-target.md` |
## Image Policy
- Target images are design direction, not implementation truth.
- Every image must be read with its target brief and sidecar.
- The regenerated dark target images are the primary premium visual direction; light variants are compatibility/design-system support artifacts because Filament includes light mode by default.
- Repo-verified elements may be treated as source anchors.
- Conceptual elements must be verified in a later implementation spec.
- Do not implement target images blindly.
- Do not infer final brand system decisions from these images.

5
docs/ui-ux-enterprise-audit/target-images/problem-annotations/README.md Normal file
View File

@ -0,0 +1,5 @@
# Problem Annotation Images
No separate problem annotation PNGs were created in Spec 325. The current-state problems are documented in each target experience brief and transformation sidecar.
This folder is reserved for later implementation waves that need annotated screenshots for design review.

40
docs/ui-ux-enterprise-audit/target-images/reference/spec-325-premium-reference/README.md Normal file
View File

@ -0,0 +1,40 @@
# Spec 325 Premium Visual Reference Set
These four images are user-accepted premium visual references for the Spec 325 target-image direction.
They are visual calibration references only. They are not repo-real product screenshots, not implementation truth, and not evidence that the shown metrics, actions, labels, dates, entities, or workflow states exist in the application.
## Reference Images
| Reference | File | Intended calibration use |
| --- | --- | --- |
| Platform Overview | `platform-overview-premium-reference.png` | Premium shell, dense dashboard composition, sidebar/topbar rhythm, overview cards. |
| Governance Inbox | `governance-inbox-premium-reference.png` | Decision workbench, table/detail split, severity filters, right-side drawer. |
| Backup & Restore | `backup-restore-premium-reference.png` | Backup/restore domain density, service-health tables, restore-plan detail panel. |
| Evidence & Audit | `evidence-audit-premium-reference.png` | Evidence/audit proof surfaces, tabs, audit timeline, proof card, export/report affordances. |
## Accepted Direction
Use these references for:
- dark premium enterprise shell
- calm high-density panel system
- left navigation plus top context bar
- right-side decision/detail panels
- evidence/audit/proof pathways
- dense but scanable tables
- operational/product context visible above diagnostics
## Required Corrections Before Runtime Implementation
Later implementation specs must still correct or verify:
- no green/success state unless backed by repo-verified evidence
- dangerous restore actions need stronger friction than a normal green execute button
- concrete metrics, dates, users, and entities are conceptual unless repo-verified
- customer-safe and auditor-safe surfaces must hide raw diagnostics by default
- every action requires RBAC, audit, workspace/environment scope, and OperationRun verification where relevant
## Relationship To Generated Target Images
The first generated Spec 325 PNGs are treated as IA/content scaffolds. The accepted premium direction is this reference set plus the regenerated premium target PNGs under `../../target/`.

BIN
docs/ui-ux-enterprise-audit/target-images/reference/spec-325-premium-reference/backup-restore-premium-reference.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 1.4 MiB

BIN
docs/ui-ux-enterprise-audit/target-images/reference/spec-325-premium-reference/evidence-audit-premium-reference.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 1.5 MiB

BIN
docs/ui-ux-enterprise-audit/target-images/reference/spec-325-premium-reference/governance-inbox-premium-reference.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 1.4 MiB

BIN
docs/ui-ux-enterprise-audit/target-images/reference/spec-325-premium-reference/platform-overview-premium-reference.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 1.3 MiB

13
docs/ui-ux-enterprise-audit/target-images/rejected/spec-325-initial-svg-pass/README.md Normal file
View File

@ -0,0 +1,13 @@
# Rejected Spec 325 Initial SVG Pass
No rejected Spec 325 SVG mockup files were present in the working tree during this implementation pass.
If rejected exploration files are added later, place them in this folder only as historical artifacts. They are not accepted target experiences, not implementation targets, and not source of truth.
The rejection rule is:
- generic SaaS dashboards are not acceptable
- unanchored visuals are not acceptable
- repeated static SVG card layouts are not acceptable
- visuals disconnected from current screenshots or page reports are not acceptable
- conceptual features must not appear as implemented product truth

11
docs/ui-ux-enterprise-audit/target-images/source/README.md Normal file
View File

@ -0,0 +1,11 @@
# Source Screenshot Reuse
Spec 325 reuses the existing Spec 323 source screenshots by link instead of copying them into this folder. This avoids duplicate binary artifacts while preserving stable source anchors.
Source screenshots live under:
```text
docs/ui-ux-enterprise-audit/screenshots/desktop/
```
Every selected surface sidecar links its source screenshot and page report directly.

BIN
docs/ui-ux-enterprise-audit/target-images/target/audit-log-target-dark.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 193 KiB

BIN
docs/ui-ux-enterprise-audit/target-images/target/audit-log-target-light.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 202 KiB

49
docs/ui-ux-enterprise-audit/target-images/target/audit-log-target.md Normal file
View File

@ -0,0 +1,49 @@
# Audit Log Target Image Sidecar
## Not Implementation Truth
This target image is visual direction only. It is not runtime implementation truth, not a product capability claim, and not a substitute for later repo, RBAC, data, audit, and browser verification.
## Links
| Item | Link |
| --- | --- |
| Source route | `/admin/audit-log` |
| Source screenshot | `../../screenshots/desktop/ui-008-audit-log.png` |
| Source page report | `../../page-reports/ui-008-audit-log.md` |
| Target brief | `../../target-experience-briefs/audit-log.md` |
| Dark target image | `audit-log-target-dark.png` |
| Light target image | `audit-log-target-light.png` |
## Transformation Table
| Current state | Target direction |
| --- | --- |
| Audit page can read as raw event history. | Event proof, scope, and selected detail become first-read. |
| Raw metadata can overpower evidence. | Human-readable proof precedes raw metadata. |
| Export/share copy needs review. | Export is scope-aware and marked for later authorization/audit verification. |
## Repo-Truth Classification
| Element in target image | Classification | Implementation note |
| --- | --- | --- |
| Audit route and screenshot | repo-verified | Existing route/screenshot anchor. |
| AuditLog event fields | repo-verified | Existing page/model concepts. |
| Selected proof panel | plausible-existing | New hierarchy over current data. |
| Export readiness | foundation-only | Requires runtime/export verification. |
| Compliance claims | unknown | Must not be asserted without proof. |
## Conceptual Elements Requiring Verification
- Export scope and redaction
- Selected event entitlement behavior
- Evidence links from audit records
- Customer/auditor wording
## Implementation Notes
Later implementation should keep scope filters visible and raw metadata behind progressive disclosure.
## Do Not Implement Blindly
Do not add compliance-ready language or audit export behavior without a separate verified implementation spec.

BIN
docs/ui-ux-enterprise-audit/target-images/target/baseline-compare-drift-target-dark.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 196 KiB

BIN
docs/ui-ux-enterprise-audit/target-images/target/baseline-compare-drift-target-light.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 207 KiB

49
docs/ui-ux-enterprise-audit/target-images/target/baseline-compare-drift-target.md Normal file
View File

@ -0,0 +1,49 @@
# Baseline Compare / Drift Target Image Sidecar
## Not Implementation Truth
This target image is visual direction only. It is not runtime implementation truth, not a product capability claim, and not a substitute for later repo, RBAC, data, audit, and browser verification.
## Links
| Item | Link |
| --- | --- |
| Source route | `/admin/workspaces/{workspace}/environments/{environment}/baseline-compare` |
| Source screenshot | `../../screenshots/desktop/ui-015-baseline-compare-blocked-404.png` |
| Source page report | `../../page-reports/ui-015-baseline-compare.md` |
| Target brief | `../../target-experience-briefs/baseline-compare-drift.md` |
| Dark target image | `baseline-compare-drift-target-dark.png` |
| Light target image | `baseline-compare-drift-target-light.png` |
## Transformation Table
| Current state | Target direction |
| --- | --- |
| Browser fixture returned 404 for the compare route. | Target is bounded to route-verified compare/readiness guidance. |
| Raw diff risk can dominate first read. | Drift impact and evidence gaps lead before raw diff. |
| Assignment, freshness, and operation truth need separation. | Baseline, compare freshness, evidence gap, and run proof are distinct. |
## Repo-Truth Classification
| Element in target image | Classification | Implementation note |
| --- | --- | --- |
| Baseline compare route | repo-verified | Route exists, fixture blocked. |
| BaselineProfile and OperationRun concepts | repo-verified | Existing models. |
| Drift impact clusters | plausible-existing | Must map to compare result data. |
| Evidence gap scoring | foundation-only | Product direction only. |
| Exception workflow from drawer | conceptual-future-state | Separate spec required. |
## Conceptual Elements Requiring Verification
- Baseline assignment data source
- Compare freshness calculation
- Drift impact grouping
- Evidence gap display and customer-safe wording
## Implementation Notes
Later implementation should put impact before raw diff and keep compare actions authorized, audited, and OperationRun-backed.
## Do Not Implement Blindly
Do not invent drift scores, evidence scores, or exception workflows from this visual.

BIN
docs/ui-ux-enterprise-audit/target-images/target/customer-review-workspace-target-dark.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 207 KiB

BIN
docs/ui-ux-enterprise-audit/target-images/target/customer-review-workspace-target-light.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 216 KiB

49
docs/ui-ux-enterprise-audit/target-images/target/customer-review-workspace-target.md Normal file
View File

@ -0,0 +1,49 @@
# Customer Review Workspace Target Image Sidecar
## Not Implementation Truth
This target image is visual direction only. It is not runtime implementation truth, not a product capability claim, and not a substitute for later repo, RBAC, data, audit, and browser verification.
## Links
| Item | Link |
| --- | --- |
| Source route | `/admin/reviews/workspace` |
| Source screenshot | `../../screenshots/desktop/ui-006-customer-review-workspace.png` |
| Source page report | `../../page-reports/ui-006-customer-review-workspace.md` |
| Target brief | `../../target-experience-briefs/customer-review-workspace.md` |
| Dark target image | `customer-review-workspace-target-dark.png` |
| Light target image | `customer-review-workspace-target-light.png` |
## Transformation Table
| Current state | Target direction |
| --- | --- |
| Customer review value is present but needs final hierarchy. | Review readiness, evidence freshness, and accepted risk become first-read. |
| Raw/internal diagnostics could leak into review framing. | Customer-safe content is default; diagnostics are hidden. |
| Review pack context needs proof language. | Review pack availability is tied to evidence and share scope. |
## Repo-Truth Classification
| Element in target image | Classification | Implementation note |
| --- | --- | --- |
| Review workspace route | repo-verified | Existing route/screenshot anchor. |
| Review/evidence/accepted-risk concepts | plausible-existing | Existing product areas, exact links need verification. |
| Customer-safe review pack card | foundation-only | Requires export/share behavior verification. |
| Customer mode split | spec-only | Target direction, not runtime proof. |
| External sharing | conceptual-future-state | Separate spec required. |
## Conceptual Elements Requiring Verification
- Review readiness derivation
- Evidence freshness source
- Accepted-risk summary source
- Export/share authorization and audit
## Implementation Notes
Later implementation should separate customer-readable content, operator diagnostics, and support/raw evidence.
## Do Not Implement Blindly
Do not expose raw OperationRuns, provider diagnostics, fingerprints, or internal reason ownership in customer-facing default views.

BIN
docs/ui-ux-enterprise-audit/target-images/target/environment-dashboard-target-dark.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 199 KiB

BIN
docs/ui-ux-enterprise-audit/target-images/target/environment-dashboard-target-light.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 209 KiB

49
docs/ui-ux-enterprise-audit/target-images/target/environment-dashboard-target.md Normal file
View File

@ -0,0 +1,49 @@
# Environment Dashboard Target Image Sidecar
## Not Implementation Truth
This target image is visual direction only. It is not runtime implementation truth, not a product capability claim, and not a substitute for later repo, RBAC, data, audit, and browser verification.
## Links
| Item | Link |
| --- | --- |
| Source route | `/admin/workspaces/{workspace}/environments/{environment}` |
| Source screenshot | `../../screenshots/desktop/ui-002-environment-dashboard.png` |
| Source page report | `../../page-reports/ui-002-environment-dashboard.md` |
| Target brief | `../../target-experience-briefs/environment-dashboard.md` |
| Dark target image | `environment-dashboard-target-dark.png` |
| Light target image | `environment-dashboard-target-light.png` |
## Transformation Table
| Current state | Target direction |
| --- | --- |
| Backup, recovery, verification, and operations have similar weight. | Readiness posture and blocker reason become the first read. |
| Dangerous downstream actions are implied by domain links. | Mutation scope and safety context are called out before action. |
| Proof and diagnostics are adjacent. | Evidence, OperationRun proof, and raw diagnostics are separated. |
## Repo-Truth Classification
| Element in target image | Classification | Implementation note |
| --- | --- | --- |
| Environment route and context | repo-verified | Existing route/screenshot anchor. |
| Backup/recovery widgets | repo-verified | Present in current report. |
| Readiness blocker lane | plausible-existing | Needs mapping to current signals. |
| Mutation-scope copy | foundation-only | Constitution-driven, exact UI not implemented. |
| Provider diagnostic drawer | conceptual-future-state | Must be separately verified. |
## Conceptual Elements Requiring Verification
- Readiness blocker derivation
- Evidence freshness source
- Mutation scope wording
- Provider diagnostics visibility
## Implementation Notes
Later implementation should keep readiness, backup, recovery, operations, and governance as separate status dimensions.
## Do Not Implement Blindly
Do not create a new environment health status family from the visual. Derive from existing truth or specify the behavior first.

BIN
docs/ui-ux-enterprise-audit/target-images/target/governance-inbox-target-dark.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 191 KiB

BIN
docs/ui-ux-enterprise-audit/target-images/target/governance-inbox-target-light.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 202 KiB

49
docs/ui-ux-enterprise-audit/target-images/target/governance-inbox-target.md Normal file
View File

@ -0,0 +1,49 @@
# Governance Inbox Target Image Sidecar
## Not Implementation Truth
This target image is visual direction only. It is not runtime implementation truth, not a product capability claim, and not a substitute for later repo, RBAC, data, audit, and browser verification.
## Links
| Item | Link |
| --- | --- |
| Source route | `/admin/governance/inbox` |
| Source screenshot | `../../screenshots/desktop/ui-004-governance-inbox.png` |
| Source page report | `../../page-reports/ui-004-governance-inbox.md` |
| Target brief | `../../target-experience-briefs/governance-inbox.md` |
| Dark target image | `governance-inbox-target-dark.png` |
| Light target image | `governance-inbox-target-light.png` |
## Transformation Table
| Current state | Target direction |
| --- | --- |
| Decision queue intent exists but first action can blur. | One priority decision and Review decision action anchor the page. |
| Evidence and status dimensions can blend. | Reason, impact, owner, due state, and evidence basis are distinct. |
| Customer-safe downstream copy is not explicit. | Customer-safe summary is visible but diagnostics stay hidden. |
## Repo-Truth Classification
| Element in target image | Classification | Implementation note |
| --- | --- | --- |
| Governance route and screenshot | repo-verified | Existing route/screenshot anchor. |
| Decision queue purpose | repo-verified | Current report confirms purpose. |
| Recommended next action | plausible-existing | Needs domain mapping. |
| Customer-safe summary | foundation-only | Requires copy/data review. |
| Unified decision taxonomy | conceptual-future-state | Do not create without separate spec. |
## Conceptual Elements Requiring Verification
- Recommended action logic
- Decision owner and due-state source
- Customer-safe summary
- Mutating action confirmation/audit behavior
## Implementation Notes
Later implementation should keep exactly one dominant next decision action and use evidence-first detail drawers.
## Do Not Implement Blindly
Do not create new decision status families or taxonomies from target image labels alone.

BIN
docs/ui-ux-enterprise-audit/target-images/target/operations-hub-target-dark.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 188 KiB

BIN
docs/ui-ux-enterprise-audit/target-images/target/operations-hub-target-light.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 198 KiB

49
docs/ui-ux-enterprise-audit/target-images/target/operations-hub-target.md Normal file
View File

@ -0,0 +1,49 @@
# Operations Hub Target Image Sidecar
## Not Implementation Truth
This target image is visual direction only. It is not runtime implementation truth, not a product capability claim, and not a substitute for later repo, RBAC, data, audit, and browser verification.
## Links
| Item | Link |
| --- | --- |
| Source route | `/admin/workspaces/{workspace}/operations` |
| Source screenshot | `../../screenshots/desktop/ui-003-operations.png` |
| Source page report | `../../page-reports/ui-003-operations.md` |
| Target brief | `../../target-experience-briefs/operations-hub.md` |
| Dark target image | `operations-hub-target-dark.png` |
| Light target image | `operations-hub-target-light.png` |
## Transformation Table
| Current state | Target direction |
| --- | --- |
| Chronological run history is the dominant shape. | Attention-needed runs and active progress lead the page. |
| Execution truth can be mistaken for governance health. | Execution state, outcome, and evidence are visually separated. |
| Raw diagnostics can become primary detail. | Raw/support diagnostics remain collapsed behind proof summary. |
## Repo-Truth Classification
| Element in target image | Classification | Implementation note |
| --- | --- | --- |
| Operations route | repo-verified | Existing route/screenshot anchor. |
| OperationRun records | repo-verified | Existing model and current page purpose. |
| Attention-needed grouping | plausible-existing | Derive from status/outcome in later spec. |
| Artifact proof rail | foundation-only | Requires per-operation artifact mapping. |
| Retry/cancel action set | unknown | Must be verified by operation family. |
## Conceptual Elements Requiring Verification
- Run grouping logic
- Summary count labels
- Retry/cancel availability
- Artifact link resolution and entitlement
## Implementation Notes
Later implementation should reuse the central OperationRun UX contract and keep terminal notifications, run links, and artifact links consistent.
## Do Not Implement Blindly
Do not introduce local OperationRun semantics or duplicate notification paths from this image.

BIN
docs/ui-ux-enterprise-audit/target-images/target/provider-readiness-target-dark.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 206 KiB

BIN
docs/ui-ux-enterprise-audit/target-images/target/provider-readiness-target-light.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 216 KiB

49
docs/ui-ux-enterprise-audit/target-images/target/provider-readiness-target.md Normal file
View File

@ -0,0 +1,49 @@
# Provider Readiness Target Image Sidecar
## Not Implementation Truth
This target image is visual direction only. It is not runtime implementation truth, not a product capability claim, and not a substitute for later repo, RBAC, data, audit, and browser verification.
## Links
| Item | Link |
| --- | --- |
| Source route | `/admin/provider-connections` plus create/detail family |
| Source screenshot | `../../screenshots/desktop/ui-009-provider-connections.png` |
| Source page report | `../../page-reports/ui-009-provider-connections.md` |
| Target brief | `../../target-experience-briefs/provider-readiness.md` |
| Dark target image | `provider-readiness-target-dark.png` |
| Light target image | `provider-readiness-target-light.png` |
## Transformation Table
| Current state | Target direction |
| --- | --- |
| Provider table needs stronger readiness hierarchy. | Readiness, permission gaps, verification, and next action lead. |
| Raw integration details can dominate. | Diagnostics are collapsed and redacted. |
| Dangerous actions need safety posture. | Rotate, disconnect, and re-consent actions require confirmation/audit notes. |
## Repo-Truth Classification
| Element in target image | Classification | Implementation note |
| --- | --- | --- |
| Provider route and screenshot | repo-verified | Existing route/screenshot anchor. |
| ProviderConnection model | repo-verified | Existing model. |
| Permission readiness summary | plausible-existing | Needs mapping to existing contracts/permissions. |
| Capability impact copy | foundation-only | Requires deterministic capability mapping. |
| Multi-provider neutral language | spec-only | Product direction for later implementation. |
## Conceptual Elements Requiring Verification
- Permission gap source
- Capability impact mapping
- Credential lifecycle status
- Re-consent and rotation action rules
## Implementation Notes
Later implementation should keep provider-specific semantics bounded and never expose secrets or raw credential payloads.
## Do Not Implement Blindly
Do not create a provider framework or new provider taxonomy from this image.

BIN
docs/ui-ux-enterprise-audit/target-images/target/restore-safety-workflow-target-dark.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 211 KiB

BIN
docs/ui-ux-enterprise-audit/target-images/target/restore-safety-workflow-target-light.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 222 KiB

49
docs/ui-ux-enterprise-audit/target-images/target/restore-safety-workflow-target.md Normal file
View File

@ -0,0 +1,49 @@
# Restore Safety Workflow Target Image Sidecar
## Not Implementation Truth
This target image is visual direction only. It is not runtime implementation truth, not a product capability claim, and not a substitute for later repo, RBAC, data, audit, and browser verification.
## Links
| Item | Link |
| --- | --- |
| Source route | `/admin/workspaces/{workspace}/environments/{environment}/restore-runs` plus create/view family |
| Source screenshot | `../../screenshots/desktop/ui-014-restore-runs.png` |
| Source page report | `../../page-reports/ui-014-restore-runs.md` |
| Target brief | `../../target-experience-briefs/restore-safety-workflow.md` |
| Dark target image | `restore-safety-workflow-target-dark.png` |
| Light target image | `restore-safety-workflow-target-light.png` |
## Transformation Table
| Current state | Target direction |
| --- | --- |
| Browser review was blocked by capability/state. | Target is explicitly marked as safety direction, not current UI proof. |
| Restore could look like normal create/list UI. | Restore appears as a high-friction safety workflow. |
| Preview/result/evidence truth needs separation. | Safety gates, preview, confirmation, operation, and evidence are distinct. |
## Repo-Truth Classification
| Element in target image | Classification | Implementation note |
| --- | --- | --- |
| Restore route family | repo-verified | Route exists, fixture blocked. |
| RestoreRun and OperationRun concepts | repo-verified | Existing models. |
| Safety gate stepper | foundation-only | Product safety requirement, exact runtime steps need spec. |
| Hard confirmation copy | spec-only | Target wording only. |
| Partial restore conflict model | conceptual-future-state | Needs separate verification. |
## Conceptual Elements Requiring Verification
- Actual dry-run/preview data shape
- Validation gate sequence
- Hard confirmation text and rules
- OperationRun and evidence result links
## Implementation Notes
Later implementation must enforce preview, explicit confirmation, authorization, audit, OperationRun continuity, and post-run evidence.
## Do Not Implement Blindly
Do not implement restore provider writes or confirmation behavior from a visual artifact without the restore safety spec and tests.

BIN
docs/ui-ux-enterprise-audit/target-images/target/workspace-overview-target-dark.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 200 KiB

BIN
docs/ui-ux-enterprise-audit/target-images/target/workspace-overview-target-light.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 209 KiB

49
docs/ui-ux-enterprise-audit/target-images/target/workspace-overview-target.md Normal file
View File

@ -0,0 +1,49 @@
# Workspace Overview Target Image Sidecar
## Not Implementation Truth
This target image is visual direction only. It is not runtime implementation truth, not a product capability claim, and not a substitute for later repo, RBAC, data, audit, and browser verification.
## Links
| Item | Link |
| --- | --- |
| Source route | `/admin` -> `/admin/workspaces/{workspace}/overview` |
| Source screenshot | `../../screenshots/desktop/ui-001-workspace-overview.png` |
| Source page report | `../../page-reports/ui-001-workspace-overview.md` |
| Target brief | `../../target-experience-briefs/workspace-overview.md` |
| Dark target image | `workspace-overview-target-dark.png` |
| Light target image | `workspace-overview-target-light.png` |
## Transformation Table
| Current state | Target direction |
| --- | --- |
| Several equal workspace attention links compete. | One priority environment action anchors the first decision. |
| Backup, recovery, alerts, and findings appear as peer summaries. | Summaries ladder from posture to reason, impact, evidence, and action. |
| Diagnostics and recent operations are useful but can compete. | Diagnostics stay secondary in an evidence/operations rail. |
## Repo-Truth Classification
| Element in target image | Classification | Implementation note |
| --- | --- | --- |
| Workspace route and workspace context | repo-verified | Existing route/screenshot anchor. |
| Attention cards | repo-verified | Present in current report. |
| Priority environment action | plausible-existing | Must derive from existing attention data. |
| Evidence strip | foundation-only | Later spec must verify data and links. |
| Brand treatment | spec-only | Visual direction only. |
## Conceptual Elements Requiring Verification
- Priority environment ranking
- Evidence strip contents
- Workspace aggregate posture wording
- Action visibility by role/capability
## Implementation Notes
Later implementation should keep the workspace home decision-first, preserve workspace context, and avoid adding a new persisted posture layer unless current product truth requires it.
## Do Not Implement Blindly
Do not copy every visual card. Verify the data source, authorization, and product meaning for each tile first.

98
specs/325-screenshot-anchored-strategic-target-images/checklists/requirements.md Normal file
View File

@ -0,0 +1,98 @@
# Requirements Checklist - Spec 325
**Purpose**: Validate Spec 325 preparation completeness and implementation-readiness.
**Created**: 2026-05-17
**Feature**: `specs/325-screenshot-anchored-strategic-target-images/spec.md`
## Scope
- [x] Spec remains docs/image target artifact work.
- [x] No product runtime UI is changed by the prepared spec.
- [x] No routes are changed by the prepared spec.
- [x] No Filament/Livewire/Blade runtime files are changed by the prepared spec.
- [x] No business logic is changed by the prepared spec.
- [x] No database schema is changed by the prepared spec.
## Selection
- [x] Selected surfaces must come from Spec 323 artifacts.
- [x] No more than 10 surfaces may be selected.
- [x] P0/P1 rationale is required.
- [x] Deferred strategic surfaces are required.
## Screenshot Anchoring
- [x] Every selected surface must reference a current screenshot and/or page report.
- [x] Every brief must describe concrete current-state problems.
- [x] Every target image must have source/brief/sidecar.
- [x] No target image may be accepted as standalone truth.
## Target Briefs
- [x] Every selected surface requires a target experience brief.
- [x] User promise is required.
- [x] Primary persona is required.
- [x] First-five-seconds target is required.
- [x] Primary decision is required.
- [x] Primary action is required.
- [x] Information hierarchy is required.
- [x] Main view / detail drawer / advanced split is required.
- [x] Visual target direction is required.
- [x] Status/trust model is required.
- [x] Repo-truth classifications are required.
- [x] Image generation prompt is required.
- [x] Implementation pattern requirements are required.
## Target Images
- [x] Every selected surface requires at least one target image.
- [x] Customer/auditor/management-facing surfaces require light target image or documented reason.
- [x] Target images must be screenshot-anchored.
- [x] Target images must not be generic SaaS dashboards.
- [x] Target images must not imply false product truth.
- [x] Target images must not present conceptual-future-state as implemented.
- [x] Target images must avoid fake green success.
- [x] Target images must be readable and reviewable.
## Customer / Risk
- [x] Customer-facing surfaces must be customer-safe.
- [x] Dangerous actions must include guardrail concepts.
- [x] Evidence/audit paths must be represented where relevant.
- [x] Technical diagnostics must be secondary.
## Coverage Artifacts
- [x] Strategic surfaces file update is required.
- [x] Design coverage matrix update is required if target-image coverage is tracked.
- [x] Grouped follow-up candidates update is required.
- [x] Follow-up implementation candidates creation is required.
- [x] README links to artifacts are required.
## Validation
- [x] `bash scripts/check-ui-productization-coverage HEAD` is required during implementation.
- [x] `git diff --check` is required during implementation.
- [x] Full Pest/runtime suite must be intentionally not run unless runtime files changed.
- [x] Pint must be intentionally not run unless PHP files changed.
## Candidate Selection Gate
- [x] Candidate is directly user-provided.
- [x] Candidate aligns with Spec 323/324 product direction.
- [x] Existing related completed specs are treated as historical context only.
- [x] Existing `specs/325-tenantial-strategic-surface-target-mockups/` contains no tracked completed spec artifacts.
- [x] Scope is bounded to a small docs/image target-artifact slice.
- [x] Adjacent pattern-library work is deferred to Spec 326.
## Spec Readiness Gate
- [x] `spec.md` exists.
- [x] `plan.md` exists.
- [x] `tasks.md` exists.
- [x] `checklists/requirements.md` exists.
- [x] Problem statement, user value, functional requirements, non-goals, acceptance criteria, risks, and assumptions are present.
- [x] Plan identifies affected repo surfaces and no-runtime constraints.
- [x] Tasks are ordered, small, and verifiable.
- [x] Workspace/environment context, RBAC/customer-safety, audit/evidence, OperationRun truth, and dangerous-action UX expectations are addressed where relevant.
- [x] No open question blocks safe implementation.

216
specs/325-screenshot-anchored-strategic-target-images/plan.md Normal file
View File

@ -0,0 +1,216 @@
# Plan: Spec 325 - Screenshot-Anchored Strategic Target Images & Experience Briefs
**Branch**: `325-screenshot-anchored-strategic-target-images` | **Date**: 2026-05-17 | **Spec**: `specs/325-screenshot-anchored-strategic-target-images/spec.md`
## Summary
Spec 325 creates screenshot-anchored target experience briefs and high-quality target image artifacts for a proportional 6-10 surface shortlist from Spec 323 strategic surfaces. The work is docs/image-only and updates UI audit coverage artifacts; it does not implement runtime UI or product behavior.
## Premium Visual Reference Plan Addendum
The user accepted four uploaded premium Tenantial images as the visual reference baseline. Implementation keeps the docs/image-only posture and adds those images under `docs/ui-ux-enterprise-audit/target-images/reference/spec-325-premium-reference/`.
The target PNG regeneration uses those references as visual calibration while preserving the existing Spec 325 content contract:
- dark premium shell is primary
- sidebar/topbar/context bar are part of the target direction
- dense enterprise panels and table/detail workbenches are preferred
- evidence, restore, governance, and operations proof paths are visible
- dangerous restore execution needs stronger safety treatment than the reference image's normal green action
- light variants remain support artifacts because Filament includes light mode by default
- concrete metrics and actions remain conceptual unless repo-verified
## Technical Context
- **Language/Version**: N/A - documentation and image artifacts only.
- **Primary Dependencies**: Spec 323 audit artifacts, Spec 324 guardrails, existing screenshots/page reports, `docs/brand/tenantial-brand-context.md`.
- **Storage**: Repository Markdown/image files only; no database storage.
- **Testing**: Static validation only.
- **Validation Lanes**: docs/static guard validation.
- **Target Platform**: Repository documentation review.
- **Project Type**: Laravel/Filament monorepo, but no application runtime code changes.
- **Performance Goals**: N/A.
- **Constraints**: No product runtime file changes; selected surfaces <= 10; target images must be screenshot-anchored and sidecar-documented.
- **Scale/Scope**: One bounded target-image preparation wave for P0/P1 strategic surfaces.
## Inputs
- `docs/ui-ux-enterprise-audit/strategic-surfaces.md`
- `docs/ui-ux-enterprise-audit/design-coverage-matrix.md`
- `docs/ui-ux-enterprise-audit/page-reports/`
- `docs/ui-ux-enterprise-audit/screenshots/desktop/`
- `docs/ui-ux-enterprise-audit/grouped-follow-up-candidates.md`
- `docs/ui-ux-enterprise-audit/README.md`
- `docs/brand/tenantial-brand-context.md`
- `specs/323-tenantial-enterprise-ui-audit-foundation/`
- `specs/324-ui-productization-coverage-guardrails/`
## UI / Surface Guardrail Plan
- **Guardrail scope**: no operator-facing runtime surface change.
- **Affected routes/pages/actions/states/navigation/panel/provider surfaces**: N/A - source surfaces are referenced only as audit/documentation inputs.
- **No-impact class**: docs-only / image-artifact-only.
- **Native vs custom classification summary**: N/A.
- **Shared-family relevance**: documentation names later pattern needs; no runtime shared family changes.
- **State layers in scope**: none at runtime.
- **Audience modes in scope**: target guidance may cover customer/read-only, operator-MSP, auditor, support, and platform personas; no runtime modes changed.
- **Decision/diagnostic/raw hierarchy plan**: every target brief must describe decision-first defaults, diagnostics-second, support/raw-third where applicable.
- **Raw/support gating plan**: documented in briefs only.
- **One-primary-action / duplicate-truth control**: documented in briefs only.
- **Handling modes by drift class or surface**: report-only for target-image artifacts; future implementation specs must decide hard-stop/review/exception modes.
- **Repository-signal treatment**: report-only.
- **Special surface test profiles**: N/A.
- **Required tests or manual smoke**: static guard validation; optional image dimension checks.
- **Exception path and spread control**: none.
- **Active feature PR close-out entry**: N/A - docs/image-only.
- **UI/Productization coverage decision**: No UI surface impact; coverage registry artifacts updated because Spec 325 itself is a UI audit target-artifact update.
- **Coverage artifacts to update**: `docs/ui-ux-enterprise-audit/README.md`, `strategic-surfaces.md`, `grouped-follow-up-candidates.md`, `design-coverage-matrix.md` if target-image coverage is tracked, target brief/image/follow-up docs.
- **No-impact rationale**: Target artifacts guide future UI implementation but do not alter reachable UI.
- **Navigation / Filament provider-panel handling**: no runtime provider/panel/nav handling.
- **Screenshot or page-report need**: yes; every selected surface needs an existing screenshot/page report anchor or must be rejected/deferred.
## Shared Pattern & System Fit
- **Cross-cutting feature marker**: yes, docs-only.
- **Systems touched**: UI audit documentation registry.
- **Shared abstractions reused**: Spec 323 audit artifacts and Spec 324 guardrail expectations.
- **New abstraction introduced? why?**: none at runtime; target-image docs identify future pattern needs only.
- **Why existing abstraction was sufficient or insufficient**: The audit registry is sufficient for target artifact tracking; runtime pattern code is deferred to Spec 326.
- **Bounded deviation / spread control**: Target images are explicitly not implementation truth and cannot be implemented blindly.
## OperationRun UX Impact
- **Touches OperationRun start/completion/link UX?**: no runtime impact.
- **Central contract reused**: N/A.
- **Delegated UX behaviors**: N/A.
- **Surface-owned behavior kept local**: N/A.
- **Queued DB-notification policy**: N/A.
- **Terminal notification path**: N/A.
- **Exception path**: none.
## Provider Boundary & Portability Fit
- **Shared provider/platform boundary touched?**: no runtime boundary touched.
- **Provider-owned seams**: N/A.
- **Platform-core seams**: N/A.
- **Neutral platform terms / contracts preserved**: briefs must preserve workspace, environment, provider, operation, evidence, and governance language.
- **Retained provider-specific semantics and why**: allowed only when repo/page report proves surface purpose is provider-specific.
- **Bounded extraction or follow-up path**: implementation lanes may later verify provider/onboarding pattern needs.
## Constitution Check
- Inventory-first: PASS - no inventory/snapshot runtime truth changes.
- Read/write separation: PASS - no writes to product runtime; target restore/dangerous-action briefs must document preview/confirmation/audit needs for later work.
- Graph contract path: PASS - no Graph calls.
- Deterministic capabilities: PASS - no capability code changes.
- RBAC-UX: PASS - no authorization changes; briefs must document customer-safe and capability assumptions.
- Workspace isolation: PASS - no runtime access changes; briefs must document workspace/environment context.
- Tenant isolation: PASS - no tenant queries or data changes.
- Run observability: PASS - no OperationRun changes.
- Automation: PASS - no queued/scheduled work.
- Data minimization: PASS - target briefs must avoid customer-visible diagnostics and fake claims.
- Test governance: PASS - docs/image-only static validation.
- Proportionality: PASS - 6-10 selected surfaces, not all 44.
- No premature abstraction: PASS - no runtime abstraction; pattern library deferred to Spec 326.
- Persisted truth: PASS - no database persistence; images are documentation artifacts.
- Behavioral state: PASS - no new runtime states/statuses.
- UI semantics: PASS - no runtime UI semantic framework.
- Shared pattern first: PASS - future pattern needs are grouped, not implemented ad hoc.
- Provider boundary: PASS - no provider core change.
- V1 explicitness / few layers: PASS - direct Markdown/image outputs.
- Spec discipline / bloat check: PASS - target-image wave is coherent and bounded.
- Filament-native UI: PASS - no Filament UI changes.
- UI/Productization coverage: PASS - active spec marks no runtime UI impact and updates audit artifacts.
## Project Structure
```text
specs/325-screenshot-anchored-strategic-target-images/
├── spec.md
├── plan.md
├── tasks.md
└── checklists/
└── requirements.md
docs/ui-ux-enterprise-audit/
├── target-experience-briefs/
├── target-images/
│ ├── source/
│ ├── problem-annotations/
│ ├── target/
│ └── rejected/
└── follow-up-specs/
```
No files under `apps/platform/` should be changed by this spec.
## Implementation Phases
1. Read Spec 323 audit artifacts.
2. Confirm Spec 324 guardrail expectations.
3. Select 6-10 P0/P1 strategic surfaces.
4. Create strategic target image shortlist.
5. Handle rejected mockup remnants if present.
6. Create target-experience-briefs structure.
7. Create target-images structure.
8. Create target briefs anchored to screenshots/page reports.
9. Generate/create target images using screenshot-anchored prompts.
10. Create target image sidecars.
11. Document deferred strategic surfaces.
12. Update strategic-surfaces and coverage matrix.
13. Create follow-up implementation candidates.
14. Update README links.
15. Run validation.
## Risk Controls
- Do not create unanchored mockups.
- Do not create generic SaaS dashboards.
- Do not mock all 44 strategic rows.
- Do not imply runtime implementation.
- Mark repo-truth level for conceptual elements.
- Keep customer-safe surfaces free of raw diagnostics.
- Do not create fake feature claims.
- Do not change product runtime files.
- Regenerate or reject target images that fail visual review criteria.
- Document any image generation/dimension validation that is not run.
## Test Governance Check
- **Test purpose / classification by changed surface**: N/A - docs/image target artifacts only.
- **Affected validation lanes**: static documentation guard.
- **Why this lane mix is the narrowest sufficient proof**: The work changes Markdown/image files and audit artifacts only.
- **Narrowest proving commands**: `bash scripts/check-ui-productization-coverage HEAD`; `git diff --check`.
- **Fixture / helper / factory / seed / context cost risks**: none.
- **Expensive defaults or shared helper growth introduced?**: no.
- **Heavy-family additions, promotions, or visibility changes**: none.
- **Surface-class relief / special coverage rule**: N/A.
- **Closing validation and reviewer handoff**: verify no product runtime files changed and all target images have source/brief/sidecar coverage.
- **Budget / baseline / trend follow-up**: none.
- **Review-stop questions**: target-image grounding, false product truth, selected-surface proportionality, customer-safe disclosure, dangerous-action guardrails.
- **Escalation path**: none.
- **Active feature PR close-out entry**: N/A.
- **Why no dedicated follow-up spec is needed**: Spec 325 is the dedicated target-image wave; Spec 326 is the recommended later pattern-library follow-up.
## Validation
Required:
```bash
bash scripts/check-ui-productization-coverage HEAD
git diff --check
```
Optional:
```bash
bash -n scripts/check-ui-productization-coverage
find docs/ui-ux-enterprise-audit/target-images -type f
find docs/ui-ux-enterprise-audit/target-experience-briefs -type f
```
If image dimension validation is available, run an equivalent check and document dimensions. Runtime tests are not required because this is docs/image-only. Full Pest suite must not be run unless unrelated runtime files changed. Pint is not required unless PHP files changed.
## Readiness Criteria
Spec 325 is ready for implementation when `spec.md`, `plan.md`, `tasks.md`, and `checklists/requirements.md` exist; the no-runtime posture is explicit; target brief/image/sidecar requirements are complete; selected-surface rules are bounded; coverage artifact updates are named; validation commands are listed; and no open questions block implementation.

627
specs/325-screenshot-anchored-strategic-target-images/spec.md Normal file
View File

@ -0,0 +1,627 @@
# Feature Specification: Spec 325 - Screenshot-Anchored Strategic Target Images & Experience Briefs
**Feature Branch**: `325-screenshot-anchored-strategic-target-images`
**Created**: 2026-05-17
**Status**: Draft
**Type**: Docs-first / UX productization / target images / strategic design direction
**Depends on**: Spec 323 - Tenantial Enterprise UI Audit Foundation; Spec 324 - UI Productization Coverage Guardrails
**Input**: User supplied full Spec 325 rewrite requiring screenshot-anchored strategic target images and experience briefs instead of rejected generic SVG mockups.
## Premium Visual Reference Addendum *(2026-05-18)*
The user accepted four premium visual reference images as final enough for the Tenantial target direction:
- `docs/ui-ux-enterprise-audit/target-images/reference/spec-325-premium-reference/platform-overview-premium-reference.png`
- `docs/ui-ux-enterprise-audit/target-images/reference/spec-325-premium-reference/governance-inbox-premium-reference.png`
- `docs/ui-ux-enterprise-audit/target-images/reference/spec-325-premium-reference/backup-restore-premium-reference.png`
- `docs/ui-ux-enterprise-audit/target-images/reference/spec-325-premium-reference/evidence-audit-premium-reference.png`
These images are visual calibration references, not implementation truth. They define the accepted premium direction: dark enterprise shell, dense but calm panels, top workspace/tenant context, table/detail workbenches, right-side decision panels, and evidence/audit/restore/governance visual language.
The first generated Spec 325 target PNGs are treated as IA/content scaffolds. The regenerated target PNGs should use the accepted premium reference direction while preserving the existing repo-truth sidecars and safety constraints.
Required corrections before any runtime implementation:
- no green/success state unless backed by repo-verified evidence
- restore execution must look high-friction and safety-gated, not like an ordinary green action
- all concrete metrics, dates, users, entities, actions, and statuses from reference images remain conceptual unless repo-verified
- customer/auditor surfaces must hide raw diagnostics by default
- later implementation specs must verify RBAC, audit, OperationRun continuity, workspace/environment scope, and customer-safe disclosure before coding
## Spec Candidate Check *(mandatory - SPEC-GATE-001)*
- **Problem**: Spec 323 identified strategic UI surfaces, but later implementation specs still lack high-quality, screenshot-anchored target experience artifacts for the most important P0/P1 surfaces.
- **Today's failure**: Generic target mockups can look polished while being disconnected from repo/browser screenshots, page reports, customer-safe data boundaries, dangerous-action risk, and repo-truth limits.
- **User-visible improvement**: Future implementation specs get grounded visual direction that makes surfaces easier to judge for enterprise quality, customer safety, evidence-first hierarchy, and implementation relevance.
- **Smallest enterprise-capable version**: Select 6-10 P0/P1 strategic surfaces, create target experience briefs, screenshot/source references, target image files, sidecars, coverage updates, and grouped follow-up candidates without changing runtime UI.
- **Explicit non-goals**: No runtime UI implementation, no Filament/Livewire/Blade/routes/navigation/provider/database/test/business-logic changes, no one-target-image-per-row expansion, no generic SaaS dashboard pass, no design-system implementation.
- **Permanent complexity imported**: Markdown documentation structure and image artifacts under `docs/ui-ux-enterprise-audit/`; no runtime models, statuses, enums, services, or code framework.
- **Why now**: Spec 323 produced the UI audit baseline and Spec 324 made coverage durable; the next proportional step is target-image direction before implementation waves start.
- **Why not local**: A local note or generic mockup would not preserve screenshot anchoring, repo-truth sidecars, deferred-surface decisions, or reusable follow-up implementation lanes.
- **Approval class**: Workflow Compression
- **Red flags triggered**: Cross-domain UI direction and target-image coverage. Defense: this is docs/image-only, bounded to selected surfaces, and explicitly forbids runtime implementation or conceptual elements as product truth.
- **Score**: Nutzen: 2 | Dringlichkeit: 2 | Scope: 2 | Komplexitat: 1 | Produktnahe: 2 | Wiederverwendung: 2 | **Gesamt: 11/12**
- **Decision**: approve
## Candidate Source & Completed-Spec Guardrail
- **Candidate source**: Direct user-provided manual promotion for Spec 325.
- **Roadmap relationship**: Follows Spec 323/324 UI coverage foundation and prepares later implementation lanes such as Customer Review Workspace productization, Governance Inbox decision experience, Operations Hub productization, Evidence/Review Pack consumption, Drift/Baseline decision experience, Restore safety UX, Provider onboarding/readiness cleanup, and Workspace/Environment dashboard productization.
- **Related completed specs**: Specs 323 and 324 are historical completed/validated context and must not be rewritten.
- **Existing `325-*` check**: `specs/325-tenantial-strategic-surface-target-mockups/` exists only as an untracked/empty directory with an empty `checklists/` directory and no `spec.md`, `plan.md`, `tasks.md`, or tracked artifacts. It is not a completed spec package and is not modified by this preparation pass.
- **Close alternatives deferred**: Spec 326 Tenantial Pattern Library & State System is deferred until Spec 325 produces target-image and experience-brief inputs. Runtime implementation of any selected surface is deferred to later implementation specs.
## Spec Scope Fields *(mandatory)*
- **Scope**: canonical-view
- **Primary Routes**: No runtime routes affected. Source surfaces are selected from `docs/ui-ux-enterprise-audit/strategic-surfaces.md`, page reports, and screenshots.
- **Data Ownership**: No product data ownership changes. Documentation classifies workspace/environment/customer/provider/audit context from existing audit artifacts only.
- **RBAC**: No authorization changes. Briefs must call out customer-safe visibility, capability/RBAC assumptions, and dangerous-action guardrails for later verification.
For canonical-view specs:
- **Default filter behavior when tenant-context is active**: N/A - docs/image target artifacts only.
- **Explicit entitlement checks preventing cross-tenant leakage**: N/A for runtime; target briefs must document workspace/environment/customer-safe boundaries as later implementation requirements.
## UI Surface Impact *(mandatory - UI-COV-001)*
Does this spec add, remove, rename, or materially change any reachable UI surface?
- [x] No UI surface impact
- [ ] Existing page changed
- [ ] New page/route added
- [ ] Navigation changed
- [ ] Filament panel/provider surface changed
- [ ] New modal/drawer/wizard/action added
- [ ] New table/form/state added
- [ ] Customer-facing surface changed
- [ ] Dangerous action changed
- [ ] Status/evidence/review presentation changed
- [ ] Workspace/environment context presentation changed
## 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)*
N/A - no reachable UI surface impact.
- **No-impact rationale**: Spec 325 creates documentation, target experience briefs, target images, annotations, repo-truth sidecars, and follow-up planning artifacts only. It does not modify reachable runtime UI surfaces, routes, Filament resources/pages, Livewire components, Blade views, navigation, panel providers, authorization, database schema, tests, or business logic.
- **Coverage files updated by implementation**: `docs/ui-ux-enterprise-audit/README.md`, `strategic-surfaces.md`, `grouped-follow-up-candidates.md`, `design-coverage-matrix.md` if target-image coverage is tracked, plus new target brief/image/follow-up docs.
## 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, documentation-only
- **Interaction class(es)**: target experience guidance for decision headers, evidence summaries, OperationRun outcome strips, dangerous-action confirmations, detail drawers, empty/loading/error states, customer-safe review summaries, provider readiness steppers, and drift impact summaries.
- **Systems touched**: Documentation and target-image artifacts under `docs/ui-ux-enterprise-audit/`; no runtime systems.
- **Existing pattern(s) to extend**: Spec 323 page reports, strategic surfaces, design coverage matrix, and grouped follow-up candidates.
- **Shared contract / presenter / builder / renderer to reuse**: N/A - no runtime implementation.
- **Why the existing shared path is sufficient or insufficient**: The audit registry can hold target-image coverage and follow-up lanes, but actual reusable runtime patterns are deferred to Spec 326 and later implementation specs.
- **Allowed deviation and why**: Documentation-only target direction may name pattern requirements without creating runtime pattern code.
- **Consistency impact**: Later implementation must verify route/page reality, data availability, RBAC/capabilities, workspace/environment isolation, OperationRun/evidence truth, customer-safe visibility, and dangerous-action guardrails before coding.
- **Review focus**: Ensure target images are not treated as implementation truth and conceptual-future-state elements remain classified.
## OperationRun UX Impact *(mandatory when the feature creates, queues, deduplicates, resumes, blocks, completes, or deep-links to an `OperationRun`; otherwise write `N/A - no OperationRun start or link semantics touched`)*
N/A - no OperationRun start or link semantics touched. Target briefs for operations/restore/evidence surfaces may recommend OperationRun outcome strip or evidence traceability patterns for later implementation, but Spec 325 creates no runs and changes no runtime links.
## Provider Boundary / Platform Core Check *(mandatory when the feature changes shared provider/platform seams, identity scope, governed-subject taxonomy, compare strategy selection, provider connection descriptors, or operator vocabulary that may leak provider-specific semantics into platform-core truth; otherwise write `N/A - no shared provider/platform boundary touched`)*
N/A - no shared provider/platform boundary touched. Target briefs must avoid making Microsoft/provider-specific implementation details into platform-core visual truth unless repo-verified.
## UI / Surface Guardrail Impact *(mandatory when operator-facing surfaces are changed; otherwise write `N/A`)*
| Surface / Change | Operator-facing surface change? | Native vs Custom | Shared-Family Relevance | State Layers Touched | Exception Needed? | Low-Impact / `N/A` Note |
|---|---|---|---|---|---|---|
| Spec 325 target-image and brief artifacts | no runtime surface change | N/A | documentation-only target direction | none | no | Docs/image artifacts only; no reachable UI changed. |
## Decision-First Surface Role *(mandatory when operator-facing surfaces are changed)*
N/A - no operator-facing runtime surface change. The target briefs must still define decision-first roles for selected source surfaces.
## Audience-Aware Disclosure *(mandatory when operator-facing surfaces are changed)*
N/A - no runtime detail/status surface is changed. Customer/auditor-facing target briefs must document customer-safe review requirements and hidden diagnostics.
## UI/UX Surface Classification *(mandatory when operator-facing surfaces are changed)*
N/A - no runtime operator-facing list, detail, queue, audit, config, or report surface is changed.
## Operator Surface Contract *(mandatory when operator-facing surfaces are changed)*
N/A - no runtime operator-facing page is added or refactored. Selected target briefs must include the intended surface contract for later implementation.
## Proportionality Review *(mandatory when structural complexity is introduced)*
- **New source of truth?**: No runtime source of truth. Target images are visual direction artifacts and explicitly not implementation truth.
- **New persisted entity/table/artifact?**: No database persistence. New Markdown and image artifacts are documentation artifacts.
- **New abstraction?**: No runtime abstraction.
- **New enum/state/reason family?**: No.
- **New cross-domain UI framework/taxonomy?**: No runtime framework. Documentation may group later pattern requirements, but reusable component/state system work is deferred to Spec 326.
- **Current operator problem**: Future UI work lacks visual, screenshot-anchored, repo-truth-bounded direction for strategic surfaces.
- **Existing structure is insufficient because**: Spec 323 page reports identify issues but do not supply reviewable visual target images or surface-by-surface transformation briefs.
- **Narrowest correct implementation**: 6-10 selected P0/P1 surfaces, not all 44 strategic rows; target briefs/images/sidecars only.
- **Ownership cost**: Documentation/image review maintenance and risk that future implementers over-copy conceptual visuals without verification.
- **Alternative intentionally rejected**: Generic SVG/SaaS mockups and broad all-surface coverage in one pass.
- **Release truth**: Current-release preparation for later implementation, not implemented runtime truth.
### Compatibility posture
This feature assumes a pre-production environment. No runtime compatibility, migration, or legacy-data behavior is changed.
## Testing / Lane / Runtime Impact *(mandatory for runtime behavior changes)*
- **Test purpose / classification**: N/A for runtime; documentation/static guard validation only.
- **Validation lane(s)**: local documentation/static checks.
- **Why this classification and these lanes are sufficient**: Spec 325 changes docs/image artifacts only and explicitly forbids runtime UI/business/database/test changes.
- **New or expanded test families**: none.
- **Fixture / helper cost impact**: none.
- **Heavy-family visibility / justification**: none.
- **Special surface test profile**: N/A.
- **Standard-native relief or required special coverage**: N/A.
- **Reviewer handoff**: Confirm no product runtime files changed, every selected surface is screenshot/page-report anchored, and target images have sidecars.
- **Budget / baseline / trend impact**: none.
- **Escalation needed**: none.
- **Active feature PR close-out entry**: N/A - docs/image-only.
- **Planned validation commands**: `bash scripts/check-ui-productization-coverage HEAD`; `git diff --check`; optional `bash -n scripts/check-ui-productization-coverage`; optional file/dimension checks for target images.
## Summary
Spec 325 creates screenshot-anchored strategic target experience briefs and high-quality visual target images for the most important Tenantial/TenantPilot product surfaces. It replaces the rejected generic SVG mockup direction with artifacts anchored to current repo/browser screenshots, Spec 323 page reports, Tenantial product principles, and explicit repo-truth sidecars.
The goal is not to generate decorative SaaS dashboards. The goal is to create visual target artifacts that are useful for later implementation specs and visually strong enough to judge whether the target Tenantial experience looks premium, calm, enterprise-grade, understandable, and sellable.
Each selected surface receives:
1. current screenshot reference
2. target experience brief
3. problem/target transformation notes
4. high-quality target image
5. repo-truth sidecar
6. implementation pattern requirements
## Product Context
Tenantial/TenantPilot is an enterprise SaaS platform for Microsoft tenant governance, Intune backup/restore, versioning, audit, evidence, baselines, drift detection, reviews, review packs, supportability, MSP/customer governance workflows, and customer-safe review consumption.
The platform direction is Governance-of-Record, OperationRun execution truth, evidence-first reporting, decision-first workflows, customer-safe review consumption, capability-first RBAC, workspace-first multi-tenancy, calm enterprise UX, progressive disclosure, no raw admin-console default experience, no misleading status, and no green success state unless verified.
## Problem Statement
The first Spec 325 mockup attempt failed because generated SVGs were too generic, repetitive, disconnected from current screenshots, insufficiently tied to repo truth, visually static, and not implementation-relevant.
Removing visuals entirely is also wrong: without target images, reviewers cannot judge whether the future Tenantial experience looks good, premium, enterprise-grade, understandable, and sellable.
Spec 325 therefore creates target images under strict grounding rules. A target image must never be the source of truth alone; it must be accompanied by source screenshot reference, target experience brief, transformation notes, repo-truth classification, and implementation pattern notes.
## Objective
Create high-quality screenshot-anchored target images and target experience briefs for selected P0/P1 strategic surfaces.
This spec must:
1. Select a focused set of strategic surfaces from Spec 323.
2. Use current screenshots/page reports as source anchors.
3. Create target experience briefs for each selected surface.
4. Generate or produce high-quality target images for each selected surface.
5. Ensure each image is grounded in actual current-state problems.
6. Document what changed from current screenshot to target experience.
7. Classify important target elements by repo-truth level.
8. Prevent conceptual/future elements from being presented as implemented.
9. Define implementation pattern requirements for later specs.
10. Update UI audit coverage artifacts.
11. Avoid runtime changes.
## Non-Goals
This spec must not implement product UI, modify Filament pages/resources, modify Livewire components, modify Blade views, modify routes/navigation/panel providers, modify authorization/RBAC, modify database schema, modify product tests, run the full application suite, create product capabilities, treat target images as runtime implementation, treat conceptual target elements as repo-real, generate generic SaaS dashboards, or replace later design-system work.
## Strategic Surface Selection Rules
Spec 325 must select a focused shortlist from Spec 323.
- **Minimum**: 6 surfaces
- **Ideal**: 7-10 surfaces
- **Maximum**: 10 surfaces
Prioritize surfaces that are core to sellability, customer-facing consumption, operator decision workflow, evidence/audit trust, demos, onboarding, dangerous/high-impact workflows, MSP/customer portfolio value, and currently too technical/admin-like but strategically important.
Preferred P0/P1 surface set:
- Customer Review Workspace
- Governance / Decision Inbox
- Operations / Monitoring Hub
- Evidence Overview / Review Pack
- Restore Safety Workflow
- Provider Onboarding / Readiness
- Workspace Dashboard / Home
- Environment Dashboard
- Baseline Compare / Drift Findings
Do not select every list page, CRUD resource, settings subpage, repeated inventory page, unresolved page without sufficient context, utility page, internal-only page, or page that should be covered by a later domain pattern.
## Required Output Structure
Implementation must create or update:
```text
docs/ui-ux-enterprise-audit/
target-experience-briefs/
README.md
strategic-target-image-shortlist.md
<surface-slug>.md
target-images/
README.md
source/
<surface-slug>-source.png
problem-annotations/
<surface-slug>-problem.png
target/
<surface-slug>-target-dark.png
<surface-slug>-target-light.png
<surface-slug>-target.md
rejected/
spec-325-initial-svg-pass/
README.md
follow-up-specs/
325-strategic-target-image-implementation-candidates.md
```
If source screenshots already exist under Spec 323, linking to existing screenshots is acceptable and preferred over duplication unless a source copy is needed for review stability.
## Rejected Mockup Handling
If previous rejected Spec 325 SVG mockups remain in the working tree, move them to:
```text
docs/ui-ux-enterprise-audit/target-images/rejected/spec-325-initial-svg-pass/
```
Add a `README.md` stating that those files are rejected exploration artifacts, not accepted target experiences, not implementation targets, and must not be used as source of truth. The reason is that the initial SVG pass was too generic, insufficiently anchored to current repo/browser screenshots, visually repetitive, and looked like static SaaS placeholder UI rather than actionable target experience guidance.
If no rejected mockups remain, document that in the final response.
## Target Image Policy
Target images are required, but valid only if they:
1. Reference a current screenshot or page report.
2. Are accompanied by a target experience brief.
3. Include repo-truth sidecar notes.
4. Explain what changed from current state.
5. Avoid generic SaaS placeholder design.
6. Do not present conceptual features as implemented.
Allowed artifacts are current screenshot references, problem annotation images, high-quality target images, dark target variants, light target variants where useful, repo-truth sidecars, and transformation notes.
Not allowed: generic SaaS dashboards, decorative placeholder mockups, unanchored UI fantasy screens, repeated card-grid layouts without page-specific logic, fake compliance claims, fake product features, unrelated labels, or target images without sidecar explanation.
## Target Image Requirements
For every selected surface, create at least:
```text
docs/ui-ux-enterprise-audit/target-images/target/<surface-slug>-target-dark.png
```
Light variant is required for customer-facing, auditor-facing, management-facing review/evidence, customer-meeting, document, or review-consumption experiences:
```text
docs/ui-ux-enterprise-audit/target-images/target/<surface-slug>-target-light.png
```
Preferred format is PNG. Preferred resolution is `1600 x 900`; allowed resolutions are `1728 x 972`, `1920 x 1080`, and `1920 x 1200`. Images must be readable at desktop review size.
## Target Image Sidecar Requirements
For every target image, create:
```text
docs/ui-ux-enterprise-audit/target-images/target/<surface-slug>-target.md
```
Each sidecar must include source screenshot, source page report, source route, target experience brief, image files, a transformation table, repo-truth classification table, a "Not Implementation Truth" notice, conceptual elements requiring verification, implementation notes, and do-not-implement-blindly notes.
Repo-truth classifications must use exactly:
- `repo-verified`
- `plausible-existing`
- `foundation-only`
- `spec-only`
- `conceptual-future-state`
- `unknown`
## Required Shortlist Artifact
Create:
```text
docs/ui-ux-enterprise-audit/target-experience-briefs/strategic-target-image-shortlist.md
```
It must summarize source, selected surfaces, deferred surfaces, selection date, branch, commit, a selected-surface table with source screenshot/report links, rejected mockup handling, and selection rationale explaining why the shortlist is proportional.
## Target Experience Brief Requirements
For every selected surface, create:
```text
docs/ui-ux-enterprise-audit/target-experience-briefs/<surface-slug>.md
```
Each brief must include metadata, current-state snapshot, current-state productization problems, target user promise, primary persona, first-five-seconds target, primary decision, primary action, secondary actions, target information hierarchy, keep/promote/simplify table, detail drawer table, advanced/admin table, hidden/removed table, target layout direction, visual target direction, status/trust model, dangerous actions, customer-safe review notes where applicable, workspace/environment context, empty/loading/error states, accessibility notes, repo-truth classification, image generation prompt, implementation pattern requirements, later implementation candidate, and non-goals for later implementation.
## Image Generation Prompt Rules
Every generated target image prompt must:
- Start from the provided current screenshot as source context.
- State that the output is a target design direction, not runtime implementation.
- Preserve the real page purpose.
- Include current problems, target user promise, primary persona, primary decision, primary action, information hierarchy, main-view items, technical details to move secondary, repo-truth constraints, visual direction, and output requirements.
- Explicitly avoid generic blue SaaS, fake compliance claims, green success without verification, placeholder nonsense text, decorative charts, repeated generic card dashboards, and runtime implementation claims.
Prompts like `Create a modern SaaS dashboard for ...` are not acceptable.
## Brand Requirements
Use Tenantial brand direction: calm, precise, premium, enterprise-grade, operator-first, evidence-first, workspace-aware, controlled, and trustworthy.
Avoid generic blue SaaS, raw admin console, cybersecurity cliche, neon dashboard, overloaded charts, fake compliance marketing, Microsoft admin clone, and random startup design.
Core token direction from the user-provided draft:
```css
--color-obsidian: #080807;
--color-carbon: #151412;
--color-graphite: #1E1D1A;
--color-warm-slate: #292722;
--color-ivory: #F4EFE6;
--color-sand: #C8BFAE;
--color-muted-sand: #8F887B;
--color-mint: #6CFFB8;
--color-mint-soft: #B8FFE0;
--color-mint-muted: #2DDC8F;
--color-violet: #9B8CFF;
--color-amber: #D6A84F;
--color-coral: #FF6B5F;
```
Mint is a signature accent, not a dominant flood color. The existing `docs/brand/tenantial-brand-context.md` is only a placeholder; final brand fidelity still requires repo/user verification.
## Product UX Requirements
Every target image and brief must show or explain:
1. page promise
2. current posture/state
3. reason/impact
4. primary next action
5. evidence/traceability path
6. workspace/environment context
7. technical detail through progressive disclosure
Every target image and brief must avoid raw technical details as default, too many equal buttons, unprioritized tables, green status without verification, unsupported compliance promises, hidden context, customer-visible debug data, and fake feature claims.
## Surface-Specific Guidance
- **Customer Review Workspace**: customer-safe read-only review/finding/risk/evidence/review-pack consumption; hide raw OperationRuns, provider diagnostics, internal IDs, and operator-only controls.
- **Governance / Decision Inbox**: operator triage and governance decisions; show action need, reason, owner, due/overdue, recommended next action, and supporting evidence.
- **Operations / Monitoring Hub**: execution truth and follow-up; show what ran, failed, reason/impact, next action, and evidence/run proof; avoid raw job log table as primary UX.
- **Evidence Overview / Review Pack**: audit-ready evidence inventory and review consumption; show freshness, linked review/report/run, export readiness, missing evidence, and safe shareability.
- **Drift Findings / Baseline Compare**: show what changed, compared baseline, impact, owner, and required decision; avoid raw diff noise first.
- **Restore Safety Workflow**: safe restore decision and auditable execution; show source, scope, safety gates, impact, confirmation, and evidence result; restore must not look ordinary.
- **Provider Onboarding / Readiness**: explain connection/permission/verification gaps and next action; diagnostics remain secondary.
- **Workspace / Environment Dashboard**: calm entry point for governance posture and next actions; avoid raw metric wall and duplicated navigation.
## Follow-Up Implementation Candidates
Create:
```text
docs/ui-ux-enterprise-audit/follow-up-specs/325-strategic-target-image-implementation-candidates.md
```
Candidate lanes must be grouped proportionally and include:
- Customer Review Workspace productization
- Governance Inbox decision experience
- Operations Hub productization
- Evidence/Review Pack consumption productization
- Drift/Baseline decision experience
- Restore safety UX productization
- Provider onboarding/readiness UX cleanup
- Workspace/Environment dashboard productization
Do not create one implementation candidate per tiny surface unless justified.
## Coverage Artifact Updates
Implementation must update:
- `docs/ui-ux-enterprise-audit/README.md` with a Spec 325 section and links.
- `docs/ui-ux-enterprise-audit/strategic-surfaces.md` to mark selected and deferred surfaces.
- `docs/ui-ux-enterprise-audit/grouped-follow-up-candidates.md` with later implementation lane references.
- `docs/ui-ux-enterprise-audit/design-coverage-matrix.md` if target-image coverage is tracked; runtime implemented must remain `No`.
Do not remove existing rows from strategic surface or coverage artifacts.
## Visual Review Criteria
Each target image must pass these checks:
1. clearly based on current page purpose
2. not generic SaaS dashboard
3. shows primary status/posture
4. shows primary decision/action
5. communicates reason/impact
6. makes evidence or traceability visible
7. keeps diagnostics secondary
8. shows workspace/environment context
9. avoids fake green success
10. avoids unsupported compliance claims
11. is visually calm and enterprise-grade
12. can be explained from the target brief
Failing images must be regenerated or marked rejected.
## User Scenarios & Testing *(mandatory)*
### User Story 1 - Select a Proportional Strategic Shortlist (Priority: P1)
As a product/design reviewer, I need Spec 325 to select only the most important P0/P1 surfaces from Spec 323 so target-image work remains focused and useful.
**Why this priority**: Without selection discipline, the work becomes a broad mockup dump rather than actionable strategic guidance.
**Independent Test**: Review `strategic-target-image-shortlist.md` and verify it contains 6-10 selected surfaces, deferred surfaces, source links, and rationale.
**Acceptance Scenarios**:
1. **Given** Spec 323 strategic surfaces, **When** Spec 325 selects target surfaces, **Then** no more than 10 surfaces are selected and the rest are deferred with reasons.
2. **Given** a selected surface, **When** a reviewer inspects the shortlist, **Then** the source screenshot or page report is linked.
---
### User Story 2 - Create Screenshot-Anchored Target Briefs (Priority: P1)
As a later implementation agent, I need target experience briefs that describe current-state problems, target promise, decision hierarchy, action hierarchy, repo-truth limits, and implementation patterns for each selected surface.
**Why this priority**: Briefs make target images implementation-relevant and prevent conceptual visuals from becoming false product truth.
**Independent Test**: Open each selected surface brief and verify it includes all required sections and repo-truth classifications.
**Acceptance Scenarios**:
1. **Given** a selected surface, **When** its target brief is reviewed, **Then** it describes concrete current-state problems from source screenshot/page report evidence.
2. **Given** conceptual future elements in a target direction, **When** the brief classifies target elements, **Then** conceptual items are marked `conceptual-future-state` or another allowed repo-truth value and are not presented as implemented.
---
### User Story 3 - Create Valid Target Images and Sidecars (Priority: P1)
As a product/design reviewer, I need readable target images with sidecars so I can judge visual direction while preserving source/repo-truth context.
**Why this priority**: Target images are the main deliverable, but only valid when anchored and explained.
**Independent Test**: Review target image files and sidecars for each selected surface and verify source, brief, transformation, repo-truth, and implementation notes are present.
**Acceptance Scenarios**:
1. **Given** a selected surface, **When** target image artifacts are reviewed, **Then** at least one dark PNG target image exists and required light variants exist or are justified.
2. **Given** a target image, **When** its sidecar is reviewed, **Then** it explains what changed from current state and states the image is not implementation truth.
---
### User Story 4 - Update Coverage and Follow-Up Planning (Priority: P2)
As a spec owner, I need UI audit artifacts updated so target-image coverage and later implementation lanes remain discoverable.
**Why this priority**: Without registry updates, target artifacts become detached from the durable Spec 323/324 coverage system.
**Independent Test**: Review README, strategic surfaces, grouped follow-ups, design coverage matrix where applicable, and follow-up implementation candidates.
**Acceptance Scenarios**:
1. **Given** selected and deferred surfaces, **When** `strategic-surfaces.md` is reviewed, **Then** selected/deferred state is recorded without removing rows.
2. **Given** target-image outputs, **When** README and follow-up candidates are reviewed, **Then** later implementation lanes are grouped proportionally and link back to the artifacts.
## Functional Requirements
- **FR-325-001**: The implementation MUST create or update `docs/ui-ux-enterprise-audit/target-experience-briefs/README.md`.
- **FR-325-002**: The implementation MUST create `strategic-target-image-shortlist.md` with 6-10 selected P0/P1 surfaces and deferred surfaces.
- **FR-325-003**: Selected surfaces MUST come from Spec 323 strategic surfaces, screenshots, and/or page reports.
- **FR-325-004**: The shortlist MUST document selection date, branch, commit, source links, personas, rationale, target brief links, target image links, and rejected mockup handling.
- **FR-325-005**: Previous rejected mockup remnants MUST be moved to the rejected folder when present, or absence MUST be documented.
- **FR-325-006**: Every selected surface MUST have a target experience brief under `target-experience-briefs/`.
- **FR-325-007**: Every target brief MUST reference a source screenshot and/or page report.
- **FR-325-008**: Every target brief MUST include current-state snapshot and concrete current-state productization problems.
- **FR-325-009**: Every target brief MUST define target user promise, primary persona, first-five-seconds target, primary decision, primary action, and secondary actions.
- **FR-325-010**: Every target brief MUST define target information hierarchy and main-view/detail-drawer/advanced-admin/hidden-default treatments.
- **FR-325-011**: Every target brief MUST document visual direction, target layout direction, status/trust model, empty/loading/error states, accessibility notes, and workspace/environment context.
- **FR-325-012**: Dangerous-action surfaces MUST document risk, required guardrails, and evidence result.
- **FR-325-013**: Customer-facing or auditor-facing surfaces MUST document customer-safe review notes and hidden diagnostics.
- **FR-325-014**: Every target brief MUST classify important target elements using the allowed repo-truth values.
- **FR-325-015**: Every target brief MUST include a screenshot-anchored image generation prompt using the required prompt structure.
- **FR-325-016**: Every target brief MUST define implementation pattern requirements and later implementation candidate lane.
- **FR-325-017**: The implementation MUST create `docs/ui-ux-enterprise-audit/target-images/README.md`.
- **FR-325-018**: Every selected surface MUST have at least one dark target image under `target-images/target/`.
- **FR-325-019**: Customer/auditor/management-facing selected surfaces MUST have a light target image or a documented reason why not.
- **FR-325-020**: Target images SHOULD be PNG and SHOULD use preferred or allowed desktop resolutions.
- **FR-325-021**: Every target image MUST have a sidecar Markdown file under `target-images/target/`.
- **FR-325-022**: Every sidecar MUST link source screenshot, page report, route, target brief, and image files.
- **FR-325-023**: Every sidecar MUST include a transformation table and repo-truth classification table.
- **FR-325-024**: Every sidecar MUST state target images are visual direction only, not runtime implementation truth.
- **FR-325-025**: Target images MUST avoid generic SaaS dashboards, fake compliance claims, fake green success, unsupported product claims, raw diagnostics as default, and unrelated labels.
- **FR-325-026**: `docs/ui-ux-enterprise-audit/README.md` MUST link to Spec 325 shortlist, brief folder, target image folder, and follow-up implementation candidates.
- **FR-325-027**: `strategic-surfaces.md` MUST mark selected and deferred states without removing rows.
- **FR-325-028**: `grouped-follow-up-candidates.md` MUST reference later implementation lanes for selected surfaces.
- **FR-325-029**: `design-coverage-matrix.md` MUST add target-image coverage if that matrix tracks it; runtime implemented MUST remain `No`.
- **FR-325-030**: The implementation MUST create `325-strategic-target-image-implementation-candidates.md` with grouped candidate lanes, recommended order, do-not-implement-yet notes, and pattern dependencies.
- **FR-325-031**: No product runtime files under `apps/platform/app/Filament/`, `apps/platform/app/Livewire/`, `apps/platform/resources/views/`, `apps/platform/routes/`, `apps/platform/config/`, `apps/platform/database/`, or `apps/platform/tests/` may be changed.
- **FR-325-032**: Validation MUST include `bash scripts/check-ui-productization-coverage HEAD` and `git diff --check`.
- **FR-325-033**: Full Pest/runtime suite MUST be documented as not run unless runtime files changed, which this spec forbids.
- **FR-325-034**: Pint MUST be documented as not run unless PHP files changed, which this spec forbids.
## Non-Functional Requirements
- **NFR-325-001**: Artifacts must be repo-based and not present conceptual/spec-only UI as implemented product truth.
- **NFR-325-002**: Markdown must be reviewable, stable, and useful for later implementation agents without replaying a browser session.
- **NFR-325-003**: Image and file names must use stable surface slugs.
- **NFR-325-004**: Target images must be readable at desktop review size.
- **NFR-325-005**: Work must remain bounded to docs/image artifacts and coverage docs.
- **NFR-325-006**: The target set must remain proportional; do not cover all 44 strategic rows.
- **NFR-325-007**: Visual direction must align with calm, precise, premium, enterprise-grade, operator-first, evidence-first, workspace-aware, controlled, trustworthy Tenantial posture.
## Assumptions
- Spec 323 audit artifacts and screenshots remain the current source baseline.
- Spec 324 guardrail script exists and should pass for docs/image-only changes.
- Target image generation may use AI image generation or another image creation workflow, but final artifacts must be screenshot-anchored and sidecar-documented.
- The existing brand context is incomplete; user-provided brand token direction in this spec is enough for target direction but not final brand governance.
- Exact selected surfaces are chosen during Spec 325 implementation after reading current Spec 323 artifacts.
## Risks
- Target images may become generic if prompts do not include source screenshot, page purpose, current problems, primary decision/action, and repo-truth constraints.
- Conceptual elements may be mistaken for implemented product truth unless sidecars and briefs classify them explicitly.
- Image generation may produce unreadable text or misleading status; failing images must be regenerated or rejected.
- Existing empty `specs/325-tenantial-strategic-surface-target-mockups/` directory can cause Spec Kit prefix warnings; this preparation pass leaves it untouched because it contains no tracked spec files.
## Acceptance Criteria
1. Strategic target image shortlist exists.
2. Shortlist selects no more than 10 surfaces.
3. Selected surfaces are based on Spec 323 artifacts.
4. Deferred strategic surfaces are documented.
5. Rejected mockup remnants are moved or absence is documented.
6. Every selected surface has a target experience brief.
7. Every selected surface references a current screenshot and/or page report.
8. Every selected surface has at least one target image.
9. Customer/auditor/management-facing selected surfaces have a light target image or documented reason.
10. Every target image has a sidecar Markdown file.
11. Every sidecar explains what changed from current state.
12. Every sidecar includes repo-truth classification.
13. Every target brief describes concrete current-state problems.
14. Every target brief defines target user promise, primary persona, first-five-seconds target, primary decision, primary action, and target hierarchy.
15. Every target brief identifies main-view, drawer/details, advanced/admin, and hidden/default treatments.
16. Every target brief documents status/trust model and dangerous actions where applicable.
17. Every customer-facing surface includes customer-safe review notes.
18. Follow-up implementation candidates are grouped proportionally.
19. `strategic-surfaces.md`, `grouped-follow-up-candidates.md`, README, and coverage matrix where applicable are updated.
20. No target image is accepted without source screenshot/brief/sidecar.
21. No target image presents conceptual-future-state elements as implemented.
22. No product runtime files are modified.
23. `bash scripts/check-ui-productization-coverage HEAD` passes.
24. `git diff --check` passes.
25. Full Pest/runtime suite and Pint are explicitly documented as not run for this docs/image-only work.
## Success Criteria
- Reviewers can identify the selected strategic surfaces, source screenshot/report anchor, and target direction within 5 minutes.
- 100% of selected surfaces have brief, image, and sidecar coverage.
- 100% of important target elements have allowed repo-truth classification.
- 0 runtime product files are changed.
- Later implementation candidates are grouped into proportional lanes rather than one spec per tiny page.
## Open Questions
None blocking preparation. Implementation must still verify exact selected surfaces, source screenshot quality, image generation method, and whether target-image coverage belongs in the current design coverage matrix.

157
specs/325-screenshot-anchored-strategic-target-images/tasks.md Normal file
View File

@ -0,0 +1,157 @@
# Tasks: Spec 325 - Screenshot-Anchored Strategic Target Images & Experience Briefs
**Input**: `specs/325-screenshot-anchored-strategic-target-images/spec.md` and `plan.md`
**Prerequisites**: Spec 323 audit artifacts and Spec 324 guardrail script exist on the active branch.
**Runtime posture**: Docs/image target artifacts only. No product runtime implementation.
## Phase 1: Inspect Inputs
- [x] T001 Read `docs/ui-ux-enterprise-audit/strategic-surfaces.md`.
- [x] T002 Read `docs/ui-ux-enterprise-audit/design-coverage-matrix.md`.
- [x] T003 Read `docs/ui-ux-enterprise-audit/grouped-follow-up-candidates.md`.
- [x] T004 Read relevant files under `docs/ui-ux-enterprise-audit/page-reports/`.
- [x] T005 Inspect available current screenshots under `docs/ui-ux-enterprise-audit/screenshots/desktop/`.
- [x] T006 Read `docs/brand/tenantial-brand-context.md` and carry forward the user-provided Spec 325 brand token direction without treating placeholder brand docs as final brand truth.
- [x] T007 Confirm Spec 324 guardrail expectations in `scripts/check-ui-productization-coverage` and `specs/324-ui-productization-coverage-guardrails/`.
- [x] T008 Confirm the implementation diff remains outside product runtime paths under `apps/platform/`.
## Phase 2: Select Strategic Shortlist
- [x] T009 Select 6-10 P0/P1 surfaces from `docs/ui-ux-enterprise-audit/strategic-surfaces.md`.
- [x] T010 Explain why the selected set is proportional and why all 44 strategic rows are not covered.
- [x] T011 Document deferred strategic surfaces and recommended later coverage.
- [x] T012 Create `docs/ui-ux-enterprise-audit/target-experience-briefs/strategic-target-image-shortlist.md`.
- [x] T013 In the shortlist, include source screenshot links, page report links, persona, target brief link, target image link, and repo-truth notes for each selected surface.
## Phase 3: Handle Rejected Mockup Remnants
- [x] T014 Check whether previous Spec 325 mockup artifacts remain under `docs/ui-ux-enterprise-audit/mockups/`, `docs/ui-ux-enterprise-audit/target-images/`, or the working tree.
- [x] T015 If rejected remnants exist, move them to `docs/ui-ux-enterprise-audit/target-images/rejected/spec-325-initial-svg-pass/`. N/A: no rejected mockup remnants were present.
- [x] T016 If rejected remnants exist, add `docs/ui-ux-enterprise-audit/target-images/rejected/spec-325-initial-svg-pass/README.md` explaining why they are rejected. Satisfied by folder README documenting no remnants and rejection policy.
- [x] T017 If no rejected remnants remain, document that fact in the final implementation response and shortlist artifact.
## Phase 4: Prepare Artifact Structure
- [x] T018 Create `docs/ui-ux-enterprise-audit/target-experience-briefs/`.
- [x] T019 Create `docs/ui-ux-enterprise-audit/target-experience-briefs/README.md`.
- [x] T020 Create `docs/ui-ux-enterprise-audit/target-images/`.
- [x] T021 Create `docs/ui-ux-enterprise-audit/target-images/README.md`.
- [x] T022 Create `docs/ui-ux-enterprise-audit/target-images/source/`.
- [x] T023 Create `docs/ui-ux-enterprise-audit/target-images/problem-annotations/` if used. N/A for annotation images; folder README documents that current-state problems live in briefs and sidecars.
- [x] T024 Create `docs/ui-ux-enterprise-audit/target-images/target/`.
- [x] T025 Create or reuse `docs/ui-ux-enterprise-audit/follow-up-specs/`.
## Phase 5: Create Target Experience Briefs
For each selected surface:
- [x] T026 Reference source screenshot/page report in `docs/ui-ux-enterprise-audit/target-experience-briefs/<surface-slug>.md`.
- [x] T027 Describe the current-state snapshot without inventing current UI.
- [x] T028 Describe concrete current-state productization problems.
- [x] T029 Define target user promise, primary persona, and secondary personas.
- [x] T030 Define first-five-seconds target.
- [x] T031 Define primary decision, primary action, and visible secondary actions.
- [x] T032 Define target information hierarchy.
- [x] T033 Define main-view keep/promote/simplify treatment.
- [x] T034 Define detail drawer treatment.
- [x] T035 Define advanced/admin treatment.
- [x] T036 Define hidden/removed default elements.
- [x] T037 Define target layout direction and visual target direction.
- [x] T038 Define status/trust model with no green/success state unless verified.
- [x] T039 Define dangerous-action guardrails where applicable.
- [x] T040 Define customer-safe review notes where applicable.
- [x] T041 Define workspace/environment context, empty state, loading state, error state, and accessibility notes.
- [x] T042 Define repo-truth classifications for important target elements using allowed values.
- [x] T043 Define screenshot-anchored image generation prompt.
- [x] T044 Define implementation pattern requirements, later implementation candidate, and non-goals for later implementation.
## Phase 6: Create Target Images
For each selected surface:
- [x] T045 Create at least one target image under `docs/ui-ux-enterprise-audit/target-images/target/<surface-slug>-target-dark.png`.
- [x] T046 Create light target image under `docs/ui-ux-enterprise-audit/target-images/target/<surface-slug>-target-light.png` where required.
- [x] T047 Use screenshot-anchored prompt from the target brief.
- [x] T048 Avoid generic SaaS layout, fake feature claims, unsupported compliance claims, and placeholder nonsense text.
- [x] T049 Avoid green success unless verified by repo/source truth.
- [x] T050 Keep text readable at desktop review size.
- [x] T051 Keep workspace/environment context visible.
- [x] T052 Keep primary decision/action visible.
- [x] T053 Keep technical diagnostics secondary.
- [x] T054 Reject or regenerate any target image that fails the visual review criteria.
- [x] T054A Add user-accepted premium visual reference images under `docs/ui-ux-enterprise-audit/target-images/reference/spec-325-premium-reference/`.
- [x] T054B Regenerate target PNGs using the accepted premium reference direction while preserving repo-truth and safety sidecar constraints.
## Phase 7: Create Target Image Sidecars
For each selected surface:
- [x] T055 Create `docs/ui-ux-enterprise-audit/target-images/target/<surface-slug>-target.md`.
- [x] T056 Link source screenshot, source page report, source route, target brief, and target image files.
- [x] T057 Document what changed from current state in a transformation table.
- [x] T058 Add repo-truth classification table.
- [x] T059 Document conceptual elements requiring verification.
- [x] T060 Add implementation notes.
- [x] T061 Add do-not-implement-blindly notes.
- [x] T062 Include the required "Not Implementation Truth" notice.
## Phase 8: Update Coverage Artifacts
- [x] T063 Update `docs/ui-ux-enterprise-audit/strategic-surfaces.md` to mark selected surfaces as `Selected for Spec 325 target image` and deferred surfaces with a proportional deferral reason.
- [x] T064 Update `docs/ui-ux-enterprise-audit/design-coverage-matrix.md` if target image coverage is tracked, with runtime implemented set to `No`.
- [x] T065 Update `docs/ui-ux-enterprise-audit/grouped-follow-up-candidates.md` with references from selected surfaces to later implementation lanes.
- [x] T066 Update `docs/ui-ux-enterprise-audit/README.md` with the Spec 325 section and links to shortlist, brief folder, target image folder, and follow-up implementation candidates.
## Phase 9: Create Follow-Up Implementation Candidates
- [x] T067 Create `docs/ui-ux-enterprise-audit/follow-up-specs/325-strategic-target-image-implementation-candidates.md`.
- [x] T068 Group implementation lanes proportionally instead of creating one candidate per tiny page.
- [x] T069 Include candidate lanes for customer review workspace, governance inbox, operations hub, evidence/review pack, drift/baseline, restore safety, provider onboarding/readiness, and workspace/environment dashboard productization where supported by selected surfaces.
- [x] T070 Mark conceptual elements requiring repo verification before implementation.
- [x] T071 Mark shared pattern dependencies and recommend Spec 326 Tenantial Pattern Library & State System as the next pattern extraction spec.
## Phase 10: Validate
- [x] T072 Run `bash scripts/check-ui-productization-coverage HEAD` from the repository root.
- [x] T073 Run `git diff --check` from the repository root.
- [x] T074 Optionally run `bash -n scripts/check-ui-productization-coverage`.
- [x] T075 Confirm no product runtime files changed under `apps/platform/app/Filament/`, `apps/platform/app/Livewire/`, `apps/platform/resources/views/`, `apps/platform/routes/`, `apps/platform/config/`, `apps/platform/database/`, or `apps/platform/tests/`.
- [x] T076 Confirm every selected target image has a source screenshot/page report, target brief, and sidecar.
- [x] T077 If image dimension validation is available, run it and document dimensions; `file docs/ui-ux-enterprise-audit/target-images/target/*-target-*.png` confirmed all 18 target PNGs are 1600 x 900.
- [x] T078 Document full Pest/runtime suite not run because this spec is docs/image-only.
- [x] T079 Document Pint not run because no PHP files changed.
## Requirements Traceability
| Requirement(s) | Task Coverage |
|---|---|
| FR-325-001, FR-325-002, FR-325-003, FR-325-004 | T001-T013 |
| FR-325-005 | T014-T017 |
| FR-325-006 through FR-325-016 | T026-T044 |
| FR-325-017 through FR-325-025 | T020-T024, T045-T062 |
| FR-325-026 through FR-325-030 | T063-T071 |
| FR-325-031 | T008, T075 |
| FR-325-032 | T072-T073 |
| FR-325-033, FR-325-034 | T078-T079 |
| NFR-325-001, NFR-325-002, NFR-325-003 | T012-T013, T026-T044, T055-T062 |
| NFR-325-004, NFR-325-005, NFR-325-006, NFR-325-007 | T009-T011, T045-T054, T072-T079 |
## Dependency Notes
- Phases 1-2 must complete before briefs or images are created.
- Phase 5 target briefs should be drafted before image generation for each surface.
- Phase 7 sidecars depend on final accepted target images.
- Phase 8 coverage updates depend on the selected/deferred surface list.
- Phase 10 validation is final and must confirm runtime posture.
## MVP Scope
The minimum viable Spec 325 implementation is 6 selected surfaces, complete briefs, at least dark target images, required light variants for customer/auditor/management-facing surfaces, sidecars, coverage updates, follow-up candidates, and required validation.
## Non-Goals During Implementation
- Do not implement runtime UI.
- Do not modify Filament, Livewire, Blade, routes, navigation, providers, policies, migrations, tests, or business logic.
- Do not make target images a source of product truth.
- Do not create a design-system/pattern-library runtime implementation.
- Do not cover all strategic surfaces in this spec.