TenantAtlas/specs/325-screenshot-anchored-strategic-target-images/spec.md

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?

• 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:

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:

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:

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:

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:

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:

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:

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:

--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:

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.