ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
platform-dev
TenantAtlas/specs/325-screenshot-anchored-strategic-target-images/tasks.md
ahmido 3eff4d8579 Spec 325: add screenshot-anchored strategic target images (#385) 
## Summary
- add the Spec 325 artifacts for screenshot-anchored strategic target images
- update the UI/UX enterprise audit documents to capture strategic surfaces and grouped follow-up candidates
- add supporting follow-up specs, target experience briefs, and target image assets for the audit workflow

## Testing
- not run (documentation/spec artifact changes only)

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #385
2026-05-18 07:18:13 +00:00

10 KiB
Raw Permalink Blame History

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

  • T001 Read docs/ui-ux-enterprise-audit/strategic-surfaces.md.
  • T002 Read docs/ui-ux-enterprise-audit/design-coverage-matrix.md.
  • T003 Read docs/ui-ux-enterprise-audit/grouped-follow-up-candidates.md.
  • T004 Read relevant files under docs/ui-ux-enterprise-audit/page-reports/.
  • T005 Inspect available current screenshots under docs/ui-ux-enterprise-audit/screenshots/desktop/.
  • 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.
  • T007 Confirm Spec 324 guardrail expectations in scripts/check-ui-productization-coverage and specs/324-ui-productization-coverage-guardrails/.
  • T008 Confirm the implementation diff remains outside product runtime paths under apps/platform/.

Phase 2: Select Strategic Shortlist

  • T009 Select 6-10 P0/P1 surfaces from docs/ui-ux-enterprise-audit/strategic-surfaces.md.
  • T010 Explain why the selected set is proportional and why all 44 strategic rows are not covered.
  • T011 Document deferred strategic surfaces and recommended later coverage.
  • T012 Create docs/ui-ux-enterprise-audit/target-experience-briefs/strategic-target-image-shortlist.md.
  • 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

  • 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.
  • 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.
  • 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.
  • T017 If no rejected remnants remain, document that fact in the final implementation response and shortlist artifact.

Phase 4: Prepare Artifact Structure

  • T018 Create docs/ui-ux-enterprise-audit/target-experience-briefs/.
  • T019 Create docs/ui-ux-enterprise-audit/target-experience-briefs/README.md.
  • T020 Create docs/ui-ux-enterprise-audit/target-images/.
  • T021 Create docs/ui-ux-enterprise-audit/target-images/README.md.
  • T022 Create docs/ui-ux-enterprise-audit/target-images/source/.
  • 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.
  • T024 Create docs/ui-ux-enterprise-audit/target-images/target/.
  • T025 Create or reuse docs/ui-ux-enterprise-audit/follow-up-specs/.

Phase 5: Create Target Experience Briefs

For each selected surface:

  • T026 Reference source screenshot/page report in docs/ui-ux-enterprise-audit/target-experience-briefs/<surface-slug>.md.
  • T027 Describe the current-state snapshot without inventing current UI.
  • T028 Describe concrete current-state productization problems.
  • T029 Define target user promise, primary persona, and secondary personas.
  • T030 Define first-five-seconds target.
  • T031 Define primary decision, primary action, and visible secondary actions.
  • T032 Define target information hierarchy.
  • T033 Define main-view keep/promote/simplify treatment.
  • T034 Define detail drawer treatment.
  • T035 Define advanced/admin treatment.
  • T036 Define hidden/removed default elements.
  • T037 Define target layout direction and visual target direction.
  • T038 Define status/trust model with no green/success state unless verified.
  • T039 Define dangerous-action guardrails where applicable.
  • T040 Define customer-safe review notes where applicable.
  • T041 Define workspace/environment context, empty state, loading state, error state, and accessibility notes.
  • T042 Define repo-truth classifications for important target elements using allowed values.
  • T043 Define screenshot-anchored image generation prompt.
  • T044 Define implementation pattern requirements, later implementation candidate, and non-goals for later implementation.

Phase 6: Create Target Images

For each selected surface:

  • T045 Create at least one target image under docs/ui-ux-enterprise-audit/target-images/target/<surface-slug>-target-dark.png.
  • T046 Create light target image under docs/ui-ux-enterprise-audit/target-images/target/<surface-slug>-target-light.png where required.
  • T047 Use screenshot-anchored prompt from the target brief.
  • T048 Avoid generic SaaS layout, fake feature claims, unsupported compliance claims, and placeholder nonsense text.
  • T049 Avoid green success unless verified by repo/source truth.
  • T050 Keep text readable at desktop review size.
  • T051 Keep workspace/environment context visible.
  • T052 Keep primary decision/action visible.
  • T053 Keep technical diagnostics secondary.
  • T054 Reject or regenerate any target image that fails the visual review criteria.
  • T054A Add user-accepted premium visual reference images under docs/ui-ux-enterprise-audit/target-images/reference/spec-325-premium-reference/.
  • 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:

  • T055 Create docs/ui-ux-enterprise-audit/target-images/target/<surface-slug>-target.md.
  • T056 Link source screenshot, source page report, source route, target brief, and target image files.
  • T057 Document what changed from current state in a transformation table.
  • T058 Add repo-truth classification table.
  • T059 Document conceptual elements requiring verification.
  • T060 Add implementation notes.
  • T061 Add do-not-implement-blindly notes.
  • T062 Include the required "Not Implementation Truth" notice.

Phase 8: Update Coverage Artifacts

  • 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.
  • T064 Update docs/ui-ux-enterprise-audit/design-coverage-matrix.md if target image coverage is tracked, with runtime implemented set to No.
  • T065 Update docs/ui-ux-enterprise-audit/grouped-follow-up-candidates.md with references from selected surfaces to later implementation lanes.
  • 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

  • T067 Create docs/ui-ux-enterprise-audit/follow-up-specs/325-strategic-target-image-implementation-candidates.md.
  • T068 Group implementation lanes proportionally instead of creating one candidate per tiny page.
  • 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.
  • T070 Mark conceptual elements requiring repo verification before implementation.
  • T071 Mark shared pattern dependencies and recommend Spec 326 Tenantial Pattern Library & State System as the next pattern extraction spec.

Phase 10: Validate

  • T072 Run bash scripts/check-ui-productization-coverage HEAD from the repository root.
  • T073 Run git diff --check from the repository root.
  • T074 Optionally run bash -n scripts/check-ui-productization-coverage.
  • 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/.
  • T076 Confirm every selected target image has a source screenshot/page report, target brief, and sidecar.
  • 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.
  • T078 Document full Pest/runtime suite not run because this spec is docs/image-only.
  • 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.