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

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

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 scripts/check-ui-productization-coverage HEAD
git diff --check

Optional:

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.